Skip to content

Latest commit

 

History

History
344 lines (256 loc) · 29 KB

sdk-map.md

File metadata and controls

344 lines (256 loc) · 29 KB

SDK map — Spotify Web API (Python)

A generated table of contents for this SDK. Consult this map and its sub-pages to learn signatures, error types, and server/auth wiring by lookup. Model shapes and enum values are not duplicated here — the map names the module declaring each type; read the shape there. Every name is the emitted spelling, so a wrong one fails at import rather than working silently.

SDK display name Spotify Web API
Root package spotify_web_api
Distribution name spotify-web-api
Requires Python 3.10 or later
API spec version 2024.3.3
Generator APIMatic

Staleness check: the API spec version above changes when the SDK is regenerated from a new spec, and the package version is what pip show reports for the installed SDK. If a lookup here fails at import, re-read the module named in the row.

All Source paths on this map and its sub-pages are relative to the SDK root — the directory holding this file and pyproject.toml — never to the page that carries them. Open them as-is from the SDK root; if the SDK sits under a subdirectory of a larger repo, prefix that subdirectory.


Getting a client

Synchronous client

from spotify_web_api import SpotifyWebApiClient
from spotify_web_api.auth import Oauth20Scope
from spotify_web_api.core import AuthorizationCodeCredentials, ClientCredentials


def prompt(url: str) -> str:
    return input(f"Open {url}, then paste the code: ")


client = SpotifyWebApiClient(
    oauth_2_0=AuthorizationCodeCredentials[Oauth20Scope](
        client_id="YOUR_CLIENT_ID", redirect_uri="YOUR_REDIRECT_URI", prompt_for_authorization_code=prompt
    ),
    oauth_2_0_client_credentials=ClientCredentials(client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET"),
)

# TODO: call endpoints here -- see api-reference.md

client.close()

Alternatively, scope it — with SpotifyWebApiClient(...) as client: closes the pool on exit.

Asynchronous client

from asyncio import run, to_thread

from spotify_web_api import AsyncSpotifyWebApiClient
from spotify_web_api.auth import Oauth20Scope
from spotify_web_api.core import AsyncAuthorizationCodeCredentials, ClientCredentials


async def prompt(url: str) -> str:
    print(f"Open {url}")
    return await to_thread(input, "Paste the code: ")


async def main() -> None:
    client = AsyncSpotifyWebApiClient(
        oauth_2_0=AsyncAuthorizationCodeCredentials[Oauth20Scope](
            client_id="YOUR_CLIENT_ID", redirect_uri="YOUR_REDIRECT_URI", prompt_for_authorization_code=prompt
        ),
        oauth_2_0_client_credentials=ClientCredentials(client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET"),
    )
    # TODO: call endpoints here, awaiting each -- see api-reference.md
    await client.aclose()


run(main())

Alternatively, scope it — async with AsyncSpotifyWebApiClient(...) as client: closes the pool on exit.

AsyncClient (spotify_web_api/async_client.py) mirrors Client method for method, each endpoint method a coroutine. It takes the same keywords, except that each client accepts only its own transport and — where the Async Type column differs — only its own flavour.

Client and AsyncClient are aliases of SpotifyWebApiClient and AsyncSpotifyWebApiClient — the names tracebacks and repr() show; all four import from the root.

close() / aclose() closes the transport even when you supplied one via custom_http_client= / custom_async_http_client=, and a closed client cannot be reused.

Every API group is a property on the client (e.g. client.albums). Every constructor argument is optional and keyword-only. Sources: spotify_web_api/client.py, spotify_web_api/async_client.py:

Keyword Sync Type Async Type Default
server_config ServerConfigOrDict | None ServerConfigOrDict | None None
timeout float float 30.0 seconds
retry_options int | RetryOptionsOrDict | None int | RetryOptionsOrDict | None None
logging_options LoggingOptionsOrDict | None LoggingOptionsOrDict | None None
hooks Sequence[SdkHook] | SdkHooksDict | None Sequence[AsyncSdkHook] | AsyncSdkHooksDict | None None
custom_http_client HttpClient | None — None
custom_async_http_client — AsyncHttpClient | None None
oauth_2_0 AuthorizationCodeCredentialsOrDict[Oauth20Scope] | None AsyncAuthorizationCodeCredentialsOrDict[Oauth20Scope] | None None
oauth_2_0_token_source RefreshableTokenSource[AuthorizationCodeCredentials[Oauth20Scope]] | None AsyncRefreshableTokenSource[AsyncAuthorizationCodeCredentials[Oauth20Scope]] | None None
oauth_2_0_client_credentials ClientCredentialsOrDict | None ClientCredentialsOrDict | None None
oauth_2_0_client_credentials_token_source TokenSource[ClientCredentials] | None AsyncTokenSource[ClientCredentials] | None None

The types those columns name — where each imports from and, for a credentials dict, its keys:

Type Import from Shape
ServerConfigOrDict spotify_web_api.server keys as the Servers & auth tables read
RetryOptionsOrDict spotify_web_api.core a retry count, RetryOptions, or a dict: max_retries: int · initial_delay: float · backoff_factor: float · max_delay: float · max_jitter: float · status_codes_to_retry: frozenset[int] · http_methods_to_retry: frozenset[HttpMethod]
LoggingOptionsOrDict spotify_web_api.core LoggingOptions or a dict: log_request_headers: bool · log_response_headers: bool · log_request_body: bool · body_size_limit: int · redaction_placeholder: str · unmask_headers: AbstractSet[str] · mask_headers: AbstractSet[str] · mask_keys: AbstractSet[str]
SdkHook spotify_web_api.core protocol — before_request(request: HttpRequest, context: HookContext) -> HttpRequest · after_response(response: HttpResponse, context: HookContext) -> HttpResponse; subclass it and override either, or pass plain functions as an SdkHooksDict
SdkHooksDict spotify_web_api.core dict — on_request: functions (HttpRequest, HookContext) -> HttpRequest · on_response: functions (HttpResponse, HookContext) -> HttpResponse; both optional, the on_request ones run first, any other key is ignored
HttpClient spotify_web_api.core protocol — send(request: HttpRequest) -> HttpResponse · close(); send returns once the head has arrived and never reads the body, and raises SdkConnectionError (from core; SdkTimeoutError for a timeout) when no response arrives, as the response's reads do for a body they cannot deliver, naming the call as request.method and safe_url(request.url) — anything else it raises is never retried
AuthorizationCodeCredentialsOrDict spotify_web_api.core AuthorizationCodeCredentials or a dict: client_id: str · client_secret: str | None · redirect_uri: str · scopes: list[Scope] | None · state: str | None · pkce: PkceMethod | None = "S256" · prompt_for_authorization_code: AuthorizationCodePrompt
Oauth20Scope spotify_web_api.auth Enum of the declared scopes
RefreshableTokenSource spotify_web_api.core protocol — fetch(credentials) -> OAuthTokenRefreshable · refresh(credentials, refresh_token) -> OAuthTokenRefreshable | None
AuthorizationCodeCredentials spotify_web_api.core client_id: str · client_secret: str | None · redirect_uri: str · scopes: list[Scope] | None · state: str | None · pkce: PkceMethod | None = "S256" · prompt_for_authorization_code: AuthorizationCodePrompt
ClientCredentialsOrDict spotify_web_api.core ClientCredentials or a dict: client_id: str · client_secret: str · scopes: list[Scope] | None
TokenSource spotify_web_api.core protocol — fetch(credentials) -> OAuthToken
ClientCredentials spotify_web_api.core client_id: str · client_secret: str · scopes: list[Scope] | None
AsyncSdkHook spotify_web_api.core protocol — the same two methods as async def, taking AsyncHookContext and AsyncHttpResponse; async def functions go in an AsyncSdkHooksDict
AsyncSdkHooksDict spotify_web_api.core dict — the same two keys, each function async def, taking AsyncHookContext and, for a response, AsyncHttpResponse
AsyncHttpClient spotify_web_api.core protocol — async send(request: HttpRequest) -> AsyncHttpResponse · async aclose(); the same obligation, awaited
AsyncAuthorizationCodeCredentialsOrDict spotify_web_api.core AsyncAuthorizationCodeCredentials or a dict: client_id: str · client_secret: str | None · redirect_uri: str · scopes: list[Scope] | None · state: str | None · pkce: PkceMethod | None = "S256" · prompt_for_authorization_code: AsyncAuthorizationCodePrompt
AsyncRefreshableTokenSource spotify_web_api.core protocol — async fetch(credentials) -> OAuthTokenRefreshable · async refresh(credentials, refresh_token) -> OAuthTokenRefreshable | None
AsyncAuthorizationCodeCredentials spotify_web_api.core client_id: str · client_secret: str | None · redirect_uri: str · scopes: list[Scope] | None · state: str | None · pkce: PkceMethod | None = "S256" · prompt_for_authorization_code: AsyncAuthorizationCodePrompt
AsyncTokenSource spotify_web_api.core protocol — async fetch(credentials) -> OAuthToken

Retries — on by default

retry_options left at None applies the default RetryOptions policy below, so an unconfigured client retries: a request whose method is in http_methods_to_retry is sent again when it gets a status in status_codes_to_retry, or no response at all, and the last outcome reaches you only once its retries are spent. A body that cannot be re-sent byte for byte — a streamed file upload — is never retried. retry_options=0 (or {"max_retries": 0}) turns retrying off; a bare count sets max_retries and leaves every other field at its default.

RetryOptions fields (source: spotify_web_api/core/retries.py). Pass only the fields you change; each one left out takes its default:

Field Type Default
max_retries int 3
initial_delay float (seconds) 1.0
backoff_factor float 2.0
max_delay float (seconds) 60.0
max_jitter float (seconds) 0.5
status_codes_to_retry frozenset[int] frozenset({408, 429, 500, 502, 503, 504})
http_methods_to_retry frozenset[HttpMethod] frozenset({"GET", "HEAD", "PUT", "OPTIONS"})

The wait before retry n is initial_delay × backoff_factor^(n−1) plus up to max_jitter of random delay, the sum capped at max_delay; a Retry-After header replaces it, trimmed to max_delay.

A single call overrides two of these through request_options (spotify_web_api/core/request_options.py): max_retries and status_codes_to_retry, each merged over the client's policy field by field — request_options={"max_retries": 0} turns retrying off for that one call and leaves every other call alone.

Logging — off by default

Every HTTP exchange is written through the standard logging module under the spotify_web_api logger, and the SDK configures nothing itself. Set that logger's level to turn it on: INFO writes the request line and a 2xx response line, WARNING a non-2xx response line and each retry, ERROR a call that ends in an exception, and DEBUG the header dumps and the request body that the flags below turn on. Or set SPOTIFY_WEB_API_LOG=info|debug before the process starts: it sets the level, turns the three flags on for debug, and adds a stderr handler only where nothing listens.

LoggingOptions fields (source: spotify_web_api/core/logging.py). Pass only the fields you change; each one left out takes its default, and a name set you pass replaces its default:

Field Type Default
log_request_headers bool False
log_response_headers bool False
log_request_body bool False
body_size_limit int (bytes) 32768
redaction_placeholder str "REDACTED"
unmask_headers AbstractSet[str] frozenset()
mask_headers AbstractSet[str] frozenset()
mask_keys AbstractSet[str] frozenset({"sig", "signature", "access_token", "apikey", "api_key", "client_secret", "password", "refresh_token", "code", "assertion", "client_assertion"})

A single call is quietened through request_options (spotify_web_api/core/request_options.py): log_level, a logging level constant, is a floor below which that call's records are not written; it never turns a dump or the body on. A header value prints REDACTED unless its name is on the runtime's safe list, a query value unless its key is a paging name, and a form field whose key is in mask_keys always; a JSON body prints as sent; a response body is never logged.

Hooks — none by default

A hook is caller code run on every attempt of every request, retries and the token requests an OAuth scheme makes included (source: spotify_web_api/core/hooks.py). before_request runs after authentication and before the request line is logged, and returns the request to send: the one it was given, or a dataclasses.replace of it. after_response runs after the response line and the 401 check and before the retry decision, and returns the response the call acts on. The client's hooks run first, in order, then the call's.

A single call adds hooks through request_options (spotify_web_api/core/request_options.py): hooks, a list of hooks or an SdkHooksDict, appended to the client's and never replacing them. The client keeps the hooks it was given uncopied, so a list changed after construction is read by the next call. On the async client the per-call options are AsyncRequestOptions, whose hooks are AsyncSdkHook or an AsyncSdkHooksDict; a hook of the other flavour is a type error, and nothing is checked at run time.

A hook that raises ends the call with that exception, after any open response is closed. The one exception is SdkConnectionError raised from before_request naming the call, safe_url(context.url): the attempt is retried as a failed send, under the same method and retry-count rules as a transport failure. Raised from after_response, it ends the call like any other exception. On a token request an OAuth scheme makes only the client's hooks run, not the call's, and one that raises reaches you as AuthSchemeError with its exception in scheme_failures; in an OR requirement the next configured scheme is tried first.


Error-handling model (read once — applies to every operation)

Every operation is reached in two response modes:

  • Parsed call. Returns the decoded payload and raises ApiError on an error status, with the decoded body on .error and the status on .status_code.
  • Raw call. Reached through .with_raw_response; returns ApiResult — Success or Failure — and never raises for an API error. Read .payload on a Success or .error on a Failure; both carry .status_code and .headers.

Everything a call raises derives from SdkError, so one except SdkError covers any number of calls; every member names the call as .method and .url and keeps what caused it on __cause__. Besides ApiError, three members raise in both modes: ResponseDecodeError for a body its declared type rejects, SdkConnectionError for no usable response (SdkTimeoutError when it timed out) and AuthSchemeError for a credential that could not be applied. ApiError and ResponseDecodeError are siblings, so except ApiError never catches a 2xx that broke its contract.

What .error holds is fixed per operation. There are two cases:

  • Case A — typed error. The operation documents at least one error status, so spotify_web_api/errors/ declares a union alias over the bodies those statuses map to — RawError is always its last arm, for any undocumented status — and .error is annotated with that alias. Narrow it with a match class pattern or isinstance. The operation blocks name the alias and the status each arm maps from.
  • Case B — raw error. The operation documents no error status; .error is RawError (spotify_web_api/core/results.py): status_code: int · content: bytes · text(encoding="utf-8"): str · json(): Any.

Core runtime types (spotify_web_api/core/) — public members with their declared types, verbatim from source:

Type Public members Source
SdkError — the root of everything a call raises method: HttpMethod · url: str — the path rendered, no query; the cause on __cause__ spotify_web_api/core/exceptions.py
ApiError — raised by every parsed call; .error is a Case A alias from spotify_web_api/errors/ or RawError error: E · status_code: int · headers: Mapping[str, str] · method: HttpMethod · url: str spotify_web_api/core/exceptions.py
ResponseDecodeError — a body its declared type rejects, in both modes status_code: int · headers: Mapping[str, str] · method · url spotify_web_api/core/exceptions.py
SdkConnectionError — no usable response, in both modes method · url; the HTTP library's exception on __cause__ spotify_web_api/core/exceptions.py
SdkTimeoutError — the SdkConnectionError that timed out timeout: float · method · url spotify_web_api/core/exceptions.py
AuthSchemeError — a credential that could not be applied, in both modes scheme_failures: tuple[Exception, ...] · method · url spotify_web_api/core/exceptions.py
ApiResult[T, E] — returned by every raw call; the Success[T] | Failure[E] union payload: T (on Success) · error: E (on Failure) · status_code: int · headers: Mapping[str, str] · method: HttpMethod · url: str (all four on either) spotify_web_api/core/results.py
RawError status_code: int · content: bytes · text(encoding="utf-8"): str · json(): Any spotify_web_api/core/results.py

Typed error bodies (the arms of a Case A alias) are ordinary models — no special handling. The operation's Type sources table gives the module that declares each one; read field names, declared types and JSON aliases there, as for any other model.

try:
    response = client.albums.check_users_saved_albums(
        "382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo,2noRn2Aes5aoNVsU6iWThc"
    )
except ApiError as e:
    # Case A — typed error: e.error is CheckUsersSavedAlbumsErrorBody.
    match e.error:
        case Unauthorized1():
            # Handle 401.
            print(e.status_code, e.error)
        case Forbidden1():
            # Handle 403.
            print(e.status_code, e.error)
        case TooManyRequests1():
            # Handle 429.
            print(e.status_code, e.error)
        case RawError():
            # Any other error status.
            print(e.status_code, e.error.text())
except ResponseDecodeError as e:
    # Body rejected by its declared type.
    print(f"{e.status_code}: undecodable body ({type(e.__cause__).__name__})")
except SdkTimeoutError as e:
    # No response, body or next event in time.
    print(f"{e.method} {e.url} timed out after {e.timeout} s")
except SdkConnectionError as e:
    # Refused, dropped, or cut off mid-body.
    print(f"{e.method} {e.url} could not connect: {e.__cause__!r}")
except AuthSchemeError as e:
    # A credential could not be applied; one failure per scheme tried.
    for failure in e.scheme_failures:
        print(f"{e.method} {e.url} unauthenticated: {failure}")
except SdkError as e:
    # A member added later.
    print(e)
except Exception as e:
    # Not a call failure: input refused before sending (ValueError), a handler you wrote raising, or a bug here.
    print(f"not a call failure: {e!r}")
    raise e

Raw (.with_raw_response) variants: present on every operation — the same call returns ApiResult instead of raising, with the same body on Failure.error. Of 138 operations, 138 are Case A (typed) and 0 are Case B (raw).


Operations — by controller (15 pages, 138 operations)

Each links to a sub-page with one block per operation, headed by its full accessor path: the HTTP verb and route (for a mock, a raw request or a provider-side log — never reconstruct it from the method name), the sync parsed signature with its required positional parameters, each parameter's role and — where it differs — wire name, both return types, and its error case — Case A names the alias and the status each arm maps from, Case B names RawError. Every block also carries a Type sources table — every generated type it names, with the module that declares it. A runtime type — a file alias, a date/time or byte converter — is not listed there.

Each block states what is specific to its operation. Everything below holds for every operation, and blocks never restate it — silence means the default applies.

Applies to every operation Stated where
Four spellings, one signature — the same method name and parameters on Client and AsyncClient, each also reachable through .with_raw_response; the async twin is a coroutine to await, with the same return types and error case, and where the Async Type column differs, pass the type it names Getting a client
Parsed raises, raw returns — ApiError versus ApiResult Error-handling model
Case B error is always RawError — also the last arm of every Case A alias, where a block's Error arms bullet ends in it Error-handling model
A trailing request_options — keyword-only and optional, for per-call overrides such as a timeout, extra headers, max_retries, status_codes_to_retry, log_level or hooks; every signature ends with it here (spotify_web_api/core/request_options.py), Retries, Logging, Hooks
Each operation names its own server — this SDK declares several, so every block carries a Server bullet with the server's key in server_config= its block
Parameter names are literal — signatures are generated code verbatim, and everything behind the bare * must be passed by name here
A parameter's wire name is its Python name — sent as-is on the path, query string, header or body, unless the block's Params bullet carries a wire name beside the role here

The operation's behavioural prose lives on the operation itself, as the method's docstring in the module named at the top of its page, and again in api-reference.md with a per-parameter description and a usage sample. Blocks here give you the contract — names, types, shapes, errors. Where an operation's semantics decide what you must pass, that is what the docstring settles; read it there rather than filling it in from memory.

Sub-pages chunk per ### block: each block is self-contained given the table above, and assumes this page is loaded beside it.

Controller Class Ops Page
client.albums Albums / AsyncAlbums 9 map/operations/albums.md
client.artists Artists / AsyncArtists 10 map/operations/artists.md
client.audiobooks Audiobooks / AsyncAudiobooks 7 map/operations/audiobooks.md
client.categories_api CategoriesApi / AsyncCategoriesApi 3 map/operations/categories_api.md
client.chapters Chapters / AsyncChapters 3 map/operations/chapters.md
client.episodes Episodes / AsyncEpisodes 7 map/operations/episodes.md
client.genres Genres / AsyncGenres 1 map/operations/genres.md
client.library Library / AsyncLibrary 29 map/operations/library.md
client.markets_api MarketsApi / AsyncMarketsApi 1 map/operations/markets_api.md
client.player Player / AsyncPlayer 15 map/operations/player.md
client.playlists Playlists / AsyncPlaylists 16 map/operations/playlists.md
client.search Search / AsyncSearch 1 map/operations/search.md
client.shows Shows / AsyncShows 7 map/operations/shows.md
client.tracks Tracks / AsyncTracks 17 map/operations/tracks.md
client.users Users / AsyncUsers 12 map/operations/users.md

Models — where they live, how to build them

Shapes live only in the source. Every module under spotify_web_api/models/ declares one type plus its input companion, and every module under spotify_web_api/errors/ one alias plus the mapper that builds it; no two share a name. Take a type's module from the operation's Type sources table. When no retrieved chunk names it, the module is the type name in snake_case under the kind's directory below (AlbumBase ↔ album_base.py; an error alias drops its Body suffix: AddToQueueErrorBody ↔ add_to_queue_error.py). Never grep for a type.

Group Count Directory (module = <type_name>.py)
Models (SdkBaseModel pydantic classes) 129 spotify_web_api/models/
Enums (Enum over str / int) — Python member names + wire values 18 spotify_web_api/models/enums/
Unions (plain) — TypeAlias over the arms 4 spotify_web_api/models/unions/
Error aliases (one per Case A operation) 89 spotify_web_api/errors/

Conventions: a model is a SdkBaseModel (pydantic) class; a field whose wire name differs from its Python name carries it as Field(alias=…) (type_ ↔ "type") — read the alias off the field rather than deriving it. An omittable field is annotated Optional[T] and defaults to UNSET, and one that may also be explicitly null is OptionalNullable[T]; both come from core and neither is typing.Optional — there is no None arm unless the spec declared the property nullable, so passing None to the first is a type error rather than a value that serializes.

Every model, enum and union also has an input companion, exported beside it from the same package (AlbumBase ↔ AlbumBaseDict). Wherever a signature names the companion you may pass either the model instance or a plain dict with the same keys, whichever reads better at the call site. An enum is a real Enum subclass over str / int; its companion is spelled <Name>OrStr or <Name>OrInt (AlbumGroup ↔ AlbumGroupOrStr) and additionally accepts a wire value this SDK version does not know. A union is a TypeAlias over its arms.

Import paths by content type (from <package> import <Name>):

Contents Import from
Client (root) spotify_web_api
Operation controllers spotify_web_api.apis
Models spotify_web_api.models
Enums spotify_web_api.models.enums
Unions spotify_web_api.models.unions, spotify_web_api.models
Error aliases spotify_web_api.errors
Core runtime (SdkError, ApiError, ApiResult, RawError, …) spotify_web_api.core

Servers & auth

OAuth2 (authorization code). Pass oauth_2_0 your client id, redirect URI and authorization code; authorization is at /authorize and tokens come from /api/token, both on the auth_server server. Scopes are the Oauth20Scope alias.

OAuth2 (client credentials). Pass oauth_2_0_client_credentials your client id and secret; tokens come from /api/token on the auth_server server.

Operation blocks name their scheme in an Auth bullet; an operation whose spec declares no scheme carries no such bullet.

  • AND — every scheme listed must be configured for the call to succeed.
  • OR — any one of the schemes listed can be used; the first one you configured is the one sent, in the order listed.

A scheme you did not configure is skipped silently rather than raising, and the request is sent anyway — so an authentication failure can mean no credential was sent rather than a bad one.

One environment. The spec declares a single environment, so no environment keyword exists and there is nothing to select.

2 servers. Base-URL templates and override points (spotify_web_api/server/server_config.py):

Server Base URL Override point
default https://api.spotify.com/v1 {"default": {"base_url": …}}
auth_server https://accounts.spotify.com {"auth_server": {"base_url": …}}

Override any of these by passing server_config= a dict nested exactly as the columns above read — {"default": {"base_url": …}} — with each row's variables sitting beside its base_url.