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,
)

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

get_track async

get_track(value: str) -> 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

Returns:

Type	Description
Track	The richest available :class:Track.

Raises:

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

get_album async

get_album(value: str) -> 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

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
NotFoundError	If the album does not exist.
SpotifyScraperError	If the client is closed.

get_artist async

get_artist(value: str) -> 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

Returns:

Type	Description
Artist	The richest available :class:Artist.

Raises:

Type	Description
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
) -> 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

Returns:

Type	Description
Playlist	The richest available :class:Playlist.

Raises:

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

get_episode async

get_episode(value: str) -> 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

Returns:

Type	Description
Episode	The richest available :class:Episode.

Raises:

Type	Description
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
) -> 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

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
NotFoundError	If the show does not exist.
SpotifyScraperError	If the client is 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.

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.