Sync/Async API wrapper for Spotify's web API

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for omarryhan from gravatar.com omarryhan

Unverified details

These details have not been verified by PyPI
Project links
Meta
Classifiers

Project description

Logo

Build Status Software License Code style: black Downloads Monthly Downloads

Welcome 👋

Pyfy is a Sync + Async Pythonic Spotify Client that focuses on ease of use in personal projects and API stability and security for production grade codebases.

Setup ⚙️

$ pip install pyfy

Quick Start 🎛️

Sync:

from pyfy import Spotify

spt = Spotify('your_access_token')

spt.play()
spt.volume(85)
spt.next()
spt.pause()

Async:

import asyncio
from pyfy import AsyncSpotify

spt = AsyncSpotify('your_access_token')

async def search():
    return await spt.search('A tout le monde')

search_result = asyncio.run(search())

Getting Started 👩

You should start by creating client credentials from Spotify's Developers console

Next edit your application's settings and set a Redirect URL. If it's for personal use then set it as:

http://localhost:9000 Port can be any port of choice, not necessarily 9000

Next, copy your:

  1. Client ID
  2. Client Secret
  3. Redirect URL (That you just set)

Next, figure out the scopes that you think you'll need from here: https://developer.spotify.com/documentation/general/guides/scopes/

e.g. ["user-library-modify", "app-remote-control"]

Next, follow the first authentication scheme from below (it's the one you'll most likely need, unless you're sure otherwise)

Authentication Schemes 👩‍🎤

1. Authorization Code Flow (OAuth2) (recommended)

Suitable if you want to access user-related resources. e.g. user-playlists, user-tracks etc.

Click here for full working examples with Sanic(async) and Flask(sync)

from pyfy import Spotify, ClientCreds, UserCreds, AuthError, ApiError

client = ClientCreds(
    client_id='clientid',
    client_secret='client_secret',
    redirect_uri='https://localhost:9000",
    scopes=["user-library-modify", "app-remote-control"]
)
spt = Spotify(client_creds=client)

def authorize():
    # Fist step of OAuth, Redirect user to spotify's authorization endpoint
    if spt.is_oauth_ready:
        return redirect(spt.auth_uri())

# Authorization callback
def callback(grant):
    try:
        user_creds = spt.build_credentials(grant=grant)
    except AuthError as e:
        abort(401)
        logging.info(e.msg)
        logging.info(e.http_response)
    else:
        db.insert(user_creds)
        return redirect(url_for_home)

def get_user_tracks():
    try:
        return json.dumps(spt.user_tracks())
    except ApiError:
        abort(500)

2. User's Access Token get from here

Same as the Authorization Code Flow above but without a refresh token. Suitable for quick runs.

from pyfy import Spotify
spt = Spotify('your access token')

3. Client Credentials Flow (OAauth2):

Suitable for when you want to access public information quickly. (Accessing user information is porhibited using this method)

from pyfy import ClientCreds, Spotify

client = ClientCreds(client_id=client_id, client_secret=client_secret)
spt = Spotify(client_creds=client)
spt.authorize_client_creds()

API endpoints 🌐

Albums:

Artists:

Browse:

Episodes:

Follow:

User Library:

Personalization:

Player:

Playlists:

Search:

Shows:

Tracks:

Users Profile:

Pagination 📖

from pyfy import Spotify

user_creds = {'access_token': '...', 'refresh_token': '....'}

spt = Spotify(user_creds=user_creds)

user_top_tracks = spt.user_top_tracks(limit=5)

next_page_1 = spt.next_page(user_top_tracks)
next_page_2 = spt.next_page(next_page_1)

previous_page_1 = spt.previous_page(next_page_2)
previous_page_1 === next_page_1  # True

Documentation 📑

For a detailed documentation of Pyfy's API, please visit: https://pyfy.readthedocs.io/en/latest where you'll find:

Backward Incompatibility Notices

V2:

  1. Removed Spotify.oauth_uri property in favor of Spotify.auth_uri method.

  2. Spotify.play() now accepts, track_ids, artist_ids etc. instead of resource_ids + resource_names

  3. Oauth2 state handling:

    • Removed deprecated enforce_state_check functionality

    • Removed state attribute from user_creds

    • Oauth2 state checking is no longer done by Pyfy's client and should be handled manually

Testing 👩‍🔬:

Please visit: https://pyfy.readthedocs.io/en/latest/#testing

Contributors

Big thank you to our amazing contributors:

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for omarryhan from gravatar.com omarryhan

Unverified details

These details have not been verified by PyPI
Project links
Meta
Classifiers

Release history Release notifications | RSS feed

2.2.0

2.1.0

2.0.9

This version

2.0.8

2.0.7

2.0.6

2.0.5

2.0.4

2.0.3

2.0.2

2.0.1

2.0.0

1.2.3

1.2.2

1.2.1

1.2.0

1.1.3

1.1.2

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyfy-2.0.8.tar.gz (50.0 kB view details)

Uploaded Source

File details

Details for the file pyfy-2.0.8.tar.gz.

File metadata

  • Download URL: pyfy-2.0.8.tar.gz
  • Upload date:
  • Size: 50.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.2

File hashes

Hashes for pyfy-2.0.8.tar.gz
Algorithm Hash digest
SHA256 e31e6adf1cffc0b32d6cd0542c7b616a1cd18b1e08ab904998d6b894bf0edaf9
MD5 c5bf3f8cacabed89215476a2ecc44aac
BLAKE2b-256 c4650c776d2c713a2888c57b99ee1632f75ebad005d5d58365720dae05f8a990

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page