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 Tumblr API v2 Client

PyTumblr Installation Install via pip: $ pip install pytumblr Install from source: $ git clone https://github.com/tumblr/pytumblr.git $ cd pytumblr $

Tumblr 677 Dec 21, 2022
A bot to share Facebook posts.

bot_share_facebook a bot to share Facebook posts. install & clone untuk menjalankan anda bisa melalui terminal contohnya termux, cmd, dan terminal lai

Muhammad Latif Harkat 7 Dec 07, 2022
An Advanced Telegram Bot to Play Radio & Music in Voice Chat. This is Also The Source Code of The Bot Which is Being Used For Playing Radio in @AsmSafone Channel ❤️

Telegram Radio Player V3 An Advanced Telegram Bot to Play Nonstop Radio/Music/YouTube Live in Channel or Group Voice Chats. This is also the source co

SAF ONE 421 Jan 05, 2023
Make your Pass (sanitaire) Fun Again

Make Your Pass (Sanitaire) Fun Again Customize your Pass Sanitaire (French name for EU digital Covide19 Certificate) with colors and images, thus make

101 Dec 01, 2022
A powerful, cool and well-made userbot for your Telegram profile with promising extension capabilities.

Telecharm userbot A powerful, fast and simple Telegram userbot written in Python 3 and based on Pyrogram 1.X. Currently in active WIP state, so feel f

Daniil Kovalenko 16 Dec 01, 2022
Wats2PDF - Convert whatsapp exported chat(without media) into a readable pdf format

Wats2PDF convert whatsApp exported chat into a readable pdf format. convert with

5 Apr 26, 2022
Asynchronous Python API Wrapper for phisherman.gg

Asynchronous Python API Wrapper for phisherman.gg

Qrista Labs 4 Apr 30, 2022
Open API to list Viet Nam administrative divisions

Viet Nam province API Homepage: https://provinces.open-api.vn This is online tool to let my VietnamProvinces library reach more users. VietnamProvince

Nguyễn Hồng Quân 52 Dec 05, 2022
To dynamically change the split direction in I3/Sway so as to split new windows automatically based on the width and height of the focused window

To dynamically change the split direction in I3/Sway so as to split new windows automatically based on the width and height of the focused window Insp

Ritin George 6 Mar 11, 2022
A Python SDK for connecting devices to Microsoft Azure IoT services

V2 - We are now GA! This repository contains code for the Azure IoT SDKs for Python. This enables python developers to easily create IoT device soluti

Microsoft Azure 381 Dec 30, 2022
A script that writes automatic instagram comments under a post

Send automatic messages under a post on instagram Instagram will rate limit you after some time. From there on you can only post 1 comment every 40 se

Maximilian Freitag 3 Apr 28, 2022
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
A CLI tool to transfer, sync, and backup playlists on music streaming services

unitunes A command-line interface tool to manage playlists across music streaming services. Introduction unitunes manages playlists across streaming s

Victor Tao 50 Jan 07, 2023
This software's intent is to automate all activities related to manage Axie Infinity Scholars. It is specially aimed to mangers with large scholar roasters.

Axie Scholars Utilities This software's intent is to automate all activities related to manage Scholars. It is specially aimed to mangers with large s

Ferran Marin 153 Nov 16, 2022
A simple Discord Mass-Ban that's still working with Member Scraper.

Mass-Ban [!] This was made for education / you can use for revenge. Please don't skid it. [!] If you want to use it, please use member scraper before

WoahThatsHot 1 Nov 20, 2021
Python3 wrapper for the Sibyl System antispam API for telegram

SibylSystem-Py Python3 wrapper for the Sibyl System antispam API for telegram Installation pip install sibylsystem Usage from SibylSystem import

Kaizoku 6 Nov 04, 2022
A Fork of Gitlab's Permifrost tool for managing Snowflake Permissions

permifrost-fork This is a fork of the GitLab permifrost project. As the GitLab team is not currently maintaining the project, we've taken on maintenac

Hightouch 7 Oct 13, 2021
Facebook fishing on telegram bot

Facebook-fishing Facebook fishing on telegram bot تثبيت الاداة pkg update -y pkg upgrade -y pkg install git -y pkg install python -y git clone https:/

sadamalsharabi 7 Oct 18, 2022
Framework to make using Bottle less time-consuming and easier

A class for the Bottle API to reduce clutter and difficulty while creating a website.

Tygzy 0 Dec 26, 2022
May or may not be work🚶

AnyDLBot There are multiple things I can do: 👉 All Supported Video Formats of https://rg3.github.io/youtube-dl/supportedsites.html 👉 Upload as file

Arun 2 Nov 16, 2021