Spotify Web API client for Python 3

Related tags

Third-party APIs Wrapperspythonspotifyapi-client
Overview

logo

build status documentation status test coverage

Welcome to the GitHub repository of Tekore! We provide a client for the Spotify Web API for Python, complete with all available endpoints and authentication methods, async support and loads of additional features. Tekore allows you to interact with the API effortlessly. Here's five lines to get you full access and start playing your top songs.

import tekore as tk

conf = (client_id, client_secret, redirect_uri)
token = tk.prompt_for_user_token(*conf, scope=tk.scope.every)

spotify = tk.Spotify(token)
tracks = spotify.current_user_top_tracks(limit=10)
spotify.playback_start_tracks([t.id for t in tracks.items])

See our homepage on PyPI for more information about the package and its versions. Visit our online documentation on Read The Docs for tutorials, examples, package reference and a detailed description of features. Join our Discord community to ask for help or discuss just about anything related to Tekore. You can also ask a question on Stack Overflow.

Contributing

open issues issue resolution time

New contributors are always welcome! If you've found a bug or would like to propose a feature, please submit an issue. If you'd like to get more involved, you can start by cloning the most recent version from GitHub and installing it as an editable package.

$ git clone https://github.com/felix-hilden/tekore.git
$ cd tekore
$ pip install -e .[dev]

The last command installs all the necessary dependencies for development. For specialised uses, sets of extras can be installed separately. tests installs dependencies related to executing tests, docs is for building documentation locally, and checks contains tox and tools for static checking. The install can be verified by running all essential tasks with tox.

$ tox

Now a subset of tests have been run, and documentation has been built. A list of all individual tasks can be viewed with their descriptions.

$ tox -a -v

Please have a look at the following sections for additional information regarding specific tasks and configuration.

Documentation

Documentation can be built locally with Sphinx.

$ cd docs
$ make html

The main page index.html can be found in build/html. If tox is installed, this is equivalent to running tox -e docs.

Code style

A set of code style rules is followed. To check for violations, run flake8.

$ flake8 tekore

Style checks for docstrings and documentation files are also available. To run all style checks use tox -e lint.

Running tests

The repository contains a suite of test cases which can be studied and run to ensure the package works as intended.

$ pytest

For tox, this is the default command when running e.g. tox -e py.

Tests against the live Web API use environment variables for credentials. These tests manipulate your data and player, but try to restore previous state insofar as it is possible. Please refer to the description of each test class for details. In order to run all tests successfully, one must specify:

  • SPOTIFY_CLIENT_ID - client ID of a registered Spotify 3rd party application
  • SPOTIFY_CLIENT_SECRET - secret associated with that application
  • SPOTIFY_REDIRECT_URI - redirect URI whitelisted in application settings
  • SPOTIFY_USER_REFRESH - user refresh token with all scopes

In addition, playback tests require an active Spotify device that does not have a private session enabled and an empty song queue.

Optionally TEKORE_TEST_SKIP_IS_FAIL can be set to raise an error if some of the tests would be skipped because of the environment has not been configured.

To measure test coverage and view uncovered lines or branches run coverage.

$ coverage run
$ coverage report

This can be achieved with tox by running tox -e coverage.

Comments
  • Uploading to PyPi and other sources

    Uploading to PyPi and other sources

    I'm creating this issue to keep track of this API progress. I know it's too early to release it but this is helpful for people who want to use it via PyPi in their project. It'd also need a new name, as I told you in the original spotipy thread.

    Also, I wanted to let you know that once it's done I can take care of uploading and maintaining it in the AUR repos.

    consideration 
    opened by marioortizmanero 50
  • Async client

    Async client

    This PR provides Async support to Tekore, and will close #131 when complete.

    • [x] Structure for Async support
    • [x] Async implementation to all endpoints
    • [x] Async paging navigation
    • [x] Async authentication
    • [x] Async to RetryingSender
    • [x] Tests for async functionality
    • [x] Extensive documentation and tutorials on Sync/Async
    • [x] Provide boolean parameter for async: Spotify(asynchronous=True)
    opened by felix-hilden 26
  • Advertise type hints with py.typed

    Advertise type hints with py.typed

    From #109 (@HarrySky): I think this is a broader issue than only models, so let's have it in a separate issue.

    About type hints - it would be great to add py.typed file to package (PEP 561). It will show mypy that this package has type hints and it will give more helpful analysis.

    • Create empty file tekore/py.typed
    • Add line to MANIFEST.in: include tekore/py.typed

    I think this could be a nice addition. However, I think our type hinting is not at the level that mypy would be happy with it. This has been discussed in #64 already, during which I decided not to change much for mypy. But maybe we ought to have another look. But I think with a py.typed there is a notion that the type hints are absolutely correct, which they most certainly are not at the moment. We've got most of it right, but for simplicity for example the client endpoints only return e.g. FullTrack instead of Union[FullTrack, Coroutine[None, None, FullTrack]]. I'll look into it.

    enhancement wontfix 
    opened by felix-hilden 23
  • Renaming Spotipy

    Renaming Spotipy

    The situation has changed a bit recently. Plamere, the original owner of the Spotipy package has responded and given rights to the original repository. So it might very well be that development will continue there. A few contributors were invited, myself included. But they do not share the vision I based my version on. The third new contributor, Harrison has yet to express his views on the matter. In case this repository parts ways with the original package, we need a new name. Better to prepare already.

    What should that potential new name be? I have some ideas, but I'd love to hear any suggestions as well!

    • spotipy3: An obvious candidate. This library is based on Plamere's, so it could carry on the name. It shows the history with spotipy and implies an improvement over the previous version.
    • spoton: Another name combination of Spotify and Python. Unique (and available on PyPI), easier to write and is coincidentally also the adjective "spot on", again implying good quality.

    How much easier to write? A lot actually. Using two hands on a qwerty keyboard "spotipy3" requires s+po+t+ip+y3 = 5 steps or bursts or hand positions, "spoton" only s+po+t+on = 4. In addition, "spoton" only requires the right hand to burst twice in the same direction, while "spotipy3" requires both directions (p->o + i->p) on the right hand and one burst from the left. Don't know about you guys, but to me this is worth considering.

    Renaming should not be such a big deal yet. We've had no releases. Documentation and other things need to be updated, but GitHub provides automatic redirects from felix-hilden/spotipy to whatever it shall be.

    We are running out of Pythonic library names soon, now Spotipy, Spoton, Pyfy, next Fyton :D

    consideration 
    opened by felix-hilden 19
  • Proof-of-Concept async version for album API endpoints

    Proof-of-Concept async version for album API endpoints

    To check it run python3.7 async_test.py

    I had to create async versions for most of the classes, since there is a need to use async/await keywords. We can open conversation about async now :)

    P.S. credentials in PR are random, no worries, replace them

    opened by HarrySky 18
  • Refreshing client token

    Refreshing client token

    Currently the client token is "refreshed" the same way as user tokens in util.RefreshingToken. This will not work, as the token has no refresh token, but needs to be requested from the credentials again.

    The refresh token is None, which can be used to check if it is a client token. In that case, request a new one instead of trying to refresh.

    bug 
    opened by felix-hilden 15
  • Model fields and type hints

    Model fields and type hints

    Dataclass fields, and subsequently type hints are not shown on the documentation (example). It would be very useful to view them and even jump to other definitions with similar links that are available elsewhere.

    documentation waiting 
    opened by felix-hilden 14
  • Async and httpx support

    Async and httpx support

    Hey, just found this library - great work!

    100% tests coverage is great and 100% type-hints (but not just dicts and lists) and async support would be even better :smile:

    Did not found a project that has all three, so I written own wrapper for my pet-project with those requirements.

    But it has only 3 endpoints (user/me, player/currently-playing and OAuth2.0 methods) and I don't want to invent my own wheel (API wrapper), can I help with annotations and async support?

    enhancement 
    opened by HarrySky 13
  • Invalid / illegal URI

    Invalid / illegal URI

    trying to play a track but it is giving invalid URI

    Issue

    KeyError: 'Passed URL contains no parameter code!'

    Steps to reproduce

    import tekore as tk

    client_id = "id" client_secret = "sec" redirect_uri = "spotify:track:52xJxFP6TqMuO4Yt0eOkMz"

    conf = (client_id, client_secret, redirect_uri) token = tk.prompt_for_user_token(*conf, scope=tk.scope.every)

    spotify = tk.Spotify(token) tracks = spotify.current_user_top_tracks(limit=10) spotify.playback_start_tracks([t.id for t in tracks.items])

    bug invalid 
    opened by Abdulsamipy 12
  • User id is not parsed to be URL safe

    User id is not parsed to be URL safe

    Issue

    User id is not parsed to be URL safe. If a valid spotify user id contains a hashtag this results in a bad request to the API leading to 404: Service not found error.

    Expected behavior

    Spotify user id's can contain special (url-unsafe) characters. Most importantly for this example: User id's can start with a #. These characters should be properly escaped before making requests.

    Steps to reproduce

    user_id = '#validuserid'
spotify.playlists(user_id)
    bug 
    opened by SimonIlic 12
  • PrivateUser has no birthdate attribute

    PrivateUser has no birthdate attribute

    Issue

    I get a TypeError: __init__() got an unexpected keyword argument 'birthdate' while getting a PrivateUser through the current_user() method.

    The keys of the JSON dict from the API call are dict_keys(['birthdate', 'country', 'display_name', 'email', 'explicit_content', 'external_urls', 'followers', 'href', 'id', 'images', 'product', 'type', 'uri'])

    Expected behavior

    I should've gotten a PrivateUser.

    Steps to reproduce

    If applicable and possible, please provide a minimal working example.

    displayName = spotify.current_user().display_name
    bug track 
    opened by kddlb 12
  • Use Pydantic or Attrs

    Use Pydantic or Attrs

    It's getting painful to manually process every model. Let's use Pydantic (or look at Attrs and what they have to offer) for parsing and extra validation!

    change 
    opened by felix-hilden 1
  • Switch to using pyproject.toml

    Switch to using pyproject.toml

    Being the standard format, we should aim to define the project with a pyproject.toml rather than a setup.py. If all tooling can handle the new format I think there is no reason to stick with setup.py, but I recall tox having some configuration issues with it. So let's investigate.

    style 
    opened by felix-hilden 4
  • Use Black and isort for automatic formatting

    Use Black and isort for automatic formatting

    We should format code automatically. I already tried out a configuration in #183, but due to some issues with Black (psf/black#1054 & psf/black#1288) we'll be delaying that.

    Here's the configuration in tox.ini:

    [flake8]
select = C,E,F,W,B,B9
ignore = B305,E203,E402,E501,E722,F401,W503

[isort]
line_length=88
use_parentheses=True
multi_line_output=3
lines_between_types=1
include_trailing_comma=True
known_third_party=requests,httpx
known_first_party=tekore
force_grid_wrap=0

[testenv:black-run]
description = Run Black formatting on code
whitelist_externals = black
commands = black --target-version py36 .

[testenv:black-check]
description = Check code formatting
whitelist_externals = black
commands = black --target-version py36 --check .

[testenv:isort-run]
description = Run isort formatting on imports
whitelist_externals = isort
commands = isort -y

[testenv:isort-check]
description = Check import formatting
whitelist_externals = isort
commands = isort --check-only

[testenv:format]
description = Run all code formatting
whitelist_externals =
    isort
    black
commands =
    isort -y
    black --target-version py36 .
    style 
    opened by felix-hilden 9
Releases(v4.5.0)
Owner
Felix Hildén
Computer vision and pattern recognition graduate, a past-time programmer.
Felix Hildén
GitHub Repository https://tekore.rtfd.org
A Python library for rendering ASS subtitle file format using libass.

ass_renderer A Python library for rendering ASS subtitle file format using libass. Installation pip install --user ass-renderer Contributing # Clone

1 Nov 02, 2022
An Async Bot/API wrapper for Twitch made in Python.

TwitchIO is an asynchronous Python wrapper around the Twitch API and IRC, with a powerful command extension for creating Twitch Chat Bots. TwitchIO co

TwitchIO 590 Jan 03, 2023
Decrypt PSSE layer of PSM Games (on PC)

psse-decrypt Decrypt PSSE layer of PSM Games (on PC) Works on Unity and PSM games, and meets all requirements of: https://github.com/vita-nuova/bounti

Bluzume 32 Oct 11, 2022
An asyncio Python wrapper around the Discord API, forked off of Rapptz's Discord.py.

Novus A modern, easy to use, feature-rich, and async ready API wrapper for Discord written in Python. A full fork of Rapptz's Discord.py library, with

Voxel Fox 60 Jan 03, 2023
This repository contains the best Data Science free hand-picked resources to equip you with all the industry-driven skills and interview preparation kit.

Best Data Science Resources Hey, Data Enthusiasts out there! Finally, after lots of requests from the community I finally came up with the best free D

Mohit Kumar 415 Dec 31, 2022
Search all history of Chrome in terminal

Chrotry Search all history of Chrome in terminal. Demo Usages Move the Chrome history file to current directory by running move_history.sh Rename hist

Xiaoxu HU 2 Jun 13, 2022
This is RequestTrackerBot and it used for tracking request made by user in a group

This is a Request Tracker Bot repo, It is for those who upload content like movies, anime, etc. It can be used for tracking request of content that your members asked for.

Abhijeet 27 Dec 29, 2022
This is a Anti Channel Ban Robots

AntiChannelBan This is a Anti Channel Ban Robots delete and ban message sent by channels Heroku Deployment 💜 Heroku is the best way to host ur Projec

BᵣₐyDₑₙ 25 Dec 10, 2021
An api, written in Python, for Investopedia's paper trading stock simulator.

investopedia-trading-api An API, written in Python, for Investopedia's paper trading stock simulator. Pull requests welcome. This library is now Pytho

Kirk Thaker 178 Jan 06, 2023
A Simple Telegram Inline Torrent Search Bot by @infotechIT

Torrent-Search-RoBot A Simple Telegram Inline Torrent Search Bot by @infotechIT. Torrent API Using api.infotech.wtf API Host Bot Deploy to Heroku Clic

InfoTech 0 May 05, 2022
A program that generates discord.py code

discord-py-generator A program that generates discord.py code Setup in cmds.txt file add your user id, client id and bot token you can change the bot

3 Dec 15, 2022
Polar devices Python API and CLI.

loophole - Polar devices API About Python API for Polar devices. Command line interface included. Tested with: A360 Loop M400 Installation pip install

[roscoe] 145 Sep 14, 2022
Simple stock price analytics

mune · Mune is an open source python web application built to analyze stocks, named after Homma Munehisa. Currently, the forecasting component is powe

Richard Hong 14 Aug 30, 2021
A Python library for the Buildkite API

PyBuildkite A Python library and client for the Buildkite API. Usage To get the package, execute: pip install pybuildkite Then set up an instance of

Peter Yasi 29 Nov 30, 2022
Quot-a-lecture - Lecture transcript question extraction

Setup virtualenv venv source venv/bin/activate pip install -r requirements.txt

Pratyaksh Sharma 5 Sep 12, 2022
Python client library for Google Maps API Web Services

Python Client for Google Maps Services Description Use Python? Want to geocode something? Looking for directions? Maybe matrices of directions? This l

Google Maps 3.8k Jan 01, 2023
A Discord bot that may save your day by predicting it.

Sage A Discord bot that may save your day by predicting it.

1 Nov 17, 2022
Tinyman Python SDK

tinyman-py-sdk Tinyman Python SDK Design Goal This SDK is designed for automated interaction with the Tinyman AMM. It will be most useful for develope

Tinyman 113 Dec 30, 2022
Zaid Vc Player Allows u to steam Songs/music on vc chat

ᴢᴀɪᴅ ᴠᴄ ᴘʟᴀʏᴇʀ 🔥 SORRY FOR OUR PROJECTS DELETED BY GITHUB FLAGGED ᴢᴀɪᴅ ᴠᴄ ᴘʟᴀᴇʀ ɪꜱ ᴀ ᴛᴇʟᴇɢʀᴀᴍ ᴘʀᴏᴊᴇᴄᴛ ʙᴀꜱᴇᴅ ᴏɴ ᴘʏʀᴏɢʀᴀᴍ ꜰᴏʀ ᴘʟᴀʏ ᴍᴜꜱɪᴄꜱ ɪɴ ᴠᴄ ᴄʜᴀᴛꜱ..

Zaid 117 Dec 29, 2022
Melissa Songs is a telegram bot to easily find songs sending music snippets and search tracks 💃🏽🎵

Find songs on Telegram, like on Shazam... 😎 Open on telegram · Report Bug · Request Feature ⬇️ Installation To get a local copy installed and working

Joaquim Roque 21 Nov 10, 2022