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/api/chart.py ADDED
@@ -0,0 +1,71 @@
1
+ """Chart API endpoints (`chart.*`)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterator
6
+ from typing import TYPE_CHECKING, Any
7
+
8
+ from fmscrape.api.base import iter_paginated
9
+ from fmscrape.errors import NotSupportedError
10
+ from fmscrape.models import ArtistListPage
11
+ from fmscrape.parsers.chart import parse_chart_top_artists, parse_chart_top_tracks
12
+
13
+ if TYPE_CHECKING:
14
+ from fmscrape.client import AsyncLastFmClient, LastFmClient
15
+
16
+
17
+ class _ChartNotSupportedMixin:
18
+ def get_top_tags(self, **kwargs: Any) -> Any:
19
+ raise NotSupportedError("chart.get_top_tags is not available on Last.fm public /charts pages.")
20
+
21
+
22
+ class ChartAPI(_ChartNotSupportedMixin):
23
+ """Synchronous `chart.*` methods."""
24
+
25
+ def __init__(self, client: LastFmClient) -> None:
26
+ self._client = client
27
+
28
+ def _get_top_artists_page(self, *, limit: int = 50, page: int = 1) -> ArtistListPage:
29
+ params = {"page": page} if page > 1 else None
30
+ resp = self._client.get("/charts/weekly", params=params)
31
+ return parse_chart_top_artists(resp.text, url=str(resp.url), page=page, limit=limit)
32
+
33
+ def get_top_artists(self, *, limit: int = 50, page: int = 1) -> Any:
34
+ return self._client.format_result(self._get_top_artists_page(limit=limit, page=page))
35
+
36
+ def iter_top_artists(
37
+ self, *, limit: int = 50, start_page: int = 1, max_pages: int | None = None
38
+ ) -> Iterator[Any]:
39
+ return iter_paginated(
40
+ lambda p: self._get_top_artists_page(limit=limit, page=p),
41
+ lambda r: r.artists,
42
+ start_page=start_page,
43
+ max_pages=max_pages,
44
+ raw_json=self._client.raw_json,
45
+ )
46
+
47
+ def get_top_tracks(self, *, limit: int = 50, page: int = 1) -> Any:
48
+ resp = self._client.get("/charts")
49
+ return self._client.format_result(
50
+ parse_chart_top_tracks(resp.text, url=str(resp.url), limit=limit)
51
+ )
52
+
53
+
54
+ class AsyncChartAPI(_ChartNotSupportedMixin):
55
+ """Asynchronous `chart.*` methods."""
56
+
57
+ def __init__(self, client: AsyncLastFmClient) -> None:
58
+ self._client = client
59
+
60
+ async def get_top_artists(self, *, limit: int = 50, page: int = 1) -> Any:
61
+ params = {"page": page} if page > 1 else None
62
+ resp = await self._client.get("/charts/weekly", params=params)
63
+ return self._client.format_result(
64
+ parse_chart_top_artists(resp.text, url=str(resp.url), page=page, limit=limit)
65
+ )
66
+
67
+ async def get_top_tracks(self, *, limit: int = 50, page: int = 1) -> Any:
68
+ resp = await self._client.get("/charts")
69
+ return self._client.format_result(
70
+ parse_chart_top_tracks(resp.text, url=str(resp.url), limit=limit)
71
+ )
fmscrape/api/geo.py ADDED
@@ -0,0 +1,22 @@
1
+ """Geo API endpoints (`geo.*`) — unavailable on current public site."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from fmscrape.errors import NotSupportedError
8
+
9
+
10
+ class GeoAPI:
11
+ """`geo.*` methods raise NotSupportedError as `/place/<country>/...` returns 404."""
12
+
13
+ def get_top_artists(self, country: str, **kwargs: Any) -> Any:
14
+ raise NotSupportedError(
15
+ "geo.get_top_artists has no public equivalent on last.fm (/place/<country>/artists returns 404)."
16
+ )
17
+
18
+ def get_top_tracks(self, country: str, **kwargs: Any) -> Any:
19
+ raise NotSupportedError(
20
+ "geo.get_top_tracks has no public equivalent on last.fm (/place/<country>/tracks returns 404)."
21
+ )
22
+
@@ -0,0 +1,272 @@
1
+ """Library API endpoints (`library.*`)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterator
6
+ from datetime import date, datetime, tzinfo
7
+ from typing import TYPE_CHECKING, Any
8
+ from urllib.parse import quote
9
+
10
+ from fmscrape.api.base import encode_music_part, iter_paginated, library_filter_params
11
+ from fmscrape.models import ArtistListPage
12
+ from fmscrape.parsers.user_lists import parse_library_plays, parse_user_top_artists
13
+
14
+ if TYPE_CHECKING:
15
+ from fmscrape.client import AsyncLastFmClient, LastFmClient
16
+
17
+
18
+ class LibraryAPI:
19
+ """Synchronous `library.*` methods."""
20
+
21
+ def __init__(self, client: LastFmClient) -> None:
22
+ self._client = client
23
+
24
+ def _get_artists_page(
25
+ self,
26
+ user: str,
27
+ *,
28
+ period: str = "overall",
29
+ from_ts: int | str | date | datetime | None = None,
30
+ to_ts: int | str | date | datetime | None = None,
31
+ tz: str | tzinfo | None = None,
32
+ limit: int = 50,
33
+ page: int = 1,
34
+ ) -> ArtistListPage:
35
+ path = f"/user/{quote(user, safe='')}/library/artists"
36
+ params = library_filter_params(
37
+ period=period,
38
+ from_ts=from_ts,
39
+ to_ts=to_ts,
40
+ tz=tz,
41
+ page=page,
42
+ has_cookies=self._client.has_cookies,
43
+ method="library.get_artists",
44
+ )
45
+ resp = self._client.get(path, params=params or None)
46
+ res = parse_user_top_artists(resp.text, url=str(resp.url), user=user, page=page, limit=limit)
47
+ res.root_key = "artists"
48
+ return res
49
+
50
+ def get_artists(
51
+ self,
52
+ user: str,
53
+ *,
54
+ period: str = "overall",
55
+ from_ts: int | str | date | datetime | None = None,
56
+ to_ts: int | str | date | datetime | None = None,
57
+ tz: str | tzinfo | None = None,
58
+ limit: int = 50,
59
+ page: int = 1,
60
+ ) -> Any:
61
+ return self._client.format_result(
62
+ self._get_artists_page(
63
+ user, period=period, from_ts=from_ts, to_ts=to_ts, tz=tz, limit=limit, page=page
64
+ )
65
+ )
66
+
67
+ def iter_artists(
68
+ self,
69
+ user: str,
70
+ *,
71
+ period: str = "overall",
72
+ from_ts: int | str | date | datetime | None = None,
73
+ to_ts: int | str | date | datetime | None = None,
74
+ tz: str | tzinfo | None = None,
75
+ limit: int = 50,
76
+ start_page: int = 1,
77
+ max_pages: int | None = None,
78
+ ) -> Iterator[Any]:
79
+ return iter_paginated(
80
+ lambda p: self._get_artists_page(
81
+ user, period=period, from_ts=from_ts, to_ts=to_ts, tz=tz, limit=limit, page=p
82
+ ),
83
+ lambda r: r.artists,
84
+ start_page=start_page,
85
+ max_pages=max_pages,
86
+ raw_json=self._client.raw_json,
87
+ )
88
+
89
+ def get_artist_plays(
90
+ self,
91
+ user: str,
92
+ artist: str,
93
+ *,
94
+ period: str | None = None,
95
+ from_ts: int | str | date | datetime | None = None,
96
+ to_ts: int | str | date | datetime | None = None,
97
+ tz: str | tzinfo | None = None,
98
+ ) -> Any:
99
+ path = f"/user/{quote(user, safe='')}/library/music/{encode_music_part(artist)}"
100
+ params = library_filter_params(
101
+ period=period,
102
+ from_ts=from_ts,
103
+ to_ts=to_ts,
104
+ tz=tz,
105
+ has_cookies=self._client.has_cookies,
106
+ method="library.get_artist_plays",
107
+ )
108
+ resp = self._client.get(path, params=params or None)
109
+ return self._client.format_result(
110
+ parse_library_plays(resp.text, url=str(resp.url), user=user, artist=artist)
111
+ )
112
+
113
+ def get_album_plays(
114
+ self,
115
+ user: str,
116
+ artist: str,
117
+ album: str,
118
+ *,
119
+ period: str | None = None,
120
+ from_ts: int | str | date | datetime | None = None,
121
+ to_ts: int | str | date | datetime | None = None,
122
+ tz: str | tzinfo | None = None,
123
+ ) -> Any:
124
+ path = (
125
+ f"/user/{quote(user, safe='')}/library/music/"
126
+ f"{encode_music_part(artist)}/{encode_music_part(album)}"
127
+ )
128
+ params = library_filter_params(
129
+ period=period,
130
+ from_ts=from_ts,
131
+ to_ts=to_ts,
132
+ tz=tz,
133
+ has_cookies=self._client.has_cookies,
134
+ method="library.get_album_plays",
135
+ )
136
+ resp = self._client.get(path, params=params or None)
137
+ return self._client.format_result(
138
+ parse_library_plays(resp.text, url=str(resp.url), user=user, artist=artist, album=album)
139
+ )
140
+
141
+ def get_track_plays(
142
+ self,
143
+ user: str,
144
+ artist: str,
145
+ track: str,
146
+ *,
147
+ period: str | None = None,
148
+ from_ts: int | str | date | datetime | None = None,
149
+ to_ts: int | str | date | datetime | None = None,
150
+ tz: str | tzinfo | None = None,
151
+ ) -> Any:
152
+ path = (
153
+ f"/user/{quote(user, safe='')}/library/music/"
154
+ f"{encode_music_part(artist)}/_/{encode_music_part(track)}"
155
+ )
156
+ params = library_filter_params(
157
+ period=period,
158
+ from_ts=from_ts,
159
+ to_ts=to_ts,
160
+ tz=tz,
161
+ has_cookies=self._client.has_cookies,
162
+ method="library.get_track_plays",
163
+ )
164
+ resp = self._client.get(path, params=params or None)
165
+ return self._client.format_result(
166
+ parse_library_plays(resp.text, url=str(resp.url), user=user, artist=artist, track=track)
167
+ )
168
+
169
+
170
+ class AsyncLibraryAPI:
171
+ """Asynchronous `library.*` methods."""
172
+
173
+ def __init__(self, client: AsyncLastFmClient) -> None:
174
+ self._client = client
175
+
176
+ async def get_artists(
177
+ self,
178
+ user: str,
179
+ *,
180
+ period: str = "overall",
181
+ from_ts: int | str | None = None,
182
+ to_ts: int | str | None = None,
183
+ limit: int = 50,
184
+ page: int = 1,
185
+ ) -> Any:
186
+ path = f"/user/{quote(user, safe='')}/library/artists"
187
+ params = library_filter_params(
188
+ period=period,
189
+ from_ts=from_ts,
190
+ to_ts=to_ts,
191
+ page=page,
192
+ has_cookies=self._client.has_cookies,
193
+ method="library.get_artists",
194
+ )
195
+ resp = await self._client.get(path, params=params or None)
196
+ res = parse_user_top_artists(resp.text, url=str(resp.url), user=user, page=page, limit=limit)
197
+ res.root_key = "artists"
198
+ return self._client.format_result(res)
199
+
200
+ async def get_artist_plays(
201
+ self,
202
+ user: str,
203
+ artist: str,
204
+ *,
205
+ period: str | None = None,
206
+ from_ts: int | str | None = None,
207
+ to_ts: int | str | None = None,
208
+ ) -> Any:
209
+ path = f"/user/{quote(user, safe='')}/library/music/{encode_music_part(artist)}"
210
+ params = library_filter_params(
211
+ period=period,
212
+ from_ts=from_ts,
213
+ to_ts=to_ts,
214
+ has_cookies=self._client.has_cookies,
215
+ method="library.get_artist_plays",
216
+ )
217
+ resp = await self._client.get(path, params=params or None)
218
+ return self._client.format_result(
219
+ parse_library_plays(resp.text, url=str(resp.url), user=user, artist=artist)
220
+ )
221
+
222
+ async def get_album_plays(
223
+ self,
224
+ user: str,
225
+ artist: str,
226
+ album: str,
227
+ *,
228
+ period: str | None = None,
229
+ from_ts: int | str | None = None,
230
+ to_ts: int | str | None = None,
231
+ ) -> Any:
232
+ path = (
233
+ f"/user/{quote(user, safe='')}/library/music/"
234
+ f"{encode_music_part(artist)}/{encode_music_part(album)}"
235
+ )
236
+ params = library_filter_params(
237
+ period=period,
238
+ from_ts=from_ts,
239
+ to_ts=to_ts,
240
+ has_cookies=self._client.has_cookies,
241
+ method="library.get_album_plays",
242
+ )
243
+ resp = await self._client.get(path, params=params or None)
244
+ return self._client.format_result(
245
+ parse_library_plays(resp.text, url=str(resp.url), user=user, artist=artist, album=album)
246
+ )
247
+
248
+ async def get_track_plays(
249
+ self,
250
+ user: str,
251
+ artist: str,
252
+ track: str,
253
+ *,
254
+ period: str | None = None,
255
+ from_ts: int | str | None = None,
256
+ to_ts: int | str | None = None,
257
+ ) -> Any:
258
+ path = (
259
+ f"/user/{quote(user, safe='')}/library/music/"
260
+ f"{encode_music_part(artist)}/_/{encode_music_part(track)}"
261
+ )
262
+ params = library_filter_params(
263
+ period=period,
264
+ from_ts=from_ts,
265
+ to_ts=to_ts,
266
+ has_cookies=self._client.has_cookies,
267
+ method="library.get_track_plays",
268
+ )
269
+ resp = await self._client.get(path, params=params or None)
270
+ return self._client.format_result(
271
+ parse_library_plays(resp.text, url=str(resp.url), user=user, artist=artist, track=track)
272
+ )
fmscrape/api/tag.py ADDED
@@ -0,0 +1,174 @@
1
+ """Tag API endpoints (`tag.*`)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterator
6
+ from typing import TYPE_CHECKING, Any
7
+ from urllib.parse import quote
8
+
9
+ from bs4 import BeautifulSoup
10
+
11
+ from fmscrape.api.base import iter_paginated, lang_prefix
12
+ from fmscrape.errors import FmScrapeError, NotSupportedError
13
+ from fmscrape.models import AlbumListPage, ArtistListPage, TrackListPage
14
+ from fmscrape.parsers.common import parse_wiki
15
+ from fmscrape.parsers.tag import (
16
+ parse_tag_info,
17
+ parse_tag_similar,
18
+ parse_tag_top_albums,
19
+ parse_tag_top_artists,
20
+ parse_tag_top_tracks,
21
+ )
22
+
23
+ if TYPE_CHECKING:
24
+ from fmscrape.client import AsyncLastFmClient, LastFmClient
25
+
26
+
27
+ class _TagNotSupportedMixin:
28
+ def get_top_tags(self) -> Any:
29
+ raise NotSupportedError(
30
+ "tag.get_top_tags has no public global directory on last.fm (/music/+tags returns 404)."
31
+ )
32
+
33
+ def get_weekly_chart_list(self, tag: str) -> Any:
34
+ raise NotSupportedError("tag.get_weekly_chart_list has no public equivalent on last.fm.")
35
+
36
+
37
+ class TagAPI(_TagNotSupportedMixin):
38
+ """Synchronous `tag.*` methods."""
39
+
40
+ def __init__(self, client: LastFmClient) -> None:
41
+ self._client = client
42
+
43
+ def get_info(self, tag: str, *, lang: str | None = None, fetch_full_wiki: bool = True) -> Any:
44
+ prefix = lang_prefix(lang)
45
+ path = f"{prefix}/tag/{quote(tag, safe='')}"
46
+ resp = self._client.get(path)
47
+ info = parse_tag_info(resp.text, url=str(resp.url), tag=tag)
48
+ if fetch_full_wiki:
49
+ try:
50
+ w_resp = self._client.get(f"{path}/wiki")
51
+ full = parse_wiki(BeautifulSoup(w_resp.text, "lxml"), is_full_page=True)
52
+ if full.content:
53
+ info.wiki.content = full.content
54
+ if full.published:
55
+ info.wiki.published = full.published
56
+ except FmScrapeError:
57
+ pass
58
+ return self._client.format_result(info)
59
+
60
+ def get_similar(self, tag: str) -> Any:
61
+ resp = self._client.get(f"/tag/{quote(tag, safe='')}")
62
+ return self._client.format_result(parse_tag_similar(resp.text, url=str(resp.url)))
63
+
64
+ def _get_top_artists_page(self, tag: str, *, limit: int = 50, page: int = 1) -> ArtistListPage:
65
+ path = f"/tag/{quote(tag, safe='')}/artists"
66
+ params = {"page": page} if page > 1 else None
67
+ resp = self._client.get(path, params=params)
68
+ return parse_tag_top_artists(resp.text, url=str(resp.url), tag=tag, page=page, limit=limit)
69
+
70
+ def get_top_artists(self, tag: str, *, limit: int = 50, page: int = 1) -> Any:
71
+ return self._client.format_result(self._get_top_artists_page(tag, limit=limit, page=page))
72
+
73
+ def iter_top_artists(
74
+ self, tag: str, *, limit: int = 50, start_page: int = 1, max_pages: int | None = None
75
+ ) -> Iterator[Any]:
76
+ return iter_paginated(
77
+ lambda p: self._get_top_artists_page(tag, limit=limit, page=p),
78
+ lambda r: r.artists,
79
+ start_page=start_page,
80
+ max_pages=max_pages,
81
+ raw_json=self._client.raw_json,
82
+ )
83
+
84
+ def _get_top_albums_page(self, tag: str, *, limit: int = 50, page: int = 1) -> AlbumListPage:
85
+ path = f"/tag/{quote(tag, safe='')}/albums"
86
+ params = {"page": page} if page > 1 else None
87
+ resp = self._client.get(path, params=params)
88
+ return parse_tag_top_albums(resp.text, url=str(resp.url), tag=tag, page=page, limit=limit)
89
+
90
+ def get_top_albums(self, tag: str, *, limit: int = 50, page: int = 1) -> Any:
91
+ return self._client.format_result(self._get_top_albums_page(tag, limit=limit, page=page))
92
+
93
+ def iter_top_albums(
94
+ self, tag: str, *, limit: int = 50, start_page: int = 1, max_pages: int | None = None
95
+ ) -> Iterator[Any]:
96
+ return iter_paginated(
97
+ lambda p: self._get_top_albums_page(tag, limit=limit, page=p),
98
+ lambda r: r.albums,
99
+ start_page=start_page,
100
+ max_pages=max_pages,
101
+ raw_json=self._client.raw_json,
102
+ )
103
+
104
+ def _get_top_tracks_page(self, tag: str, *, limit: int = 50, page: int = 1) -> TrackListPage:
105
+ path = f"/tag/{quote(tag, safe='')}/tracks"
106
+ params = {"page": page} if page > 1 else None
107
+ resp = self._client.get(path, params=params)
108
+ return parse_tag_top_tracks(resp.text, url=str(resp.url), tag=tag, page=page, limit=limit)
109
+
110
+ def get_top_tracks(self, tag: str, *, limit: int = 50, page: int = 1) -> Any:
111
+ return self._client.format_result(self._get_top_tracks_page(tag, limit=limit, page=page))
112
+
113
+ def iter_top_tracks(
114
+ self, tag: str, *, limit: int = 50, start_page: int = 1, max_pages: int | None = None
115
+ ) -> Iterator[Any]:
116
+ return iter_paginated(
117
+ lambda p: self._get_top_tracks_page(tag, limit=limit, page=p),
118
+ lambda r: r.tracks,
119
+ start_page=start_page,
120
+ max_pages=max_pages,
121
+ raw_json=self._client.raw_json,
122
+ )
123
+
124
+
125
+ class AsyncTagAPI(_TagNotSupportedMixin):
126
+ """Asynchronous `tag.*` methods."""
127
+
128
+ def __init__(self, client: AsyncLastFmClient) -> None:
129
+ self._client = client
130
+
131
+ async def get_info(self, tag: str, *, lang: str | None = None, fetch_full_wiki: bool = True) -> Any:
132
+ prefix = lang_prefix(lang)
133
+ path = f"{prefix}/tag/{quote(tag, safe='')}"
134
+ resp = await self._client.get(path)
135
+ info = parse_tag_info(resp.text, url=str(resp.url), tag=tag)
136
+ if fetch_full_wiki:
137
+ try:
138
+ w_resp = await self._client.get(f"{path}/wiki")
139
+ full = parse_wiki(BeautifulSoup(w_resp.text, "lxml"), is_full_page=True)
140
+ if full.content:
141
+ info.wiki.content = full.content
142
+ if full.published:
143
+ info.wiki.published = full.published
144
+ except FmScrapeError:
145
+ pass
146
+ return self._client.format_result(info)
147
+
148
+ async def get_similar(self, tag: str) -> Any:
149
+ resp = await self._client.get(f"/tag/{quote(tag, safe='')}")
150
+ return self._client.format_result(parse_tag_similar(resp.text, url=str(resp.url)))
151
+
152
+ async def get_top_artists(self, tag: str, *, limit: int = 50, page: int = 1) -> Any:
153
+ path = f"/tag/{quote(tag, safe='')}/artists"
154
+ params = {"page": page} if page > 1 else None
155
+ resp = await self._client.get(path, params=params)
156
+ return self._client.format_result(
157
+ parse_tag_top_artists(resp.text, url=str(resp.url), tag=tag, page=page, limit=limit)
158
+ )
159
+
160
+ async def get_top_albums(self, tag: str, *, limit: int = 50, page: int = 1) -> Any:
161
+ path = f"/tag/{quote(tag, safe='')}/albums"
162
+ params = {"page": page} if page > 1 else None
163
+ resp = await self._client.get(path, params=params)
164
+ return self._client.format_result(
165
+ parse_tag_top_albums(resp.text, url=str(resp.url), tag=tag, page=page, limit=limit)
166
+ )
167
+
168
+ async def get_top_tracks(self, tag: str, *, limit: int = 50, page: int = 1) -> Any:
169
+ path = f"/tag/{quote(tag, safe='')}/tracks"
170
+ params = {"page": page} if page > 1 else None
171
+ resp = await self._client.get(path, params=params)
172
+ return self._client.format_result(
173
+ parse_tag_top_tracks(resp.text, url=str(resp.url), tag=tag, page=page, limit=limit)
174
+ )
fmscrape/api/track.py ADDED
@@ -0,0 +1,144 @@
1
+ """Track API endpoints (`track.*`)."""
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.models import CorrectionResult
10
+ from fmscrape.parsers.track import (
11
+ parse_track_info,
12
+ parse_track_search,
13
+ parse_track_similar,
14
+ parse_track_top_tags,
15
+ )
16
+
17
+ if TYPE_CHECKING:
18
+ from fmscrape.client import AsyncLastFmClient, LastFmClient
19
+
20
+
21
+ class _TrackWriteNotSupported:
22
+ def scrobble(self, *args: Any, **kwargs: Any) -> Any:
23
+ raise NotSupportedError("track.scrobble requires Last.fm authentication.")
24
+
25
+ def love(self, artist: str, track: str) -> Any:
26
+ raise NotSupportedError("track.love requires Last.fm authentication.")
27
+
28
+ def unlove(self, artist: str, track: str) -> Any:
29
+ raise NotSupportedError("track.unlove requires Last.fm authentication.")
30
+
31
+ def update_now_playing(self, *args: Any, **kwargs: Any) -> Any:
32
+ raise NotSupportedError("track.update_now_playing requires Last.fm authentication.")
33
+
34
+ def add_tags(self, artist: str, track: str, tags: list[str] | str) -> Any:
35
+ raise NotSupportedError("track.add_tags requires Last.fm authentication.")
36
+
37
+ def remove_tag(self, artist: str, track: str, tag: str) -> Any:
38
+ raise NotSupportedError("track.remove_tag requires Last.fm authentication.")
39
+
40
+
41
+ class TrackAPI(_TrackWriteNotSupported):
42
+ """Synchronous `track.*` methods."""
43
+
44
+ def __init__(self, client: LastFmClient) -> None:
45
+ self._client = client
46
+
47
+ def get_info(
48
+ self, artist: str, track: str, *, autocorrect: int = 1, lang: str | None = None
49
+ ) -> Any:
50
+ path = build_music_path(artist, "_", track, autocorrect=autocorrect, lang=lang)
51
+ resp = self._client.get(path)
52
+ return self._client.format_result(parse_track_info(resp.text, url=str(resp.url)))
53
+
54
+ def get_similar(
55
+ self, artist: str, track: str, *, limit: int = 50, autocorrect: int = 1
56
+ ) -> Any:
57
+ path = build_music_path(artist, "_", track, autocorrect=autocorrect)
58
+ resp = self._client.get(path)
59
+ return self._client.format_result(
60
+ parse_track_similar(resp.text, url=str(resp.url), artist=artist, limit=limit)
61
+ )
62
+
63
+ def get_top_tags(self, artist: str, track: str, *, autocorrect: int = 1) -> Any:
64
+ path = build_music_path(artist, "_", track, autocorrect=autocorrect, suffix="/+tags")
65
+ resp = self._client.get(path)
66
+ return self._client.format_result(parse_track_top_tags(resp.text, url=str(resp.url)))
67
+
68
+ def get_correction(self, artist: str, track: str) -> Any:
69
+ path = build_music_path(artist, "_", track, autocorrect=1)
70
+ resp = self._client.get(path)
71
+ info = parse_track_info(resp.text, url=str(resp.url))
72
+ return self._client.format_result(
73
+ CorrectionResult(
74
+ name=info.name,
75
+ url=info.url,
76
+ artist_name=info.artist.name,
77
+ artist_url=info.artist.url,
78
+ )
79
+ )
80
+
81
+ def search(
82
+ self, track: str, *, artist: str | None = None, limit: int = 30, page: int = 1
83
+ ) -> Any:
84
+ query = f"{artist} {track}".strip() if artist else track
85
+ params: dict[str, Any] = {"q": query}
86
+ if page > 1:
87
+ params["page"] = page
88
+ resp = self._client.get("/search/tracks", params=params)
89
+ return self._client.format_result(
90
+ parse_track_search(resp.text, url=str(resp.url), page=page, limit=limit)
91
+ )
92
+
93
+
94
+ class AsyncTrackAPI(_TrackWriteNotSupported):
95
+ """Asynchronous `track.*` methods."""
96
+
97
+ def __init__(self, client: AsyncLastFmClient) -> None:
98
+ self._client = client
99
+
100
+ async def get_info(
101
+ self, artist: str, track: str, *, autocorrect: int = 1, lang: str | None = None
102
+ ) -> Any:
103
+ path = build_music_path(artist, "_", track, autocorrect=autocorrect, lang=lang)
104
+ resp = await self._client.get(path)
105
+ return self._client.format_result(parse_track_info(resp.text, url=str(resp.url)))
106
+
107
+ async def get_similar(
108
+ self, artist: str, track: str, *, limit: int = 50, autocorrect: int = 1
109
+ ) -> Any:
110
+ path = build_music_path(artist, "_", track, autocorrect=autocorrect)
111
+ resp = await self._client.get(path)
112
+ return self._client.format_result(
113
+ parse_track_similar(resp.text, url=str(resp.url), artist=artist, limit=limit)
114
+ )
115
+
116
+ async def get_top_tags(self, artist: str, track: str, *, autocorrect: int = 1) -> Any:
117
+ path = build_music_path(artist, "_", track, autocorrect=autocorrect, suffix="/+tags")
118
+ resp = await self._client.get(path)
119
+ return self._client.format_result(parse_track_top_tags(resp.text, url=str(resp.url)))
120
+
121
+ async def get_correction(self, artist: str, track: str) -> Any:
122
+ path = build_music_path(artist, "_", track, autocorrect=1)
123
+ resp = await self._client.get(path)
124
+ info = parse_track_info(resp.text, url=str(resp.url))
125
+ return self._client.format_result(
126
+ CorrectionResult(
127
+ name=info.name,
128
+ url=info.url,
129
+ artist_name=info.artist.name,
130
+ artist_url=info.artist.url,
131
+ )
132
+ )
133
+
134
+ async def search(
135
+ self, track: str, *, artist: str | None = None, limit: int = 30, page: int = 1
136
+ ) -> Any:
137
+ query = f"{artist} {track}".strip() if artist else track
138
+ params: dict[str, Any] = {"q": query}
139
+ if page > 1:
140
+ params["page"] = page
141
+ resp = await self._client.get("/search/tracks", params=params)
142
+ return self._client.format_result(
143
+ parse_track_search(resp.text, url=str(resp.url), page=page, limit=limit)
144
+ )