Batch helpers¶

Each entity getter has a plural sibling — get_tracks, get_albums, get_artists, get_playlists, get_episodes, get_shows — that fetches many inputs in one call and returns one BatchItem per input, index- aligned with what you passed in.

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    items = client.get_tracks([
        "4uLU6hMCjMI75M1A2tKUQC",
        "spotify:track:0VjIjW4GlUZAMYd2vXMi3b",
        "this-is-not-valid",
    ])

for item in items:
    if item.ok:
        print(item.result.name)
    else:
        print("failed:", item.value, "->", item.error)

Partial failure never aborts the batch¶

A single dead or malformed input does not raise or stop the others — its outcome is captured on that one BatchItem instead. Exactly one of result / error is populated, and the input value is echoed back so you can correlate outcomes even after deduplication or reordering:

item.ok — True when the fetch succeeded;
item.result — the typed model on success, else None;
item.error — the captured SpotifyScraperError on failure, else None;
item.unwrap() — returns the model, or re-raises the captured error.

ok = [i.result for i in items if i.ok]
failed = {i.value: i.error for i in items if not i.ok}

Async + managed concurrency¶

The async client runs batch fetches concurrently, bounded by the client's max_concurrency (default 5) so it never floods Spotify; the per-host rate limiter still governs request pacing on top of that.

from spotify_scraper import AsyncSpotifyClient

async with AsyncSpotifyClient(max_concurrency=8) as client:
    items = await client.get_tracks([id1, id2, id3, ...])

The sync helpers fetch sequentially. Both return the same BatchItem shape.

`BatchItem`¶

spotify_scraper.batch.BatchItem `dataclass` ¶

BatchItem(
    value: str,
    result: _T | None = None,
    error: Exception | None = None,
)

Bases: Generic[_T]

One ordered, index-aligned outcome from a plural batch helper.

Exactly one of result / error is populated: the model on success, or the captured :class:~spotify_scraper.errors.SpotifyScraperError on failure. The input value is echoed back so callers can correlate the outcome with the input even after reordering or deduplication.

Attributes:

Name	Type	Description
`value`	`str`	The input URL, URI, or ID, echoed back.
`result`	`_T \| None`	The fetched model on success, else `None`.
`error`	`Exception \| None`	The captured exception on failure, else `None`.

ok `property` ¶

ok: bool

Whether the fetch succeeded (error is None).

unwrap ¶

unwrap() -> _T

Return the model on success, or re-raise the captured error.

Returns:

Type	Description
`_T`	The fetched model when this item succeeded.

Raises:

Type	Description
`Exception`	The captured error when this item failed.