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 Twitter bot written in Python using Tweepy and hosted on a server.

A Twitter bot written in Python using Tweepy. It can like and/or retweet tweets that contain single or multiple keywords and hashtags.

anniedotexe 11 Dec 15, 2022
Automate UCheck COVID-19 self-assessment form submission

ucheck Automate UCheck COVID-19 self-assessment form submission. Disclaimer ucheck automatically completes the University of Tornto's UCheck COVID-19

Ira Horecka 15 Nov 30, 2022
SSH-Restricted deploys an SSH compliance rule (AWS Config) with auto-remediation via AWS Lambda if SSH access is public.

SSH-Restricted SSH-Restricted deploys an SSH compliance rule with auto-remediation via AWS Lambda if SSH access is public. SSH-Auto-Restricted checks

Adrian Hornsby 30 Nov 08, 2022
Official Python client for the MonkeyLearn API. Build and consume machine learning models for language processing from your Python apps.

MonkeyLearn API for Python Official Python client for the MonkeyLearn API. Build and run machine learning models for language processing from your Pyt

MonkeyLearn 157 Nov 22, 2022
Web3 Pancakeswap Sniper & honeypot detector Take Profit/StopLose bot written in python3, For ANDROID WIN MAC & LINUX

🏆 Pancakeswap BSC Sniper Bot web3 with honeypot detector (ANDROID WINDOWS MAC LINUX) 🥇 ⭐️ ⭐️ ⭐️ First SNIPER BOT for ANDROID & WINDOWS with honeypot

HYDRA 2 Dec 24, 2021
Production Ontology Merging (PrOM) Framework

Production Ontology Merging (PrOM) Framework OWL 2 DL ontology merging framework tailored to the production domain Features preprocessing: translation

4 Nov 02, 2022
A jokes api python module

A jokes api python module

Fayas Noushad 3 Nov 28, 2021
Updater for PGCG (Paradox Game Converters Group) converters written in Python.

Updater Updater for PGCG (Paradox Game Converters Group) converters written in Python. Needs to be put inside an "Updater" directory in the root conve

Paradox Game Converters 2 Jan 10, 2022
A nuker for Roblox accounts.

Roblox-Nuker A nuker for Roblox accounts. Made by Ice Bear#0167 Usage I would recommend running in replit (https://replit.com) as it is deprecated in

7 May 10, 2022
Scheduled Block Checker for Cardano Stakepool Operators

ScheduledBlocks Scheduled Block Checker for Cardano Stakepool Operators Lightweight and Portable Scheduled Blocks Checker for Current Epoch. No cardan

SNAKE (Cardano Stakepool) 4 Oct 18, 2022
A wrapper for slurm especially on Taiwania2 (HPC CLI)A wrapper for slurm especially on Taiwania2 (HPC CLI)

TWCC-slurm-wrapper A wrapper for slurm especially on Taiwania2 (HPC CLI). For Taiwania2 (HPC CLI) usage, please refer to here. (中文) How to Install? gi

Chi-Liang, Liu 5 Oct 07, 2022
A Python library for miHoYo bbs and HoYoLAB Community

A Python library for miHoYo bbs and HoYoLAB Community. genshin 原神签到小助手

384 Jan 05, 2023
Wrapper for Gismeteo.ru.

pygismeteo Обёртка для Gismeteo.ru. Асинхронная версия здесь. Установка python -m pip install -U pygismeteo Документация https://pygismeteo.readthedoc

Almaz 7 Dec 26, 2022
Auto Join: A GitHub action script to automatically invite everyone to the organization who comment at the issue page.

Auto Invite To Org By Issue Comment A GitHub action script to automatically invite everyone to the organization who comment at the issue page. What is

Max Base 6 Jun 08, 2022
Discord bot for Ukrfans Discord server

Ukrfans Discord Bot Discord bot for Ukrfans Discord server. 💡 Prerequisites Python ⚙️ Build & Run Create an .env file in the root directory and add t

3 Jun 24, 2022
A WhatsApp Crashing Tool for Termux

CrashW A WhatsApp Crashing Tool For Termux Users Installing : apt update && apt upgrade -y pkg install python3 pkg install git git clone git://gith

Gokul Mahato 20 Dec 27, 2022
A Discord bot to easily and quickly format your JSON data

Invite PrettyJSON to your Discord server Table of contents About the project What is JSON? What is pretty printing? How to use Input options Command I

Sem 4 Jan 24, 2022
Google Sheets Python API

Google Spreadsheets Python API v4 Simple interface for working with Google Sheets. Features: Open a spreadsheet by title, key or url. Read, write, and

Anton Burnashev 6.2k Dec 30, 2022
The Python client library for the Tuneup Technology App.

Tuneup Technology App Python Client Library The Python client library for the Tuneup Technology App. This library allows you to interact with the cust

Tuneup Technology 0 Jun 29, 2022
Create CDK projects with projen

The Projenator: I'll be back! Description This is a CDKv2 project that takes the grind out of setting up new cdk projects/implementations by using aut

Andrew 2 Dec 11, 2021