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
:snake: A simple library to fetch data from the iTunes Store API made for Python >= 3.5

itunespy itunespy is a simple library to fetch data from the iTunes Store API made for Python 3.5 and beyond. Important: Since version 1.6 itunespy no

Fran González 56 Dec 22, 2022
checks anilist for available usernames (200rq/s)

Anilist checker Running the program Set a path to the extracted files Install the packages with pip install -r req.txt Run the script by typing python

gxzs 1 Oct 13, 2021
A multifunctional bot for Discord

Um bot multifuncional e divertido para Discord Estive desenvolvendo o BotDaora desde o começo de outubro de 2021 e agora ele é open-source! tomei essa

Ruan 4 Dec 28, 2021
Bot for tenhou.net riichi mahjong server written in Python

[Tests coverage] Bot was tested with Python 3.7+ and PyPy3, we are not supporting Python 2. What do we have here? Mahjong hands calculation You can fi

190 Jan 06, 2023
Automatic login to Microsoft Teams conferences

Automatic login to Microsoft Teams conferences

Xhos 1 Jan 24, 2022
A simple python script for rclone. Use multiple Google Service Accounts and cycle through them.

About GSAclone GSAclone is a simple python script for rclone, written with the purpose of using multiple Google service accounts on Google Drive and "

Shiro39 6 Feb 25, 2022
Messing around with GitHub API to look at omicron build times

gh-workflow-runs This is a very simple tool to dump out basic information about workflow runs for a GitHub repo. The structure is based on gh-subscrip

David Pacheco 1 Nov 30, 2021
Info gathering | API hacketarget.com

InfoFetch Info gathering | API hackertarget.com set-up: apt-get install python3 pip3 install requests apt-get install git git clone https://github.com

Muhammed Rizad 4 Nov 22, 2021
Rotten Tomatoes API for Python

rottentomatoes.py rottentomatoes offers an easy-to-use Python wrapper to interact with the Rotten Tomatoes API. Before you try and use the API, make s

Zach Williams 88 Dec 15, 2022
Simple Python Auto Follow Bot

Instagram-Auto-Follow-Bot Description Một IG BOT đơn giản. Tự động follow những người mà bạn muốn cướp follow. Tự động unfollow. Tự động đăng nhập vào

CodingLinhTinh 3 Aug 27, 2022
eBay Scraper Homework 3 With Python

eBay Scraper Homework 3 Description of Code My ebay-dl.py file is programmed with python to download 6 key pieces of information - name, if there are

1 Nov 10, 2021
Converts a text file of songs to a playlist on your Spotify account.

Playlist Converter Convert a text file of songs to a playlist on your Spotify account. Create your playlists faster instead of manually searching for

Priya Aggarwal 18 Dec 21, 2022
Python wrapper for Coinex APIs

coinexpy - Python wrapper for Coinex APIs Through coinexpy you can simply buy or sell crypto in your Coinex account Features place limit order place m

Iman Mousaei 16 Jan 02, 2023
A Python 2.7/3.x module for Amcrest Cameras using the SDK HTTP API.

A Python 2.7/3.x module for Amcrest Cameras using the SDK HTTP API. Amcrest and Dahua devices share similar firmwares. Dahua Cameras and NVRs also work with this module.

Marcelo Moreira de Mello 176 Dec 21, 2022
The best discord Nuk3r !

Discord - Nuker ☢️ Nuk3r ☢️ STEP 1 ✅ We go create discord bot ! [] Go on https://discord.com/developers/applications [] Set the name of your applica

2s.py 1 Apr 16, 2022
Discord bot ( discord.py ), uses pandas library from python for data-management.

Discord_bot A Best and the most easy-to-use Discord bot !! Some simple basic auto moderations, Chat functions. It includes a game similar to Casino, g

Jaitej 4 Aug 30, 2022
Request based Python module(s) to help with the Newegg raffle.

Newegg Shuffle Python module(s) to help you with the Newegg raffle How to use $ git clone https://github.com/Matthew17-21/Newegg-Shuffle $ cd Newegg-S

Matthew 45 Dec 01, 2022
Example of a discord bot in Python

discordbot.py Example of a discord bot in Python Requirements Python 3.8 or higher Discord Bot Setting Up Clone this repo or download the files Rename

Debert Jamie 1 Oct 23, 2021
ServiceX DID Finder Girder

ServiceX_DID_Finder_Girder Access datasets for ServiceX from yt Hub Finding datasets This DID finder is designed to take a collection id (https://gird

1 Dec 07, 2021
A simple Python wrapper for the archive.is capturing service

archiveis A simple Python wrapper for the archive.is capturing service. Installation pipenv install archiveis Python Usage Import it. import archi

PastPages 157 Dec 28, 2022