Spotiwise

A Python object convenience layer on top of spotipy

Spotiwise wraps spotipy.Spotify and returns rich Python objects (SpotiwiseTrack, SpotiwiseArtist, SpotiwiseAlbum, SpotiwisePlaylist, SpotiwiseUser, SpotiwiseItem, SpotiwisePlayback) instead of raw JSON dicts for the methods where that's useful — no more track['artists'][0]['name'], just track.artist.

Everything else — authentication, retries, pagination helpers, the full endpoint surface — is spotipy itself. spotiwise.Spotify is a subclass of spotipy.Spotify, so any method spotiwise doesn't explicitly wrap is inherited unchanged and returns the same raw JSON spotipy always has. Because the object-wrapping methods just call super() under the hood, spotiwise tracks spotipy's upstream changes by bumping a dependency version rather than hand-porting a fork.

Installation

uv add spotiwise

or with pip:

pip install spotiwise

Quick Start

Without user authentication

export SPOTIPY_CLIENT_ID=client_id_here
export SPOTIPY_CLIENT_SECRET=client_secret_here

fromspotiwiseimportSpotify, SpotifyClientCredentialssp=Spotify(auth_manager=SpotifyClientCredentials())
track=sp.track('4iV5W9uYEdYUVa79Axb7Rh')
print(f"{track.name} by {track.artist} ({track.album.name})")

With user authentication

export SPOTIPY_CLIENT_ID=client_id_here
export SPOTIPY_CLIENT_SECRET=client_secret_here
export SPOTIPY_REDIRECT_URI=redirect_uri_here

fromspotiwiseimportSpotify, SpotifyOAuthsp=Spotify(auth_manager=SpotifyOAuth(scope="user-library-read"))
fortrackinsp.current_user_saved_tracks():
print(f"{track.artist} - {track.name}")

SpotifyOAuth, SpotifyClientCredentials, SpotifyPKCE, SpotifyImplicitGrant, and SpotifyException are all re-exported straight from spotipy — spotiwise doesn't maintain its own copies, so auth behaves exactly like spotipy's own documentation describes.

What's wrapped

Methods that map naturally onto an object return one — track/tracks, artist/artists, album/albums, artist_top_tracks, artist_related_artists, user, me/current_user, playlist, playlist_items, current_user_playlists, user_playlists, featured_playlists, new_releases, current_playback/currently_playing/current_user_playing_track, current_user_saved_albums/_tracks, current_user_followed_artists, and current_user_recently_played.

Everything else (search, playback controls, show/episode endpoints, recommendations, audio features, saved-item mutators, ...) is inherited from spotipy.Spotify unchanged and returns raw JSON — refer to spotipy's documentation for those.

Reporting Issues

For questions or bugs specific to the object-wrapping layer, file an issue here.

For anything about the underlying Spotify Web API or spotipy's own methods, see spotipy's documentation and issue tracker.