spotify

Module for interacting with Spotify API. To use this module, you must have a Spotify API key and Spotify API secret.

import spotdl.utils.spotify
spotify.Spotify.init(client_id, client_secret)

SpotifyClient

Runtime-selected Spotify client facade.

__getattr__(name)

The selected backend provides Spotify API methods at runtime.

Source code in spotdl/utils/spotify.py

def __getattr__(self, name: str) -> Any:
    """
    The selected backend provides Spotify API methods at runtime.
    """

    raise AttributeError(name)

__new__()

Return the initialized Spotify client implementation.

Source code in spotdl/utils/spotify.py

def __new__(cls):
    """
    Return the initialized Spotify client implementation.
    """

    if cls._instance is None:
        raise SpotifyError(
            "Spotify client not created. Call SpotifyClient.init"
            "("
            "client_id, client_secret, user_auth=False, no_cache=False, "
            "headless=False, max_retries=3, use_cache_file=False, "
            "use_official_api=False, auth_token=None, cache_path=None"
            ") first."
        )

    return cls._instance

init(client_id, client_secret, user_auth=False, no_cache=False, headless=False, max_retries=3, use_cache_file=False, use_official_api=False, auth_token=None, cache_path=None) classmethod

Initializes the selected SpotifyClient implementation.

Source code in spotdl/utils/spotify.py

@classmethod
def init(
    cls,
    client_id: str,
    client_secret: str,
    user_auth: bool = False,
    no_cache: bool = False,
    headless: bool = False,
    max_retries: int = 3,
    use_cache_file: bool = False,
    use_official_api: bool = False,
    auth_token: Optional[str] = None,
    cache_path: Optional[str] = None,
) -> Any:
    """
    Initializes the selected SpotifyClient implementation.
    """

    if cls._instance is not None:
        raise SpotifyError("A spotify client has already been initialized")

    kwargs = {
        "client_id": client_id,
        "client_secret": client_secret,
        "user_auth": user_auth,
        "no_cache": no_cache,
        "headless": headless,
        "max_retries": max_retries,
        "use_cache_file": use_cache_file,
        "auth_token": auth_token,
        "cache_path": cache_path,
    }

    official_only_options = [
        option for key, option in OFFICIAL_API_ONLY_OPTIONS.items() if kwargs[key]
    ]
    if official_only_options and not use_official_api:
        logger.info(
            "Using the official Spotify Web API because %s %s requested.",
            ", ".join(official_only_options),
            "was" if len(official_only_options) == 1 else "were",
        )
        use_official_api = True

    if use_official_api:
        cls._instance = _init_official_spotify_client(**kwargs)
    else:
        cls._instance = _init_free_spotify_client(**kwargs)

    cls._use_official_api = use_official_api

    return cls._instance

is_using_official_api() classmethod

Returns whether the active client uses the official Spotify Web API.

Source code in spotdl/utils/spotify.py

@classmethod
def is_using_official_api(cls) -> bool:
    """
    Returns whether the active client uses the official Spotify Web API.
    """

    return cls._use_official_api

SpotifyError

Bases: Exception

Base class for all exceptions related to SpotifyClient.

save_spotify_cache(cache)

Saves the Spotify cache to a file when the official API client is active.

Arguments

• cache: The cache to save.

Source code in spotdl/utils/spotify.py

def save_spotify_cache(cache: Dict[str, Optional[Dict]]):
    """
    Saves the Spotify cache to a file when the official API client is active.

    ### Arguments
    - cache: The cache to save.
    """

    if not SpotifyClient.is_using_official_api():
        return

    cache_file_loc = get_spotify_cache_path()

    logger.debug("Saving Spotify cache to %s", cache_file_loc)

    cache = {
        key: value
        for key, value in cache.items()
        if value is not None and "tracks/" in key
    }

    with open(cache_file_loc, "w", encoding="utf-8") as cache_file:
        json.dump(cache, cache_file)