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 +80 -0
- fmscrape/api/__init__.py +2 -0
- fmscrape/api/album.py +80 -0
- fmscrape/api/artist.py +265 -0
- fmscrape/api/auth.py +21 -0
- fmscrape/api/base.py +185 -0
- fmscrape/api/chart.py +71 -0
- fmscrape/api/geo.py +22 -0
- fmscrape/api/library.py +272 -0
- fmscrape/api/tag.py +174 -0
- fmscrape/api/track.py +144 -0
- fmscrape/api/user.py +638 -0
- fmscrape/client.py +474 -0
- fmscrape/errors.py +37 -0
- fmscrape/models.py +594 -0
- fmscrape/normalize.py +80 -0
- fmscrape/parsers/__init__.py +2 -0
- fmscrape/parsers/album.py +152 -0
- fmscrape/parsers/artist.py +305 -0
- fmscrape/parsers/chart.py +118 -0
- fmscrape/parsers/common.py +120 -0
- fmscrape/parsers/tag.py +207 -0
- fmscrape/parsers/track.py +184 -0
- fmscrape/parsers/user_lists.py +462 -0
- fmscrape/parsers/user_recent.py +190 -0
- fmscrape-0.1.0.dist-info/METADATA +126 -0
- fmscrape-0.1.0.dist-info/RECORD +29 -0
- fmscrape-0.1.0.dist-info/WHEEL +5 -0
- fmscrape-0.1.0.dist-info/top_level.txt +1 -0
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
|
+
]
|
fmscrape/api/__init__.py
ADDED
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
|
+
|