fmscrape 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of fmscrape might be problematic. Click here for more details.

fmscrape/__init__.py ADDED
@@ -0,0 +1,80 @@
1
+ """fmscrape: Last.fm public HTML scraper with an API-compatible interface."""
2
+
3
+ from fmscrape.client import AsyncLastFmClient, LastFmClient
4
+ from fmscrape.errors import (
5
+ FmScrapeError,
6
+ NetworkError,
7
+ NotFoundError,
8
+ NotSupportedError,
9
+ ParseError,
10
+ RateLimitError,
11
+ RobotsDisallowedError,
12
+ )
13
+ from fmscrape.models import (
14
+ AlbumEntry,
15
+ AlbumInfo,
16
+ AlbumListPage,
17
+ AlbumRef,
18
+ ArtistEntry,
19
+ ArtistInfo,
20
+ ArtistListPage,
21
+ ArtistRef,
22
+ CorrectionResult,
23
+ DateInfo,
24
+ FriendsPage,
25
+ Image,
26
+ LibraryPlays,
27
+ PaginationAttr,
28
+ RecentTrack,
29
+ RecentTracksPage,
30
+ SearchResultsPage,
31
+ StatsInfo,
32
+ TagDetails,
33
+ TagInfo,
34
+ TagsListResult,
35
+ TrackEntry,
36
+ TrackInfo,
37
+ TrackListPage,
38
+ UserEntry,
39
+ UserInfo,
40
+ WikiInfo,
41
+ )
42
+
43
+ __all__ = [
44
+ "AlbumEntry",
45
+ "AlbumInfo",
46
+ "AlbumListPage",
47
+ "AlbumRef",
48
+ "ArtistEntry",
49
+ "ArtistInfo",
50
+ "ArtistListPage",
51
+ "ArtistRef",
52
+ "AsyncLastFmClient",
53
+ "CorrectionResult",
54
+ "DateInfo",
55
+ "FmScrapeError",
56
+ "FriendsPage",
57
+ "Image",
58
+ "LastFmClient",
59
+ "LibraryPlays",
60
+ "NetworkError",
61
+ "NotFoundError",
62
+ "NotSupportedError",
63
+ "PaginationAttr",
64
+ "ParseError",
65
+ "RateLimitError",
66
+ "RecentTrack",
67
+ "RecentTracksPage",
68
+ "RobotsDisallowedError",
69
+ "SearchResultsPage",
70
+ "StatsInfo",
71
+ "TagDetails",
72
+ "TagInfo",
73
+ "TagsListResult",
74
+ "TrackEntry",
75
+ "TrackInfo",
76
+ "TrackListPage",
77
+ "UserEntry",
78
+ "UserInfo",
79
+ "WikiInfo",
80
+ ]
@@ -0,0 +1,2 @@
1
+ """API namespace modules mirroring Last.fm API v2."""
2
+
fmscrape/api/album.py ADDED
@@ -0,0 +1,80 @@
1
+ """Album API endpoints (`album.*`)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING, Any
6
+
7
+ from fmscrape.api.base import build_music_path
8
+ from fmscrape.errors import NotSupportedError
9
+ from fmscrape.parsers.album import (
10
+ parse_album_info,
11
+ parse_album_search,
12
+ parse_album_top_tags,
13
+ )
14
+
15
+ if TYPE_CHECKING:
16
+ from fmscrape.client import AsyncLastFmClient, LastFmClient
17
+
18
+
19
+ class _AlbumWriteNotSupported:
20
+ def add_tags(self, artist: str, album: str, tags: list[str] | str) -> Any:
21
+ raise NotSupportedError("album.add_tags requires Last.fm authentication.")
22
+
23
+ def remove_tag(self, artist: str, album: str, tag: str) -> Any:
24
+ raise NotSupportedError("album.remove_tag requires Last.fm authentication.")
25
+
26
+
27
+ class AlbumAPI(_AlbumWriteNotSupported):
28
+ """Synchronous `album.*` methods."""
29
+
30
+ def __init__(self, client: LastFmClient) -> None:
31
+ self._client = client
32
+
33
+ def get_info(
34
+ self, artist: str, album: str, *, autocorrect: int = 1, lang: str | None = None
35
+ ) -> Any:
36
+ path = build_music_path(artist, album, autocorrect=autocorrect, lang=lang)
37
+ resp = self._client.get(path)
38
+ return self._client.format_result(parse_album_info(resp.text, url=str(resp.url)))
39
+
40
+ def get_top_tags(self, artist: str, album: str, *, autocorrect: int = 1) -> Any:
41
+ path = build_music_path(artist, album, autocorrect=autocorrect, suffix="/+tags")
42
+ resp = self._client.get(path)
43
+ return self._client.format_result(parse_album_top_tags(resp.text, url=str(resp.url)))
44
+
45
+ def search(self, album: str, *, limit: int = 30, page: int = 1) -> Any:
46
+ params: dict[str, Any] = {"q": album}
47
+ if page > 1:
48
+ params["page"] = page
49
+ resp = self._client.get("/search/albums", params=params)
50
+ return self._client.format_result(
51
+ parse_album_search(resp.text, url=str(resp.url), page=page, limit=limit)
52
+ )
53
+
54
+
55
+ class AsyncAlbumAPI(_AlbumWriteNotSupported):
56
+ """Asynchronous `album.*` methods."""
57
+
58
+ def __init__(self, client: AsyncLastFmClient) -> None:
59
+ self._client = client
60
+
61
+ async def get_info(
62
+ self, artist: str, album: str, *, autocorrect: int = 1, lang: str | None = None
63
+ ) -> Any:
64
+ path = build_music_path(artist, album, autocorrect=autocorrect, lang=lang)
65
+ resp = await self._client.get(path)
66
+ return self._client.format_result(parse_album_info(resp.text, url=str(resp.url)))
67
+
68
+ async def get_top_tags(self, artist: str, album: str, *, autocorrect: int = 1) -> Any:
69
+ path = build_music_path(artist, album, autocorrect=autocorrect, suffix="/+tags")
70
+ resp = await self._client.get(path)
71
+ return self._client.format_result(parse_album_top_tags(resp.text, url=str(resp.url)))
72
+
73
+ async def search(self, album: str, *, limit: int = 30, page: int = 1) -> Any:
74
+ params: dict[str, Any] = {"q": album}
75
+ if page > 1:
76
+ params["page"] = page
77
+ resp = await self._client.get("/search/albums", params=params)
78
+ return self._client.format_result(
79
+ parse_album_search(resp.text, url=str(resp.url), page=page, limit=limit)
80
+ )
fmscrape/api/artist.py ADDED
@@ -0,0 +1,265 @@
1
+ """Artist API endpoints (`artist.*`)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterator
6
+ from typing import TYPE_CHECKING, Any
7
+
8
+ from bs4 import BeautifulSoup
9
+
10
+ from fmscrape.api.base import build_music_path, iter_paginated
11
+ from fmscrape.errors import FmScrapeError, NotSupportedError
12
+ from fmscrape.models import (
13
+ AlbumListPage,
14
+ ArtistInfo,
15
+ CorrectionResult,
16
+ TrackListPage,
17
+ )
18
+ from fmscrape.parsers.artist import (
19
+ parse_artist_info,
20
+ parse_artist_search,
21
+ parse_artist_similar,
22
+ parse_artist_top_albums,
23
+ parse_artist_top_tags,
24
+ parse_artist_top_tracks,
25
+ )
26
+ from fmscrape.parsers.common import parse_wiki
27
+
28
+ if TYPE_CHECKING:
29
+ from fmscrape.client import AsyncLastFmClient, LastFmClient
30
+
31
+
32
+ class _ArtistWriteNotSupported:
33
+ def add_tags(self, artist: str, tags: list[str] | str) -> Any:
34
+ raise NotSupportedError("artist.add_tags requires Last.fm authentication.")
35
+
36
+ def remove_tag(self, artist: str, tag: str) -> Any:
37
+ raise NotSupportedError("artist.remove_tag requires Last.fm authentication.")
38
+
39
+
40
+ def _merge_full_wiki(info: ArtistInfo, wiki_html: str) -> ArtistInfo:
41
+ full_wiki = parse_wiki(BeautifulSoup(wiki_html, "lxml"), is_full_page=True)
42
+ if full_wiki.content:
43
+ info.bio.content = full_wiki.content
44
+ if full_wiki.published:
45
+ info.bio.published = full_wiki.published
46
+ return info
47
+
48
+
49
+ class ArtistAPI(_ArtistWriteNotSupported):
50
+ """Synchronous `artist.*` methods."""
51
+
52
+ def __init__(self, client: LastFmClient) -> None:
53
+ self._client = client
54
+
55
+ def _get_info_model(
56
+ self,
57
+ artist: str,
58
+ *,
59
+ autocorrect: int = 1,
60
+ lang: str | None = None,
61
+ fetch_full_bio: bool = True,
62
+ ) -> ArtistInfo:
63
+ path = build_music_path(artist, autocorrect=autocorrect, lang=lang)
64
+ resp = self._client.get(path)
65
+ info = parse_artist_info(resp.text, url=str(resp.url))
66
+ if fetch_full_bio:
67
+ try:
68
+ wiki_resp = self._client.get(f"{path}/+wiki")
69
+ _merge_full_wiki(info, wiki_resp.text)
70
+ except FmScrapeError:
71
+ pass
72
+ return info
73
+
74
+ def get_info(
75
+ self,
76
+ artist: str,
77
+ *,
78
+ autocorrect: int = 1,
79
+ lang: str | None = None,
80
+ fetch_full_bio: bool = True,
81
+ ) -> Any:
82
+ return self._client.format_result(
83
+ self._get_info_model(
84
+ artist, autocorrect=autocorrect, lang=lang, fetch_full_bio=fetch_full_bio
85
+ )
86
+ )
87
+
88
+ def get_similar(
89
+ self,
90
+ artist: str,
91
+ *,
92
+ limit: int = 50,
93
+ page: int = 1,
94
+ autocorrect: int = 1,
95
+ ) -> Any:
96
+ path = build_music_path(artist, autocorrect=autocorrect, suffix="/+similar")
97
+ params = {"page": page} if page > 1 else None
98
+ resp = self._client.get(path, params=params)
99
+ return self._client.format_result(
100
+ parse_artist_similar(resp.text, url=str(resp.url), artist=artist, page=page, limit=limit)
101
+ )
102
+
103
+ def _get_top_albums_page(
104
+ self, artist: str, *, limit: int = 50, page: int = 1, autocorrect: int = 1
105
+ ) -> AlbumListPage:
106
+ path = build_music_path(artist, autocorrect=autocorrect, suffix="/+albums")
107
+ params = {"page": page} if page > 1 else None
108
+ resp = self._client.get(path, params=params)
109
+ return parse_artist_top_albums(resp.text, url=str(resp.url), artist=artist, page=page, limit=limit)
110
+
111
+ def get_top_albums(
112
+ self, artist: str, *, limit: int = 50, page: int = 1, autocorrect: int = 1
113
+ ) -> Any:
114
+ return self._client.format_result(
115
+ self._get_top_albums_page(artist, limit=limit, page=page, autocorrect=autocorrect)
116
+ )
117
+
118
+ def iter_top_albums(
119
+ self,
120
+ artist: str,
121
+ *,
122
+ limit: int = 50,
123
+ start_page: int = 1,
124
+ max_pages: int | None = None,
125
+ autocorrect: int = 1,
126
+ ) -> Iterator[Any]:
127
+ return iter_paginated(
128
+ lambda p: self._get_top_albums_page(artist, limit=limit, page=p, autocorrect=autocorrect),
129
+ lambda r: r.albums,
130
+ start_page=start_page,
131
+ max_pages=max_pages,
132
+ raw_json=self._client.raw_json,
133
+ )
134
+
135
+ def _get_top_tracks_page(
136
+ self, artist: str, *, limit: int = 50, page: int = 1, autocorrect: int = 1
137
+ ) -> TrackListPage:
138
+ path = build_music_path(artist, autocorrect=autocorrect, suffix="/+tracks")
139
+ params = {"page": page} if page > 1 else None
140
+ resp = self._client.get(path, params=params)
141
+ return parse_artist_top_tracks(resp.text, url=str(resp.url), artist=artist, page=page, limit=limit)
142
+
143
+ def get_top_tracks(
144
+ self, artist: str, *, limit: int = 50, page: int = 1, autocorrect: int = 1
145
+ ) -> Any:
146
+ return self._client.format_result(
147
+ self._get_top_tracks_page(artist, limit=limit, page=page, autocorrect=autocorrect)
148
+ )
149
+
150
+ def iter_top_tracks(
151
+ self,
152
+ artist: str,
153
+ *,
154
+ limit: int = 50,
155
+ start_page: int = 1,
156
+ max_pages: int | None = None,
157
+ autocorrect: int = 1,
158
+ ) -> Iterator[Any]:
159
+ return iter_paginated(
160
+ lambda p: self._get_top_tracks_page(artist, limit=limit, page=p, autocorrect=autocorrect),
161
+ lambda r: r.tracks,
162
+ start_page=start_page,
163
+ max_pages=max_pages,
164
+ raw_json=self._client.raw_json,
165
+ )
166
+
167
+ def get_top_tags(self, artist: str, *, autocorrect: int = 1) -> Any:
168
+ path = build_music_path(artist, autocorrect=autocorrect, suffix="/+tags")
169
+ resp = self._client.get(path)
170
+ return self._client.format_result(parse_artist_top_tags(resp.text, url=str(resp.url)))
171
+
172
+ def get_correction(self, artist: str) -> Any:
173
+ info = self._get_info_model(artist, autocorrect=1, fetch_full_bio=False)
174
+ return self._client.format_result(CorrectionResult(name=info.name, url=info.url))
175
+
176
+ def search(self, artist: str, *, limit: int = 20, page: int = 1) -> Any:
177
+ params: dict[str, Any] = {"q": artist}
178
+ if page > 1:
179
+ params["page"] = page
180
+ resp = self._client.get("/search/artists", params=params)
181
+ return self._client.format_result(
182
+ parse_artist_search(resp.text, url=str(resp.url), page=page, limit=limit)
183
+ )
184
+
185
+
186
+ class AsyncArtistAPI(_ArtistWriteNotSupported):
187
+ """Asynchronous `artist.*` methods."""
188
+
189
+ def __init__(self, client: AsyncLastFmClient) -> None:
190
+ self._client = client
191
+
192
+ async def _get_info_model(
193
+ self,
194
+ artist: str,
195
+ *,
196
+ autocorrect: int = 1,
197
+ lang: str | None = None,
198
+ fetch_full_bio: bool = True,
199
+ ) -> ArtistInfo:
200
+ path = build_music_path(artist, autocorrect=autocorrect, lang=lang)
201
+ resp = await self._client.get(path)
202
+ info = parse_artist_info(resp.text, url=str(resp.url))
203
+ if fetch_full_bio:
204
+ try:
205
+ wiki_resp = await self._client.get(f"{path}/+wiki")
206
+ _merge_full_wiki(info, wiki_resp.text)
207
+ except FmScrapeError:
208
+ pass
209
+ return info
210
+
211
+ async def get_info(
212
+ self,
213
+ artist: str,
214
+ *,
215
+ autocorrect: int = 1,
216
+ lang: str | None = None,
217
+ fetch_full_bio: bool = True,
218
+ ) -> Any:
219
+ return self._client.format_result(
220
+ await self._get_info_model(
221
+ artist, autocorrect=autocorrect, lang=lang, fetch_full_bio=fetch_full_bio
222
+ )
223
+ )
224
+
225
+ async def get_similar(self, artist: str, *, limit: int = 50, page: int = 1, autocorrect: int = 1) -> Any:
226
+ path = build_music_path(artist, autocorrect=autocorrect, suffix="/+similar")
227
+ params = {"page": page} if page > 1 else None
228
+ resp = await self._client.get(path, params=params)
229
+ return self._client.format_result(
230
+ parse_artist_similar(resp.text, url=str(resp.url), artist=artist, page=page, limit=limit)
231
+ )
232
+
233
+ async def get_top_albums(self, artist: str, *, limit: int = 50, page: int = 1, autocorrect: int = 1) -> Any:
234
+ path = build_music_path(artist, autocorrect=autocorrect, suffix="/+albums")
235
+ params = {"page": page} if page > 1 else None
236
+ resp = await self._client.get(path, params=params)
237
+ return self._client.format_result(
238
+ parse_artist_top_albums(resp.text, url=str(resp.url), artist=artist, page=page, limit=limit)
239
+ )
240
+
241
+ async def get_top_tracks(self, artist: str, *, limit: int = 50, page: int = 1, autocorrect: int = 1) -> Any:
242
+ path = build_music_path(artist, autocorrect=autocorrect, suffix="/+tracks")
243
+ params = {"page": page} if page > 1 else None
244
+ resp = await self._client.get(path, params=params)
245
+ return self._client.format_result(
246
+ parse_artist_top_tracks(resp.text, url=str(resp.url), artist=artist, page=page, limit=limit)
247
+ )
248
+
249
+ async def get_top_tags(self, artist: str, *, autocorrect: int = 1) -> Any:
250
+ path = build_music_path(artist, autocorrect=autocorrect, suffix="/+tags")
251
+ resp = await self._client.get(path)
252
+ return self._client.format_result(parse_artist_top_tags(resp.text, url=str(resp.url)))
253
+
254
+ async def get_correction(self, artist: str) -> Any:
255
+ info = await self._get_info_model(artist, autocorrect=1, fetch_full_bio=False)
256
+ return self._client.format_result(CorrectionResult(name=info.name, url=info.url))
257
+
258
+ async def search(self, artist: str, *, limit: int = 20, page: int = 1) -> Any:
259
+ params: dict[str, Any] = {"q": artist}
260
+ if page > 1:
261
+ params["page"] = page
262
+ resp = await self._client.get("/search/artists", params=params)
263
+ return self._client.format_result(
264
+ parse_artist_search(resp.text, url=str(resp.url), page=page, limit=limit)
265
+ )
fmscrape/api/auth.py ADDED
@@ -0,0 +1,21 @@
1
+ """Auth API endpoints (`auth.*`) — out of scope, require authentication."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from fmscrape.errors import NotSupportedError
8
+
9
+
10
+ class AuthAPI:
11
+ """All `auth.*` methods raise NotSupportedError."""
12
+
13
+ def get_token(self, *args: Any, **kwargs: Any) -> Any:
14
+ raise NotSupportedError("auth.get_token requires Last.fm API authentication and is out of scope.")
15
+
16
+ def get_session(self, *args: Any, **kwargs: Any) -> Any:
17
+ raise NotSupportedError("auth.get_session requires Last.fm API authentication and is out of scope.")
18
+
19
+ def get_mobile_session(self, *args: Any, **kwargs: Any) -> Any:
20
+ raise NotSupportedError("auth.get_mobile_session requires Last.fm API authentication and is out of scope.")
21
+
fmscrape/api/base.py ADDED
@@ -0,0 +1,185 @@
1
+ """Shared pagination, URL encoding, and period validation helpers for API modules."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
6
+ from datetime import date, datetime, timezone, tzinfo
7
+ from typing import Any, TypeVar
8
+ from urllib.parse import quote_plus
9
+ from zoneinfo import ZoneInfo
10
+
11
+ from fmscrape.errors import NotSupportedError
12
+
13
+ VALID_PERIODS = ("overall", "7day", "1month", "3month", "6month", "12month")
14
+
15
+ PERIOD_TO_DATE_PRESET: dict[str, str] = {
16
+ "overall": "ALL",
17
+ "7day": "LAST_7_DAYS",
18
+ "1month": "LAST_30_DAYS",
19
+ "3month": "LAST_90_DAYS",
20
+ "6month": "LAST_180_DAYS",
21
+ "12month": "LAST_365_DAYS",
22
+ }
23
+
24
+ _T = TypeVar("_T")
25
+
26
+
27
+ def ts_to_date_str(ts: int) -> str:
28
+ """Convert a UTC unix timestamp into Last.fm's YYYY-MM-DD query format."""
29
+ return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d")
30
+
31
+
32
+ def encode_music_part(value: str) -> str:
33
+ """Encode an artist, album, or track name using Last.fm's `+` space convention."""
34
+ return quote_plus(value.strip())
35
+
36
+
37
+ def lang_prefix(lang: str | None) -> str:
38
+ """Return optional Last.fm language path prefix (e.g. '/pt') for non-English locales."""
39
+ if not lang or lang.lower() in ("en", "en-us", "en-gb"):
40
+ return ""
41
+ clean = lang.strip().lower().split("-")[0]
42
+ return f"/{clean}"
43
+
44
+
45
+ def build_music_path(
46
+ *parts: str,
47
+ autocorrect: int = 1,
48
+ lang: str | None = None,
49
+ suffix: str = "",
50
+ ) -> str:
51
+ """Build a `/music/...` URL path with optional lang prefix, noredirect, and suffix."""
52
+ prefix = lang_prefix(lang)
53
+ encoded = "/".join(p if p == "_" else encode_music_part(p) for p in parts)
54
+ base = f"{prefix}/music/+noredirect/{encoded}" if autocorrect == 0 else f"{prefix}/music/{encoded}"
55
+ return f"{base}{suffix}"
56
+
57
+
58
+ def validate_period(period: str, *, method: str, has_cookies: bool) -> str | None:
59
+ """Validate period and return date_preset query value (or None for default overall)."""
60
+ if period not in VALID_PERIODS:
61
+ raise ValueError(f"Invalid period {period!r}; expected one of {VALID_PERIODS}")
62
+ if period == "overall":
63
+ return None
64
+ if not has_cookies:
65
+ raise NotSupportedError(
66
+ f"{method} with period={period!r} redirects to Last.fm login on the public site; "
67
+ "pass user cookies to LastFmClient(cookies=...) or use period='overall'."
68
+ )
69
+ return PERIOD_TO_DATE_PRESET[period]
70
+
71
+
72
+ def normalize_timestamp(
73
+ value: int | str | date | datetime | None,
74
+ tz: str | tzinfo | None = None,
75
+ ) -> int | None:
76
+ """Convert int, ISO date/datetime string, date, or datetime to a UTC Unix timestamp."""
77
+ if value is None:
78
+ return None
79
+ if isinstance(value, int) and not isinstance(value, bool):
80
+ return value
81
+ if isinstance(value, str):
82
+ stripped = value.strip()
83
+ if stripped.isdigit():
84
+ return int(stripped)
85
+ dt = datetime.fromisoformat(stripped)
86
+ elif isinstance(value, datetime):
87
+ dt = value
88
+ elif isinstance(value, date):
89
+ dt = datetime(value.year, value.month, value.day)
90
+ else:
91
+ raise TypeError(f"Unsupported timestamp value: {value!r}")
92
+
93
+ if dt.tzinfo is None:
94
+ zone: tzinfo = timezone.utc
95
+ if isinstance(tz, str):
96
+ zone = ZoneInfo(tz)
97
+ elif tz is not None:
98
+ zone = tz
99
+ dt = dt.replace(tzinfo=zone)
100
+ return int(dt.astimezone(timezone.utc).timestamp())
101
+
102
+
103
+ def library_filter_params(
104
+ *,
105
+ period: str | None = None,
106
+ from_ts: int | str | date | datetime | None = None,
107
+ to_ts: int | str | date | datetime | None = None,
108
+ tz: str | tzinfo | None = None,
109
+ page: int = 1,
110
+ has_cookies: bool,
111
+ method: str,
112
+ ) -> dict[str, Any]:
113
+ """Build query parameters for Last.fm library endpoints (date_preset, Unix GMT from/to, page)."""
114
+ params: dict[str, Any] = {}
115
+ if from_ts is not None or to_ts is not None:
116
+ if not has_cookies:
117
+ raise NotSupportedError(
118
+ f"{method} with from_ts/to_ts requires user cookies on last.fm."
119
+ )
120
+ f_uts = normalize_timestamp(from_ts, tz=tz)
121
+ t_uts = normalize_timestamp(to_ts, tz=tz)
122
+ if f_uts is not None:
123
+ params["from"] = str(f_uts)
124
+ if t_uts is not None:
125
+ params["to"] = str(t_uts)
126
+ elif period is not None:
127
+ preset = validate_period(period, method=method, has_cookies=has_cookies)
128
+ if preset is not None:
129
+ params["date_preset"] = preset
130
+ if page > 1:
131
+ params["page"] = page
132
+ return params
133
+
134
+
135
+ def iter_paginated(
136
+ fetch_page: Callable[[int], Any],
137
+ extract_items: Callable[[Any], list[_T]],
138
+ *,
139
+ start_page: int = 1,
140
+ max_pages: int | None = None,
141
+ raw_json: bool = True,
142
+ ) -> Iterator[Any]:
143
+ """Synchronously iterate across paginated Last.fm results."""
144
+ page = start_page
145
+ fetched = 0
146
+ while True:
147
+ result = fetch_page(page)
148
+ items = extract_items(result)
149
+ if not items:
150
+ break
151
+ for item in items:
152
+ yield item.to_dict() if raw_json and hasattr(item, "to_dict") else item
153
+ fetched += 1
154
+ if max_pages is not None and fetched >= max_pages:
155
+ break
156
+ if page >= result.attr.total_pages:
157
+ break
158
+ page += 1
159
+
160
+
161
+ async def aiter_paginated(
162
+ fetch_page: Callable[[int], Awaitable[Any]],
163
+ extract_items: Callable[[Any], list[_T]],
164
+ *,
165
+ start_page: int = 1,
166
+ max_pages: int | None = None,
167
+ raw_json: bool = True,
168
+ ) -> AsyncIterator[Any]:
169
+ """Asynchronously iterate across paginated Last.fm results."""
170
+ page = start_page
171
+ fetched = 0
172
+ while True:
173
+ result = await fetch_page(page)
174
+ items = extract_items(result)
175
+ if not items:
176
+ break
177
+ for item in items:
178
+ yield item.to_dict() if raw_json and hasattr(item, "to_dict") else item
179
+ fetched += 1
180
+ if max_pages is not None and fetched >= max_pages:
181
+ break
182
+ if page >= result.attr.total_pages:
183
+ break
184
+ page += 1
185
+