HTTP & config¶

These objects tune the client's outbound HTTP behaviour. Pass RateLimit and RetryPolicy to either client's constructor; both are frozen dataclasses with safe defaults. The Anti-ban guide explains when to adjust them.

RateLimit¶

spotify_scraper.http.RateLimit `dataclass` ¶

RateLimit(per_second: float = 2.0, burst: int = 5)

Token-bucket configuration.

Attributes:

Name	Type	Description
`per_second`	`float`	Sustained request rate (token refill rate).
`burst`	`int`	Bucket capacity — how many requests may go out instantly.

__post_init__ ¶

__post_init__() -> None

Reject nonsensical limits that would stall or divide by zero.

RetryPolicy¶

spotify_scraper.http.RetryPolicy `dataclass` ¶

RetryPolicy(
    max_attempts: int = 4,
    backoff_base: float = 0.5,
    backoff_max: float = 30.0,
)

Retry configuration for a transport.

Attributes:

Name	Type	Description
`max_attempts`	`int`	Total attempts allowed, including the first request.
`backoff_base`	`float`	Delay in seconds before the second attempt; doubles on each subsequent retry.
`backoff_max`	`float`	Ceiling in seconds for any single computed delay; a `Retry-After` hint above this budget aborts retrying.

Per-host throttling¶

A client accepts host_rate_limits, a mapping of host name to RateLimit, to override the global rate for specific hosts. The pathfinder GraphQL host is exposed as a constant for exactly this purpose:

from spotify_scraper import RateLimit, SpotifyClient
from spotify_scraper.http.ratelimit import PARTNER_API_HOST

client = SpotifyClient(
    host_rate_limits={PARTNER_API_HOST: RateLimit(per_second=1.0, burst=2)},
)

spotify_scraper.http.ratelimit.PARTNER_API_HOST `module-attribute` ¶

PARTNER_API_HOST = 'api-partner.spotify.com'

spotify_scraper.http.ratelimit.resolve_rate_limit ¶

resolve_rate_limit(
    host: str,
    default: RateLimit | None,
    overrides: Mapping[str, RateLimit],
) -> RateLimit

Pick the rate limit for a host.

An explicit per-host override wins; otherwise the global default (or the built-in :class:RateLimit when none was supplied) applies.

Parameters:

Name	Type	Description	Default
`host`	`str`	Destination host name.	required
`default`	`RateLimit \| None`	Caller-supplied global rate, or `None` for the built-in.	required
`overrides`	`Mapping[str, RateLimit]`	Per-host rate overrides (always win).	required

Returns:

Name	Type	Description
`The`	`RateLimit`	class:`RateLimit` to throttle `host` with.