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
Python package for agilex robotics mobile base platform

This is Python API for Agilex Robotics Mobile base This is a python API for Can communication with Agilex Robotics Mobile base and controlling it. Sup

7 Sep 06, 2022
Tracker to check the covid shot slot availability in India and send mobile alerts via Twilio Messaging Service.

Cowin-Slot-Tracker Tracker to check the covid vaccine slot availability in India and send mobile notifications through Twilio Messaging Service. Requi

invalid username 27 Nov 12, 2022
Send embeds using your discord personal account

Welcome to Embed Sender πŸ‘‹ Send embeds using your discord personal account Install pip install -r requirements.txt Usage Put your discord token in ./

SkydenFly 11 Sep 07, 2022
Discord Mafia Game Bot using nextcord

Mafia-Bot Discord Mafia Game Bot using nextcord Features Mafia Game Game Replays Installation Run the following command to install required modules: p

Nian 6 Nov 19, 2022
A Python AWS Lambda Webhook listener that generates a permanent URL when an asset is created in Contentstack.

Webhook Listener A Python Lambda Webhook Listener - Generates a permanent URL on created assets. See doc on Generating a Permanent URL: https://www.co

Contentstack Solutions 1 Nov 04, 2021
A fast, distributed, high performance gradient boosting (GBT, GBDT, GBRT, GBM or MART) framework based on decision tree algorithms, used for ranking, classification and many other machine learning tasks.

Light Gradient Boosting Machine LightGBM is a gradient boosting framework that uses tree based learning algorithms. It is designed to be distributed a

Microsoft 14.5k Jan 08, 2023
Source code of u/pekofy_bot from reddit.

pekofy-bot Source code of u/pekofy_bot from reddit. Get more info about the bot here: https://www.reddit.com/user/pekofy_bot/comments/krxxol/pekofy_bo

32 Dec 25, 2022
Backend for Indipe client

Betsushi Betsu (εˆ₯), the japanese word meaning "another" and Shiharai (支払い) meaning "payment". Hence the name Betsushi was derived. Introduction This i

Sudodevs 3 Feb 09, 2022
A code that can make your 5 accounts stay 24/7 in a discord voice channel!

Voicecord A code that can make your 5 accounts stay 24/7 in a discord voice channel! Usage ・Fork the repo ・Clone it to replit ・Install the required pa

DraKenCodeZ 3 Jan 09, 2022
OpenSea Python Bot coded purely in Python3.

OpenSea Python Bot coded purely in Python3. It utilises everything from OpenSea API to continuously monitor NFT's. It can be used to snipe or monitor if something falls below floor value.

OpenSea Elite Sniper 20 Dec 29, 2021
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
Quickly and efficiently delete your entire tweet history with the help of your Twitter archive without worrying about the pointless 3200 tweet limit imposed by Twitter.

Twitter Nuke Quickly and efficiently delete your entire tweet history with the help of your Twitter archive without worrying about the puny and pointl

Mayur Bhoi 73 Dec 12, 2022
A Simple Advance Auto Filter Bot Complete Rewritten Version Of Adv-Filter-Bot

Adv Auto Filter Bot This Is Just An Simple Advance Auto Filter Bot Complete Rewritten Version Of Adv-Filter-Bot.. Just Sent Any Text As Query It Will

TeamShadow 4 Dec 10, 2021
Tomli is a Python library for parsing TOML. Tomli is fully compatible with TOML v1.0.0.

Tomli A lil' TOML parser Table of Contents generated with mdformat-toc Intro Installation Usage Parse a TOML string Parse a TOML file Handle invalid T

Taneli Hukkinen 313 Dec 26, 2022
:spaghetti: Pastas is an open-source Python framework for the analysis of hydrological time series.

Pastas: Analysis of Groundwater Time Series Pastas: what is it? Pastas is an open source python package for processing, simulating and analyzing groun

Pastas 277 Dec 29, 2022
Telegram bot to stream videos in telegram voicechat for both groups and channels

Telegram bot to stream videos in telegram voicechat for both groups and channels. Supports live streams, YouTube videos and telegram media. With record stream support, Schedule streams, and many more

ALBY 9 Feb 20, 2022
Bringing Ethereum Virtual Machine to StarkNet at warp speed!

Warp Warp brings EVM compatible languages to StarkNet, making it possible to transpile Ethereum smart contracts to Cairo, and use them on StarkNet. Ta

Nethermind 700 Dec 26, 2022
It connects to Telegram's API. It generates JSON files containing channel's data, including channel's information and posts.

It connects to Telegram's API. It generates JSON files containing channel's data, including channel's information and posts. You can search for a specific channel, or a set of channels provided in a

Esteban Ponce de Leon 75 Jan 02, 2023
π—–π π¦π©π πžπ₯ 𝝦π—₯πžπ—–π½Β°β„’οΈ πŸ‡±πŸ‡° Is An All In One Media Inline Bot Made For Inline Your Media Effectively With Some Advance Security Toolsβ™₯️

π—–π π¦π©π πžπ₯ 𝝦π—₯πžπ—–π½Β° ℒ️ πŸ‡±πŸ‡° π—™π—˜π π©π—¨π—₯π—˜π—¦ Auto Filter IMDB Admin Commands Broadcast Index IMDB Search Inline Search Random Pics Ids & User I

KΙͺκœ±α΄€Κ€α΄€ Pα΄‡κœ±α΄€Ι΄α΄ŠΙͺα΄›Κœ Pᴇʀᴇʀᴀ 〄 13 Jun 21, 2022
RichWatch is wrapper around AWS Cloud Watch to display beautiful logs with help of Python library Rich.

RichWatch is TUI (Textual User Interface) for AWS Cloud Watch. It formats and pretty prints Cloud Watch's logs so they are much more readable. Because

21 Jul 25, 2022