sung.base

Base functionalities for the sung package.

This module provides foundational tools and abstractions for interacting with Spotify’s API. It includes classes and functions to search for tracks, manage playlists, and handle Spotify track metadata. The utilities here are designed to integrate seamlessly with Spotify’s API and streamline data extraction and manipulation.

Key Components:

• search_tracks: A function to perform searches on Spotify, supporting filters such as year, genre, and market.

• TracksBase: A base class for managing collections of Spotify tracks, providing a dictionary-like interface with additional utilities for metadata handling.

• Tracks: A concrete implementation of TracksBase that uses track IDs or track metadata.

• PlaylistReader and Playlist: Classes for managing Spotify playlists, offering read-only and mutable interfaces respectively.

• Utility functions and constants for managing Spotify clients and data extraction.

This module is foundational for building higher-level operations within the sung package.

Functions

delete_playlist(playlist_id[, verbose, ...])
process_track_columns(df)
search_tracks(query[, egress, search_type, ...])	Search for tracks on Spotify.
track_ids_to_metas(track_ids, client)	Convert track IDs to track metadata using the Spotify client.
track_metadata(track_id, *[, client])
track_metas_to_track_ids(track_metas)	Extract track IDs from track metadata.

Classes

Playlist(playlist_id, *[, client])	A Spotify playlist with mutable mapping interface.
PlaylistReader(playlist_id, *[, client])	Read-only access to a Spotify playlist.
SpotifyDacc([client])
Tracks(tracks, *[, client])	A collection of Spotify tracks represented by track IDs or track metadata.
TracksBase(tracks, *[, client])	Base class representing a collection of Spotify tracks.

class sung.base.Playlist(playlist_id, *, client=None)

Bases: PlaylistReader, MutableMapping[str, dict[str, Any]]

A Spotify playlist with mutable mapping interface.

classmethod create_from_track_list(track_list=(), playlist_name='New Playlist', public=True, *, client=None, user_id=None)

Create a new playlist from a list of track IDs.

Parameters:

• track_list (Sequence[str]) – A list of track IDs to add to the playlist.

• playlist_name (str) – The name of the new playlist.

• public (bool) – Whether the playlist should be public.

• client (Any | None) – The Spotify client to use for creating the playlist.

• user_id (-) – The user ID of the playlist owner.

Return type:

Playlist

class sung.base.PlaylistReader(playlist_id, *, client=None)

Bases: Tracks, Mapping[str, dict[str, Any]]

Read-only access to a Spotify playlist.

class sung.base.Tracks(tracks, *, client=None)

Bases: TracksBase

A collection of Spotify tracks represented by track IDs or track metadata.

class sung.base.TracksBase(tracks, *, client=None)

Bases: Mapping[str, dict[str, Any]]

Base class representing a collection of Spotify tracks.

property audio_features

Track-level audio features keyed by track id.

Returns {} and emits a one-time warning if Spotify rejects the request (403) — a known restriction for apps registered after the Nov 2024 Web API deprecation. Callers should treat audio features as best-effort and fall back to metadata-only paths when empty.

dataframe(key=slice(None, None, None), *, front_columns=('name', 'artists_names', 'duration_ms', 'popularity', 'explicit', 'album_name', 'album_release_date', 'album_release_year', 'added_at_date', 'url', 'artist_list', 'first_artist', 'first_letter', 'id'), back_columns=('type', 'episode', 'track', 'album', 'disc_number', 'track_number', 'artists', 'preview_url', 'uri', 'href', 'available_markets', 'external_ids', 'external_urls'))

Get tracks metadata for given key(s), as a pandas DataFrame.

By default, will return all tracks in the collection.

Return type:

DataFrame

meta_dataframe(key=slice(None, None, None), *, front_columns=('name', 'artists_names', 'duration_ms', 'popularity', 'explicit', 'album_name', 'album_release_date', 'album_release_year', 'added_at_date', 'url', 'artist_list', 'first_artist', 'first_letter', 'id'), back_columns=('type', 'episode', 'track', 'album', 'disc_number', 'track_number', 'artists', 'preview_url', 'uri', 'href', 'available_markets', 'external_ids', 'external_urls'))

Get tracks metadata for given key(s), as a pandas DataFrame.

By default, will return all tracks in the collection.

Return type:

DataFrame

sung.base.search_tracks(query, egress=functools.partial(<function glom>, spec='tracks.items', default=None), *, search_type='track', market=None, year=None, genre=None, limit=20, offset=0, client=<function get_spotify_client>)

Search for tracks on Spotify.

Parameters:

• the (- query - the search query (see how to write a query in) – official documentation)

• return. (- offset - the index of the first item to)

• 'from_token'. (- market - An ISO 3166-1 alpha-2 country code or the string)

• return.

• return.

sung.base.track_ids_to_metas(track_ids, client)

Convert track IDs to track metadata using the Spotify client.

sung.base.track_metas_to_track_ids(track_metas)

Extract track IDs from track metadata.