Client¶

SpotifyClient is the synchronous facade. It owns an HTTP transport and an anonymous token provider, exposes one get_* method per entity type plus the media download helpers, and works as a context manager. See the Entities guide for task-oriented examples.

spotify_scraper.SpotifyClient ¶

SpotifyClient(
    *,
    rate_limit: RateLimit | None = None,
    retry: RetryPolicy | None = None,
    proxy: str | None = None,
    user_agent: str | None = None,
    timeout: float = 10.0,
    transport: Transport | None = None,
    cookies: str | Path | Mapping[str, str] | None = None,
    host_rate_limits: Mapping[str, RateLimit] | None = None,
)

Synchronous client for extracting public Spotify data.

The client is a context manager and should be closed when done, either via with or by calling :meth:close. 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`	`Transport \| 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 ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 ¶

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.

close ¶

close() -> None

Close the owned transport and mark the client closed.

enter ¶

__enter__() -> SpotifyClient

Return the client for use in a with block.

exit ¶

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

Close the client on exiting a with block.

Client¶

spotify_scraper.SpotifyClient ¶

get_track ¶

get_album ¶

get_artist ¶

get_playlist ¶

get_episode ¶

get_show ¶

get_lyrics ¶

download_cover ¶

download_preview ¶

close ¶

__enter__ ¶

__exit__ ¶

enter ¶

exit ¶