Async client¶

AsyncSpotifyClient is a 1:1 async mirror of SpotifyClient: the same methods, the same return models, but async/await over an async transport. It is an async context manager — use async with or call aclose(). See the Async guide for gather patterns.

spotify_scraper.AsyncSpotifyClient ¶

AsyncSpotifyClient(
    *,
    rate_limit: RateLimit | None = None,
    retry: RetryPolicy | None = None,
    proxy: str | None = None,
    user_agent: str | None = None,
    timeout: float = 10.0,
    transport: AsyncTransport | None = None,
    cookies: str | Path | Mapping[str, str] | None = None,
    host_rate_limits: Mapping[str, RateLimit] | None = None,
    cache: CacheConfig | None = None,
    locale: str | None = None,
    max_concurrency: int = 5,
)

Asynchronous client for extracting public Spotify data.

The client is an async context manager and should be closed when done, either via async with or by awaiting :meth:aclose. Using it after closing raises :class:~spotify_scraper.errors.SpotifyScraperError.

Initialize the client.

Parameters:

Name	Type	Description	Default
`rate_limit`	`RateLimit \| None`	Global token-bucket configuration; defaults to safe limits applied per host.	`None`
`retry`	`RetryPolicy \| None`	Retry policy; defaults to :class:`RetryPolicy`.	`None`
`proxy`	`str \| None`	Optional proxy URL for the default transport.	`None`
`user_agent`	`str \| None`	Fixed User-Agent for the default transport.	`None`
`timeout`	`float`	Per-request timeout in seconds for the default transport.	`10.0`
`transport`	`AsyncTransport \| None`	A custom transport that overrides every other HTTP option; the client does not own its lifecycle.	`None`
`cookies`	`str \| Path \| Mapping[str, str] \| None`	User cookies for authenticated features; accepted and stored now, consumed by the lyrics extraction change.	`None`
`host_rate_limits`	`Mapping[str, RateLimit] \| None`	Optional per-host rate overrides for the default transport (e.g. to throttle `api-partner.spotify.com`).	`None`
`cache`	`CacheConfig \| None`	Optional response-cache configuration (opt-in, off by default). When supplied and no custom `transport` is given, the default transport is wrapped in an :class:`~spotify_scraper.http.cache.AsyncCachingTransport` and the client owns and closes the whole stack. Ignored when a custom `transport` is supplied, exactly as `rate_limit`/ `retry`/`proxy` are.	`None`
`locale`	`str \| None`	Default display-language for localized names, a BCP-47 language tag — a bare language subtag (e.g. `"de"`, `"ja"`) or a language-region tag (e.g. `"ja-JP"`) — sent as the `Accept-Language` header. Localizes display-name LANGUAGE only; a bare country code like `"US"` is not a language and is ignored. It does NOT filter regional availability or vary preview URLs (those require the authenticated Web API). A per-call `locale` overrides it. Raises :class:`~spotify_scraper.errors.URLError` if invalid.	`None`
`max_concurrency`	`int`	Caps how many entity pipelines run concurrently in the plural `get_*s` helpers; bounds open sockets and bucket-lock contention while the rate limiter still governs request rate. Must be at least 1. Defaults to 5, matching the default :attr:`RateLimit.burst`.	`5`

Raises:

Type	Description
`ValueError`	If `max_concurrency` is less than 1.

login `async` ¶

login(
    *,
    reuse: bool = True,
    save: bool = True,
    store: str = "file",
    timeout: float = 300.0,
    proxy: str | None = None,
    session_path: Path | None = None,
) -> None

Authenticate, reusing a valid saved session or capturing a new one.

When reuse is set (the default) and a valid saved session exists, its cookie is loaded and wired into this client WITHOUT opening the browser — the Playwright import is skipped entirely, so reusing a session never needs the browser extra. Otherwise a real Chromium window opens; the user signs into Spotify by hand, the captured cookie is wired in, and when save is set it is persisted for later reuse.

Validity is checked locally (the saved file exists, is securely permissioned, parses, and is not past its known expiry), so a cookie Spotify has since revoked is still reused; the first authenticated call then surfaces :class:AuthenticationError per the existing 401 contract.

The captured/loaded cookie resets the cached cookie-token provider so the next authenticated call re-exchanges. This method performs no HTTP request itself.

Parameters:

Name	Type	Description	Default
`reuse`	`bool`	Skip the browser and load a valid saved session when present.	`True`
`save`	`bool`	Persist a freshly captured cookie to `session_path`.	`True`
`store`	`str`	Session backend, `"file"` (default) or `"keyring"`.	`'file'`
`timeout`	`float`	Seconds to wait for the manual login to yield a cookie.	`300.0`
`proxy`	`str \| None`	Optional proxy URL for the login browser. Neither client retains the constructor proxy, so pass it explicitly here.	`None`
`session_path`	`Path \| None`	Override for where the session is saved/loaded.	`None`

Raises:

Type	Description
`AuthenticationError`	If no cookie is captured before the timeout.
`ImportError`	If the `browser` extra is not installed (capture path).
`SpotifyScraperError`	If the client is closed.

from_saved_session `classmethod` ¶

from_saved_session(
    *,
    store: str = "file",
    session_path: Path | None = None,
    **kwargs: Any,
) -> AsyncSpotifyClient

Build a client from a previously saved session, no browser required.

This is a synchronous classmethod: it only reads a file, so no event loop is needed.

Parameters:

Name	Type	Description	Default
`store`	`str`	Session backend, `"file"` (default) or `"keyring"`.	`'file'`
`session_path`	`Path \| None`	Override for the session file to load.	`None`
`**kwargs`	`Any`	Forwarded to :class:`AsyncSpotifyClient` (e.g. `rate_limit`, `retry`, `proxy`, `timeout`, `transport`).	`{}`

Returns:

Type	Description
`AsyncSpotifyClient`	A client wired with the saved `sp_dc` cookie.

Raises:

Type	Description
`SessionError`	If no usable saved session exists.

logout `classmethod` ¶

logout(
    *, store: str = "file", session_path: Path | None = None
) -> None

Remove the saved session for local revocation; idempotent.

Parameters:

Name	Type	Description	Default
`store`	`str`	Session backend, `"file"` (default) or `"keyring"`.	`'file'`
`session_path`	`Path \| None`	Override for the session file to clear.	`None`

session_info `classmethod` ¶

session_info(
    *, store: str = "file", session_path: Path | None = None
) -> SessionInfo

Report the saved session's status WITHOUT exposing the cookie.

This is a synchronous classmethod: it only reads a file, so no event loop is needed.

Parameters:

Name	Type	Description	Default
`store`	`str`	Session backend, `"file"` (default) or `"keyring"`.	`'file'`
`session_path`	`Path \| None`	Override for the session file to inspect.	`None`

Returns:

Type	Description
`SessionInfo`	A cookie-free :class:`SessionInfo` (`exists` / `valid` / expiry);
`SessionInfo`	never raises for a missing, corrupt, insecure, or expired session.

get_track `async` ¶

get_track(
    value: str, *, locale: str | None = None
) -> Track

Fetch a track by URL, URI, or bare ID.

The embed page is fetched first: it supplies the tier-2 fallback track and bootstraps the anonymous token. Tier 1 (pathfinder) is then attempted and merged in. On tier-1 :class:ParsingError the embed track is returned with a logged warning.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify track URL, URI, or 22-character ID.	required
`locale`	`str \| None`	Per-call display-language override (`Accept-Language`); localizes display-name LANGUAGE only, not availability/preview.	`None`

Returns:

Type	Description
`Track`	The richest available :class:`Track`.

Raises:

Type	Description
`URLError`	If `locale` is invalid.
`NotFoundError`	If the track does not exist.
`SpotifyScraperError`	If the client is closed.

get_album `async` ¶

get_album(
    value: str, *, locale: str | None = None
) -> Album

Fetch an album by URL, URI, or bare ID, paginating its tracks.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify album URL, URI, or 22-character ID.	required
`locale`	`str \| None`	Per-call display-language override (`Accept-Language`); localizes display-name LANGUAGE only, not availability/preview.	`None`

Returns:

Type	Description
`Album`	The richest available :class:`Album` with as many tracks as the
`Album`	pathfinder pages provided (all of them by default).

Raises:

Type	Description
`URLError`	If `locale` is invalid.
`NotFoundError`	If the album does not exist.
`SpotifyScraperError`	If the client is closed.

get_artist `async` ¶

get_artist(
    value: str, *, locale: str | None = None
) -> Artist

Fetch an artist by URL, URI, or bare ID.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify artist URL, URI, or 22-character ID.	required
`locale`	`str \| None`	Per-call display-language override (`Accept-Language`); localizes display-name LANGUAGE only, not availability/preview.	`None`

Returns:

Type	Description
`Artist`	The richest available :class:`Artist`.

Raises:

Type	Description
`URLError`	If `locale` is invalid.
`NotFoundError`	If the artist does not exist.
`SpotifyScraperError`	If the client is closed.

get_playlist `async` ¶

get_playlist(
    value: str,
    *,
    max_tracks: int | None = 100,
    locale: str | None = None,
) -> Playlist

Fetch a playlist by URL, URI, or bare ID, paginating its tracks.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify playlist URL, URI, or 22-character ID.	required
`max_tracks`	`int \| None`	Upper bound on tracks to collect; `None` fetches all.	`100`
`locale`	`str \| None`	Per-call display-language override (`Accept-Language`); localizes display-name LANGUAGE only, not availability/preview.	`None`

Returns:

Type	Description
`Playlist`	The richest available :class:`Playlist`.

Raises:

Type	Description
`URLError`	If `locale` is invalid.
`NotFoundError`	If the playlist does not exist.
`SpotifyScraperError`	If the client is closed.

get_episode `async` ¶

get_episode(
    value: str, *, locale: str | None = None
) -> Episode

Fetch a podcast episode by URL, URI, or bare ID.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify episode URL, URI, or 22-character ID.	required
`locale`	`str \| None`	Per-call display-language override (`Accept-Language`); localizes display-name LANGUAGE only, not availability/preview.	`None`

Returns:

Type	Description
`Episode`	The richest available :class:`Episode`.

Raises:

Type	Description
`URLError`	If `locale` is invalid.
`NotFoundError`	If the episode does not exist.
`SpotifyScraperError`	If the client is closed.

get_show `async` ¶

get_show(
    value: str,
    *,
    max_episodes: int | None = 50,
    locale: str | None = None,
) -> Show

Fetch a podcast show by URL, URI, or bare ID, listing its episodes.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify show URL, URI, or 22-character ID.	required
`max_episodes`	`int \| None`	Upper bound on episodes to collect; `None` fetches all of them.	`50`
`locale`	`str \| None`	Per-call display-language override (`Accept-Language`); localizes display-name LANGUAGE only, not availability/preview.	`None`

Returns:

Type	Description
`Show`	The richest available :class:`Show`, with `total_episodes` and a
`Show`	paginated `episodes` listing when tier 1 succeeds.

Raises:

Type	Description
`URLError`	If `locale` is invalid.
`NotFoundError`	If the show does not exist.
`SpotifyScraperError`	If the client is closed.

get_tracks `async` ¶

get_tracks(
    values: Sequence[str],
) -> Sequence[BatchItem[Track]]

Fetch many tracks, one ordered :class:BatchItem per input.

Parameters:

Name	Type	Description	Default
`values`	`Sequence[str]`	Spotify track URLs, URIs, or 22-character IDs.	required

Returns:

Type	Description
`Sequence[BatchItem[Track]]`	An ordered sequence of :class:`BatchItem`, index-aligned with
`Sequence[BatchItem[Track]]`	`values`; a per-item :class:`SpotifyScraperError` is captured in
`Sequence[BatchItem[Track]]`	`error` and never raised mid-batch.

Raises:

Type	Description
`SpotifyScraperError`	Only if the client is already closed.

get_albums `async` ¶

get_albums(
    values: Sequence[str],
) -> Sequence[BatchItem[Album]]

Fetch many albums, one ordered :class:BatchItem per input.

Parameters:

Name	Type	Description	Default
`values`	`Sequence[str]`	Spotify album URLs, URIs, or 22-character IDs.	required

Returns:

Type	Description
`Sequence[BatchItem[Album]]`	An ordered sequence of :class:`BatchItem`, index-aligned with
`Sequence[BatchItem[Album]]`	`values`; a per-item :class:`SpotifyScraperError` is captured in
`Sequence[BatchItem[Album]]`	`error` and never raised mid-batch.

Raises:

Type	Description
`SpotifyScraperError`	Only if the client is already closed.

get_artists `async` ¶

get_artists(
    values: Sequence[str],
) -> Sequence[BatchItem[Artist]]

Fetch many artists, one ordered :class:BatchItem per input.

Parameters:

Name	Type	Description	Default
`values`	`Sequence[str]`	Spotify artist URLs, URIs, or 22-character IDs.	required

Returns:

Type	Description
`Sequence[BatchItem[Artist]]`	An ordered sequence of :class:`BatchItem`, index-aligned with
`Sequence[BatchItem[Artist]]`	`values`; a per-item :class:`SpotifyScraperError` is captured in
`Sequence[BatchItem[Artist]]`	`error` and never raised mid-batch.

Raises:

Type	Description
`SpotifyScraperError`	Only if the client is already closed.

get_episodes `async` ¶

get_episodes(
    values: Sequence[str],
) -> Sequence[BatchItem[Episode]]

Fetch many episodes, one ordered :class:BatchItem per input.

Parameters:

Name	Type	Description	Default
`values`	`Sequence[str]`	Spotify episode URLs, URIs, or 22-character IDs.	required

Returns:

Type	Description
`Sequence[BatchItem[Episode]]`	An ordered sequence of :class:`BatchItem`, index-aligned with
`Sequence[BatchItem[Episode]]`	`values`; a per-item :class:`SpotifyScraperError` is captured in
`Sequence[BatchItem[Episode]]`	`error` and never raised mid-batch.

Raises:

Type	Description
`SpotifyScraperError`	Only if the client is already closed.

get_playlists `async` ¶

get_playlists(
    values: Sequence[str], *, max_tracks: int | None = 100
) -> Sequence[BatchItem[Playlist]]

Fetch many playlists, one ordered :class:BatchItem per input.

Parameters:

Name	Type	Description	Default
`values`	`Sequence[str]`	Spotify playlist URLs, URIs, or 22-character IDs.	required
`max_tracks`	`int \| None`	Forwarded to each :meth:`get_playlist`; `None` fetches all tracks.	`100`

Returns:

Type	Description
`Sequence[BatchItem[Playlist]]`	An ordered sequence of :class:`BatchItem`, index-aligned with
`Sequence[BatchItem[Playlist]]`	`values`; a per-item :class:`SpotifyScraperError` is captured in
`Sequence[BatchItem[Playlist]]`	`error` and never raised mid-batch.

Raises:

Type	Description
`SpotifyScraperError`	Only if the client is already closed.

get_shows `async` ¶

get_shows(
    values: Sequence[str], *, max_episodes: int | None = 50
) -> Sequence[BatchItem[Show]]

Fetch many shows, one ordered :class:BatchItem per input.

Parameters:

Name	Type	Description	Default
`values`	`Sequence[str]`	Spotify show URLs, URIs, or 22-character IDs.	required
`max_episodes`	`int \| None`	Forwarded to each :meth:`get_show`; `None` fetches all episodes.	`50`

Returns:

Type	Description
`Sequence[BatchItem[Show]]`	An ordered sequence of :class:`BatchItem`, index-aligned with
`Sequence[BatchItem[Show]]`	`values`; a per-item :class:`SpotifyScraperError` is captured in
`Sequence[BatchItem[Show]]`	`error` and never raised mid-batch.

Raises:

Type	Description
`SpotifyScraperError`	Only if the client is already closed.

get_lyrics `async` ¶

get_lyrics(value: str) -> Lyrics

Fetch a track's lyrics using the cookie-derived web-player token.

Lyrics are an authenticated feature: the client must have been built with cookies=. A client without cookies raises :class:AuthenticationError immediately, without any HTTP request.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify track URL, URI, or 22-character ID.	required

Returns:

Type	Description
`Lyrics`	The track's :class:`Lyrics` (synced when Spotify provides offsets).

Raises:

Type	Description
`AuthenticationError`	If no cookies were configured, or the cookie is rejected by the token exchange.
`NotFoundError`	If the track exists but has no lyrics.
`SpotifyScraperError`	If the client is closed.

get_transcript `async` ¶

get_transcript(value: str) -> Transcript

Fetch an episode's transcript using the cookie-derived token.

Transcripts are an authenticated feature: the client must have been built with cookies=. A client without cookies raises :class:AuthenticationError immediately, without any HTTP request.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify episode URL, URI, or 22-character ID.	required

Returns:

Type	Description
`Transcript`	The episode's :class:`Transcript` with millisecond-offset lines.

Raises:

Type	Description
`AuthenticationError`	If no cookies were configured, or the cookie is rejected by the token exchange.
`NotFoundError`	If the episode exists but has no transcript.
`SpotifyScraperError`	If the client is closed.

get_account `async` ¶

get_account() -> Account

Fetch the logged-in account's product state (Premium, country, …).

This is an authenticated feature: the client must have been built with cookies=. A client without cookies raises :class:AuthenticationError immediately, without any HTTP request. It takes no entity argument — the product-state body is a flat per-account object.

Returns:

Name	Type	Description
`The`	`Account`	class:`Account` parsed from Spotify's product-state endpoint.

Raises:

Type	Description
`AuthenticationError`	If no cookies were configured, or the cookie is rejected by the token exchange.
`ParsingError`	If the product-state response is not JSON.
`SpotifyScraperError`	If the client is closed.

is_premium `async` ¶

is_premium() -> bool

Return True when the logged-in account is Premium.

Convenience for (await get_account()).is_premium; same auth needs.

search `async` ¶

search(
    query: str,
    *,
    types: Sequence[str] = _SEARCH_TYPES,
    limit: int = 20,
    locale: str | None = None,
) -> SearchResults

Search Spotify for tracks, albums, artists, playlists, shows, episodes.

Search is anonymous and tier-1-only: it uses the same anonymous bearer token as the entity getters, with no cookie and no embed page. A query that matches nothing returns an empty :class:SearchResults, not an error.

Parameters:

Name	Type	Description	Default
`query`	`str`	The free-text search term.	required
`types`	`Sequence[str]`	Which entity sections to return; the accepted values are `"track"`, `"album"`, `"artist"`, `"playlist"`, `"show"`, and `"episode"`.	`_SEARCH_TYPES`
`limit`	`int`	Maximum hits per section requested from Spotify.	`20`
`locale`	`str \| None`	Per-call display-language override (`Accept-Language`); localizes display-name LANGUAGE only, not availability/preview.	`None`

Returns:

Name	Type	Description
`A`	`SearchResults`	class:`SearchResults` whose tuples for the requested `types` are
	`SearchResults`	populated; unrequested types stay empty.

Raises:

Type	Description
`URLError`	If `types` contains an unrecognized entity type, or `locale` is invalid.
`SpotifyScraperError`	If the client is closed.

get_colors `async` ¶

get_colors(source: str | HasImagesAndName) -> Colors

Extract the dominant theming colors of a cover image.

Anonymous and tier-1-only — the same bearer token as the entity getters, no cookie. Accepts a Spotify image URL or spotify:image: uri, or any fetched entity carrying images (a :class:Track, :class:Album, :class:Artist, …); the entity's first image is used.

Parameters:

Name	Type	Description	Default
`source`	`str \| HasImagesAndName`	An image URL/uri, or an entity with `images`.	required

Returns:

Type	Description
`Colors`	The image's :class:`Colors` (`#RRGGBB` hex, for UI theming).

Raises:

Type	Description
`URLError`	If `source` has no usable image.
`SpotifyScraperError`	If the client is closed.

get_canvas `async` ¶

get_canvas(value: str) -> Canvas | None

Fetch a track's Canvas (looping cover video), or None if it has none.

Canvas is an authenticated feature: the client must have been built with cookies=. A client without cookies raises :class:AuthenticationError immediately, without any HTTP request. Most tracks have no Canvas, so None is a normal, common result rather than an error.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify track URL, URI, or 22-character ID.	required

Returns:

Type	Description
`Canvas \| None`	The track's :class:`Canvas`, or `None` when absent.

Raises:

Type	Description
`AuthenticationError`	If no cookies were configured, or the cookie is rejected by the token exchange.
`NotFoundError`	If the track does not exist.
`SpotifyScraperError`	If the client is closed.

download_canvas `async` ¶

download_canvas(
    source: str | Canvas,
    dest: str | Path = ".",
    *,
    filename: str | None = None,
) -> Path

Download a track's Canvas MP4 to dest and return its path.

Parameters:

Name	Type	Description	Default
`source`	`str \| Canvas`	A track URL/URI/ID, or an already-fetched :class:`Canvas`.	required
`dest`	`str \| Path`	Destination directory; created if it does not exist.	`'.'`
`filename`	`str \| None`	Explicit filename; defaults to `<canvas-id>.mp4`.	`None`

Returns:

Type	Description
`Path`	The path of the written MP4.

Raises:

Type	Description
`AuthenticationError`	If a track `source` is given without cookies.
`NotFoundError`	If the track has no Canvas.
`SpotifyScraperError`	If the client is closed.

list_charts ¶

list_charts() -> Sequence[charts_api.ChartDef]

List the built-in editorial charts (key, name, backing playlist id).

Returns:

Type	Description
`Sequence[ChartDef]`	Every registered :class:`~spotify_scraper.api.charts.ChartDef`. Pass a
`Sequence[ChartDef]`	chart's `key` to :meth:`get_chart` to fetch it as a playlist.

get_chart `async` ¶

get_chart(
    key: str, *, max_tracks: int | None = 100
) -> Playlist

Fetch an editorial chart (e.g. "top-50-global") as a playlist.

Charts are ordinary editorial playlists; this resolves key to its backing playlist id and delegates to :meth:get_playlist.

Parameters:

Name	Type	Description	Default
`key`	`str`	A chart key from :meth:`list_charts` (e.g. `"todays-top-hits"`).	required
`max_tracks`	`int \| None`	Upper bound on tracks; `None` fetches all.	`100`

Returns:

Type	Description
`Playlist`	The chart's :class:`Playlist`.

Raises:

Type	Description
`URLError`	If `key` is not a known chart.
`SpotifyScraperError`	If the client is closed.

get_related_artists `async` ¶

get_related_artists(value: str) -> tuple[Artist, ...]

Fetch artists related to the given artist (anonymous).

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify artist URL, URI, or 22-character ID.	required

Returns:

Type	Description
`tuple[Artist, ...]`	Related artists (id / uri / name / images); empty if Spotify lists none.

Raises:

Type	Description
`NotFoundError`	If the artist does not exist.
`SpotifyScraperError`	If the client is closed.

get_discography `async` ¶

get_discography(
    value: str, *, max_releases: int | None = None
) -> tuple[AlbumRef, ...]

Fetch an artist's full discography (anonymous), paginating releases.

Returns every release — albums, singles, and compilations — as :class:AlbumRef objects in Spotify's discography order.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify artist URL, URI, or 22-character ID.	required
`max_releases`	`int \| None`	Upper bound on releases; `None` fetches all.	`None`

Returns:

Type	Description
`tuple[AlbumRef, ...]`	The artist's releases.

Raises:

Type	Description
`NotFoundError`	If the artist does not exist.
`SpotifyScraperError`	If the client is closed.

get_similar_albums `async` ¶

get_similar_albums(
    value: str, *, limit: int = 10
) -> tuple[AlbumRef, ...]

Recommend albums similar to a track (anonymous).

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify track URL, URI, or 22-character ID.	required
`limit`	`int`	Maximum recommended albums to request.	`10`

Returns:

Type	Description
`tuple[AlbumRef, ...]`	Recommended albums (empty when Spotify has none).

Raises:

Type	Description
`NotFoundError`	If the track does not exist.
`SpotifyScraperError`	If the client is closed.

get_user `async` ¶

get_user(user_id: str) -> UserProfile

Fetch a public user profile (requires authentication).

Public profiles need the cookie-derived token (the anonymous token is refused with HTTP 403), so the client must have been built with cookies=; otherwise :class:AuthenticationError is raised at once.

Parameters:

Name	Type	Description	Default
`user_id`	`str`	A Spotify user id, `spotify:user:<id>` uri, or profile URL.	required

Returns:

Type	Description
`UserProfile`	The user's public :class:`UserProfile`.

Raises:

Type	Description
`AuthenticationError`	If no cookies were configured, or the cookie is rejected by the token exchange.
`NotFoundError`	If the user does not exist or has no public profile.
`SpotifyScraperError`	If the client is closed.

get_artist_events `async` ¶

get_artist_events(value: str) -> tuple[Concert, ...]

Fetch an artist's upcoming concerts/events (anonymous).

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify artist URL, URI, or 22-character ID.	required

Returns:

Type	Description
`Concert`	Upcoming concerts (empty when Spotify lists none); the set returned
`...`	can vary by the request's region.

Raises:

Type	Description
`NotFoundError`	If the artist does not exist.
`SpotifyScraperError`	If the client is closed.

get_credits `async` ¶

get_credits(value: str) -> Credits

Fetch a track's credits (performers, writers, producers).

Credits are an authenticated feature: the client must have been built with cookies=; otherwise :class:AuthenticationError is raised at once, without any HTTP request.

Parameters:

Name	Type	Description	Default
`value`	`str`	A Spotify track URL, URI, or 22-character ID.	required

Returns:

Type	Description
`Credits`	The track's :class:`Credits`, grouped by role.

Raises:

Type	Description
`AuthenticationError`	If no cookies were configured, or the cookie is rejected by the token exchange.
`NotFoundError`	If the track does not exist or has no credits.
`SpotifyScraperError`	If the client is closed.

download_cover `async` ¶

download_cover(
    entity: HasImagesAndName,
    dest: str | Path = ".",
    *,
    size: ImageSize = "largest",
    filename: str | None = None,
) -> Path

Download an entity's cover art to dest and return its path.

Parameters:

Name	Type	Description	Default
`entity`	`HasImagesAndName`	Any fetched model carrying `name` and `images` (a :class:`Track` falls back to its album's images when empty).	required
`dest`	`str \| Path`	Destination directory; created if it does not exist.	`'.'`
`size`	`ImageSize`	`"largest"` or `"smallest"` of the available images.	`'largest'`
`filename`	`str \| None`	Explicit filename; defaults to a sanitized `<name>.<ext>` (extension from the response content type).	`None`

Returns:

Type	Description
`Path`	The path of the written image.

Raises:

Type	Description
`MediaError`	If the entity has no images.
`SpotifyScraperError`	If the client is closed.

download_preview `async` ¶

download_preview(
    entity: Track | Episode,
    dest: str | Path = ".",
    *,
    filename: str | None = None,
    embed_cover: bool = False,
) -> Path

Download a track or episode preview MP3 and return its path.

Parameters:

Name	Type	Description	Default
`entity`	`Track \| Episode`	A :class:`Track` or :class:`Episode` with a `preview_url`.	required
`dest`	`str \| Path`	Destination directory; created if it does not exist.	`'.'`
`filename`	`str \| None`	Explicit filename; defaults to a sanitized `<name>.mp3`.	`None`
`embed_cover`	`bool`	When `True`, embed the entity's cover art and basic tags via mutagen (the `media` extra).	`False`

Returns:

Type	Description
`Path`	The path of the written MP3.

Raises:

Type	Description
`MediaError`	If no preview exists, or `embed_cover` is requested without mutagen installed.
`SpotifyScraperError`	If the client is closed.

aclose `async` ¶

aclose() -> None

Close the owned transport and mark the client closed.

aenter `async` ¶

__aenter__() -> AsyncSpotifyClient

Return the client for use in an async with block.

aexit `async` ¶

__aexit__(
    exc_type: type[BaseException] | None,
    exc: BaseException | None,
    tb: TracebackType | None,
) -> None

Close the client on exiting an async with block.

Async client¶

spotify_scraper.AsyncSpotifyClient ¶

login async ¶

from_saved_session classmethod ¶

logout classmethod ¶

session_info classmethod ¶

get_track async ¶

get_album async ¶

get_artist async ¶

get_playlist async ¶

get_episode async ¶

get_show async ¶

get_tracks async ¶

get_albums async ¶

get_artists async ¶

get_episodes async ¶

get_playlists async ¶

get_shows async ¶

get_lyrics async ¶

get_transcript async ¶

get_account async ¶

is_premium async ¶

search async ¶

get_colors async ¶

get_canvas async ¶

download_canvas async ¶

list_charts ¶

get_chart async ¶

get_related_artists async ¶

get_discography async ¶

get_similar_albums async ¶

get_user async ¶

get_artist_events async ¶

get_credits async ¶

download_cover async ¶

download_preview async ¶

aclose async ¶

__aenter__ async ¶

__aexit__ async ¶

login `async` ¶

from_saved_session `classmethod` ¶

logout `classmethod` ¶

session_info `classmethod` ¶

get_track `async` ¶

get_album `async` ¶

get_artist `async` ¶

get_playlist `async` ¶

get_episode `async` ¶

get_show `async` ¶

get_tracks `async` ¶

get_albums `async` ¶

get_artists `async` ¶

get_episodes `async` ¶

get_playlists `async` ¶

get_shows `async` ¶

get_lyrics `async` ¶

get_transcript `async` ¶

get_account `async` ¶

is_premium `async` ¶

search `async` ¶

get_colors `async` ¶

get_canvas `async` ¶

download_canvas `async` ¶

get_chart `async` ¶

get_related_artists `async` ¶

get_discography `async` ¶

get_similar_albums `async` ¶

get_user `async` ¶

get_artist_events `async` ¶

get_credits `async` ¶

download_cover `async` ¶

download_preview `async` ¶

aclose `async` ¶

aenter `async` ¶

aexit `async` ¶