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/models.py
ADDED
|
@@ -0,0 +1,594 @@
|
|
|
1
|
+
"""Typed dataclasses mirroring Last.fm API v2 JSON structures."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclass(slots=True)
|
|
10
|
+
class Image:
|
|
11
|
+
"""Last.fm image entry with size and URL."""
|
|
12
|
+
|
|
13
|
+
url: str
|
|
14
|
+
size: str
|
|
15
|
+
|
|
16
|
+
def to_dict(self) -> dict[str, str]:
|
|
17
|
+
return {"#text": self.url, "size": self.size}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(slots=True)
|
|
21
|
+
class DateInfo:
|
|
22
|
+
"""Scrobble timestamp in UTC."""
|
|
23
|
+
|
|
24
|
+
uts: int
|
|
25
|
+
text: str
|
|
26
|
+
|
|
27
|
+
def to_dict(self) -> dict[str, str]:
|
|
28
|
+
return {"uts": str(self.uts), "#text": self.text}
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(slots=True)
|
|
32
|
+
class ArtistRef:
|
|
33
|
+
"""Compact artist reference embedded inside track/album responses."""
|
|
34
|
+
|
|
35
|
+
name: str
|
|
36
|
+
url: str = ""
|
|
37
|
+
mbid: str = ""
|
|
38
|
+
|
|
39
|
+
def to_dict(self) -> dict[str, str]:
|
|
40
|
+
data: dict[str, str] = {"mbid": self.mbid, "#text": self.name}
|
|
41
|
+
if self.url:
|
|
42
|
+
data["url"] = self.url
|
|
43
|
+
return data
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass(slots=True)
|
|
47
|
+
class AlbumRef:
|
|
48
|
+
"""Compact album reference embedded inside track responses."""
|
|
49
|
+
|
|
50
|
+
name: str
|
|
51
|
+
url: str = ""
|
|
52
|
+
mbid: str = ""
|
|
53
|
+
|
|
54
|
+
def to_dict(self) -> dict[str, str]:
|
|
55
|
+
data: dict[str, str] = {"mbid": self.mbid, "#text": self.name}
|
|
56
|
+
if self.url:
|
|
57
|
+
data["url"] = self.url
|
|
58
|
+
return data
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass(slots=True)
|
|
62
|
+
class PaginationAttr:
|
|
63
|
+
"""Pagination metadata matching Last.fm's `@attr` block."""
|
|
64
|
+
|
|
65
|
+
page: int
|
|
66
|
+
per_page: int
|
|
67
|
+
total_pages: int
|
|
68
|
+
total: int
|
|
69
|
+
user: str | None = None
|
|
70
|
+
tag: str | None = None
|
|
71
|
+
artist: str | None = None
|
|
72
|
+
|
|
73
|
+
def to_dict(self) -> dict[str, str]:
|
|
74
|
+
data: dict[str, str] = {
|
|
75
|
+
"page": str(self.page),
|
|
76
|
+
"perPage": str(self.per_page),
|
|
77
|
+
"totalPages": str(self.total_pages),
|
|
78
|
+
"total": str(self.total),
|
|
79
|
+
}
|
|
80
|
+
if self.user is not None:
|
|
81
|
+
data["user"] = self.user
|
|
82
|
+
if self.tag is not None:
|
|
83
|
+
data["tag"] = self.tag
|
|
84
|
+
if self.artist is not None:
|
|
85
|
+
data["artist"] = self.artist
|
|
86
|
+
return data
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
@dataclass(slots=True)
|
|
90
|
+
class TagInfo:
|
|
91
|
+
"""Tag entry with name, URL, and optional count."""
|
|
92
|
+
|
|
93
|
+
name: str
|
|
94
|
+
url: str = ""
|
|
95
|
+
count: int | None = None
|
|
96
|
+
|
|
97
|
+
def to_dict(self) -> dict[str, Any]:
|
|
98
|
+
data: dict[str, Any] = {"name": self.name, "url": self.url}
|
|
99
|
+
if self.count is not None:
|
|
100
|
+
data["count"] = self.count
|
|
101
|
+
return data
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
@dataclass(slots=True)
|
|
105
|
+
class WikiInfo:
|
|
106
|
+
"""Wiki / biography block."""
|
|
107
|
+
|
|
108
|
+
summary: str = ""
|
|
109
|
+
content: str = ""
|
|
110
|
+
published: str = ""
|
|
111
|
+
|
|
112
|
+
def to_dict(self) -> dict[str, str]:
|
|
113
|
+
return {
|
|
114
|
+
"published": self.published,
|
|
115
|
+
"summary": self.summary,
|
|
116
|
+
"content": self.content,
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
@dataclass(slots=True)
|
|
121
|
+
class StatsInfo:
|
|
122
|
+
"""Listeners and playcount statistics."""
|
|
123
|
+
|
|
124
|
+
listeners: int = 0
|
|
125
|
+
playcount: int = 0
|
|
126
|
+
|
|
127
|
+
def to_dict(self) -> dict[str, str]:
|
|
128
|
+
return {
|
|
129
|
+
"listeners": str(self.listeners),
|
|
130
|
+
"playcount": str(self.playcount),
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
@dataclass(slots=True)
|
|
135
|
+
class RecentTrack:
|
|
136
|
+
"""A track entry returned by `user.get_recent_tracks`."""
|
|
137
|
+
|
|
138
|
+
name: str
|
|
139
|
+
artist: ArtistRef
|
|
140
|
+
album: AlbumRef
|
|
141
|
+
url: str
|
|
142
|
+
images: list[Image] = field(default_factory=list)
|
|
143
|
+
date: DateInfo | None = None
|
|
144
|
+
loved: bool = False
|
|
145
|
+
now_playing: bool = False
|
|
146
|
+
mbid: str = ""
|
|
147
|
+
|
|
148
|
+
def to_dict(self) -> dict[str, Any]:
|
|
149
|
+
data: dict[str, Any] = {
|
|
150
|
+
"artist": self.artist.to_dict(),
|
|
151
|
+
"mbid": self.mbid,
|
|
152
|
+
"name": self.name,
|
|
153
|
+
"album": self.album.to_dict(),
|
|
154
|
+
"url": self.url,
|
|
155
|
+
"image": [img.to_dict() for img in self.images],
|
|
156
|
+
"loved": "1" if self.loved else "0",
|
|
157
|
+
}
|
|
158
|
+
if self.now_playing:
|
|
159
|
+
data["@attr"] = {"nowplaying": "true"}
|
|
160
|
+
elif self.date is not None:
|
|
161
|
+
data["date"] = self.date.to_dict()
|
|
162
|
+
return data
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
@dataclass(slots=True)
|
|
166
|
+
class RecentTracksPage:
|
|
167
|
+
"""Paginated result for `user.get_recent_tracks`."""
|
|
168
|
+
|
|
169
|
+
tracks: list[RecentTrack]
|
|
170
|
+
attr: PaginationAttr
|
|
171
|
+
|
|
172
|
+
def to_dict(self) -> dict[str, Any]:
|
|
173
|
+
return {
|
|
174
|
+
"recenttracks": {
|
|
175
|
+
"track": [t.to_dict() for t in self.tracks],
|
|
176
|
+
"@attr": self.attr.to_dict(),
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
@dataclass(slots=True)
|
|
182
|
+
class ArtistEntry:
|
|
183
|
+
"""Compact artist item used in top artists, similar artists, search, and charts."""
|
|
184
|
+
|
|
185
|
+
name: str
|
|
186
|
+
url: str = ""
|
|
187
|
+
images: list[Image] = field(default_factory=list)
|
|
188
|
+
playcount: int | None = None
|
|
189
|
+
listeners: int | None = None
|
|
190
|
+
rank: int | None = None
|
|
191
|
+
mbid: str = ""
|
|
192
|
+
|
|
193
|
+
def to_dict(self) -> dict[str, Any]:
|
|
194
|
+
data: dict[str, Any] = {
|
|
195
|
+
"name": self.name,
|
|
196
|
+
"mbid": self.mbid,
|
|
197
|
+
"url": self.url,
|
|
198
|
+
"image": [img.to_dict() for img in self.images],
|
|
199
|
+
}
|
|
200
|
+
if self.playcount is not None:
|
|
201
|
+
data["playcount"] = str(self.playcount)
|
|
202
|
+
if self.listeners is not None:
|
|
203
|
+
data["listeners"] = str(self.listeners)
|
|
204
|
+
if self.rank is not None:
|
|
205
|
+
data["@attr"] = {"rank": str(self.rank)}
|
|
206
|
+
return data
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
@dataclass(slots=True)
|
|
210
|
+
class ArtistInfo:
|
|
211
|
+
"""Detailed artist info returned by `artist.get_info`."""
|
|
212
|
+
|
|
213
|
+
name: str
|
|
214
|
+
url: str
|
|
215
|
+
images: list[Image] = field(default_factory=list)
|
|
216
|
+
stats: StatsInfo = field(default_factory=StatsInfo)
|
|
217
|
+
similar: list[ArtistEntry] = field(default_factory=list)
|
|
218
|
+
tags: list[TagInfo] = field(default_factory=list)
|
|
219
|
+
bio: WikiInfo = field(default_factory=WikiInfo)
|
|
220
|
+
mbid: str = ""
|
|
221
|
+
|
|
222
|
+
def to_dict(self) -> dict[str, Any]:
|
|
223
|
+
return {
|
|
224
|
+
"artist": {
|
|
225
|
+
"name": self.name,
|
|
226
|
+
"mbid": self.mbid,
|
|
227
|
+
"url": self.url,
|
|
228
|
+
"image": [img.to_dict() for img in self.images],
|
|
229
|
+
"stats": self.stats.to_dict(),
|
|
230
|
+
"similar": {"artist": [s.to_dict() for s in self.similar]},
|
|
231
|
+
"tags": {"tag": [t.to_dict() for t in self.tags]},
|
|
232
|
+
"bio": self.bio.to_dict(),
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
@dataclass(slots=True)
|
|
238
|
+
class AlbumEntry:
|
|
239
|
+
"""Compact album item used in top albums, tag albums, and search."""
|
|
240
|
+
|
|
241
|
+
name: str
|
|
242
|
+
artist: ArtistRef
|
|
243
|
+
url: str = ""
|
|
244
|
+
images: list[Image] = field(default_factory=list)
|
|
245
|
+
playcount: int | None = None
|
|
246
|
+
listeners: int | None = None
|
|
247
|
+
rank: int | None = None
|
|
248
|
+
mbid: str = ""
|
|
249
|
+
|
|
250
|
+
def to_dict(self) -> dict[str, Any]:
|
|
251
|
+
data: dict[str, Any] = {
|
|
252
|
+
"name": self.name,
|
|
253
|
+
"mbid": self.mbid,
|
|
254
|
+
"url": self.url,
|
|
255
|
+
"artist": {"name": self.artist.name, "mbid": self.artist.mbid, "url": self.artist.url},
|
|
256
|
+
"image": [img.to_dict() for img in self.images],
|
|
257
|
+
}
|
|
258
|
+
if self.playcount is not None:
|
|
259
|
+
data["playcount"] = str(self.playcount)
|
|
260
|
+
if self.listeners is not None:
|
|
261
|
+
data["listeners"] = str(self.listeners)
|
|
262
|
+
if self.rank is not None:
|
|
263
|
+
data["@attr"] = {"rank": str(self.rank)}
|
|
264
|
+
return data
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
@dataclass(slots=True)
|
|
268
|
+
class TrackEntry:
|
|
269
|
+
"""Compact track item used in top tracks, similar tracks, search, album tracklists, and charts."""
|
|
270
|
+
|
|
271
|
+
name: str
|
|
272
|
+
artist: ArtistRef
|
|
273
|
+
url: str = ""
|
|
274
|
+
images: list[Image] = field(default_factory=list)
|
|
275
|
+
duration: int | None = None
|
|
276
|
+
playcount: int | None = None
|
|
277
|
+
listeners: int | None = None
|
|
278
|
+
rank: int | None = None
|
|
279
|
+
mbid: str = ""
|
|
280
|
+
|
|
281
|
+
def to_dict(self) -> dict[str, Any]:
|
|
282
|
+
data: dict[str, Any] = {
|
|
283
|
+
"name": self.name,
|
|
284
|
+
"mbid": self.mbid,
|
|
285
|
+
"url": self.url,
|
|
286
|
+
"artist": {"name": self.artist.name, "mbid": self.artist.mbid, "url": self.artist.url},
|
|
287
|
+
"image": [img.to_dict() for img in self.images],
|
|
288
|
+
}
|
|
289
|
+
if self.duration is not None:
|
|
290
|
+
data["duration"] = str(self.duration)
|
|
291
|
+
if self.playcount is not None:
|
|
292
|
+
data["playcount"] = str(self.playcount)
|
|
293
|
+
if self.listeners is not None:
|
|
294
|
+
data["listeners"] = str(self.listeners)
|
|
295
|
+
if self.rank is not None:
|
|
296
|
+
data["@attr"] = {"rank": str(self.rank)}
|
|
297
|
+
return data
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
@dataclass(slots=True)
|
|
301
|
+
class AlbumInfo:
|
|
302
|
+
"""Detailed album info returned by `album.get_info`."""
|
|
303
|
+
|
|
304
|
+
name: str
|
|
305
|
+
artist: str
|
|
306
|
+
url: str
|
|
307
|
+
images: list[Image] = field(default_factory=list)
|
|
308
|
+
listeners: int = 0
|
|
309
|
+
playcount: int = 0
|
|
310
|
+
tracks: list[TrackEntry] = field(default_factory=list)
|
|
311
|
+
tags: list[TagInfo] = field(default_factory=list)
|
|
312
|
+
wiki: WikiInfo = field(default_factory=WikiInfo)
|
|
313
|
+
release_date: str = ""
|
|
314
|
+
mbid: str = ""
|
|
315
|
+
|
|
316
|
+
def to_dict(self) -> dict[str, Any]:
|
|
317
|
+
return {
|
|
318
|
+
"album": {
|
|
319
|
+
"name": self.name,
|
|
320
|
+
"artist": self.artist,
|
|
321
|
+
"mbid": self.mbid,
|
|
322
|
+
"url": self.url,
|
|
323
|
+
"image": [img.to_dict() for img in self.images],
|
|
324
|
+
"listeners": str(self.listeners),
|
|
325
|
+
"playcount": str(self.playcount),
|
|
326
|
+
"tracks": {"track": [t.to_dict() for t in self.tracks]},
|
|
327
|
+
"tags": {"tag": [t.to_dict() for t in self.tags]},
|
|
328
|
+
"wiki": self.wiki.to_dict(),
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
@dataclass(slots=True)
|
|
334
|
+
class TrackInfo:
|
|
335
|
+
"""Detailed track info returned by `track.get_info`."""
|
|
336
|
+
|
|
337
|
+
name: str
|
|
338
|
+
artist: ArtistRef
|
|
339
|
+
url: str
|
|
340
|
+
duration: int = 0
|
|
341
|
+
listeners: int = 0
|
|
342
|
+
playcount: int = 0
|
|
343
|
+
album: AlbumRef | None = None
|
|
344
|
+
toptags: list[TagInfo] = field(default_factory=list)
|
|
345
|
+
wiki: WikiInfo = field(default_factory=WikiInfo)
|
|
346
|
+
mbid: str = ""
|
|
347
|
+
|
|
348
|
+
def to_dict(self) -> dict[str, Any]:
|
|
349
|
+
data: dict[str, Any] = {
|
|
350
|
+
"name": self.name,
|
|
351
|
+
"mbid": self.mbid,
|
|
352
|
+
"url": self.url,
|
|
353
|
+
"duration": str(self.duration),
|
|
354
|
+
"listeners": str(self.listeners),
|
|
355
|
+
"playcount": str(self.playcount),
|
|
356
|
+
"artist": {"name": self.artist.name, "mbid": self.artist.mbid, "url": self.artist.url},
|
|
357
|
+
"toptags": {"tag": [t.to_dict() for t in self.toptags]},
|
|
358
|
+
"wiki": self.wiki.to_dict(),
|
|
359
|
+
}
|
|
360
|
+
if self.album is not None:
|
|
361
|
+
data["album"] = {
|
|
362
|
+
"artist": self.artist.name,
|
|
363
|
+
"title": self.album.name,
|
|
364
|
+
"mbid": self.album.mbid,
|
|
365
|
+
"url": self.album.url,
|
|
366
|
+
}
|
|
367
|
+
return {"track": data}
|
|
368
|
+
|
|
369
|
+
|
|
370
|
+
@dataclass(slots=True)
|
|
371
|
+
class UserEntry:
|
|
372
|
+
"""User entry returned by `user.get_friends`."""
|
|
373
|
+
|
|
374
|
+
name: str
|
|
375
|
+
url: str
|
|
376
|
+
images: list[Image] = field(default_factory=list)
|
|
377
|
+
realname: str = ""
|
|
378
|
+
|
|
379
|
+
def to_dict(self) -> dict[str, Any]:
|
|
380
|
+
return {
|
|
381
|
+
"name": self.name,
|
|
382
|
+
"realname": self.realname,
|
|
383
|
+
"url": self.url,
|
|
384
|
+
"image": [img.to_dict() for img in self.images],
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
|
|
388
|
+
@dataclass(slots=True)
|
|
389
|
+
class UserInfo:
|
|
390
|
+
"""Detailed user profile returned by `user.get_info`."""
|
|
391
|
+
|
|
392
|
+
name: str
|
|
393
|
+
url: str
|
|
394
|
+
realname: str = ""
|
|
395
|
+
images: list[Image] = field(default_factory=list)
|
|
396
|
+
playcount: int = 0
|
|
397
|
+
artist_count: int = 0
|
|
398
|
+
registered: str = ""
|
|
399
|
+
|
|
400
|
+
def to_dict(self) -> dict[str, Any]:
|
|
401
|
+
return {
|
|
402
|
+
"user": {
|
|
403
|
+
"name": self.name,
|
|
404
|
+
"realname": self.realname,
|
|
405
|
+
"url": self.url,
|
|
406
|
+
"image": [img.to_dict() for img in self.images],
|
|
407
|
+
"playcount": str(self.playcount),
|
|
408
|
+
"artist_count": str(self.artist_count),
|
|
409
|
+
"registered": {"#text": self.registered},
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
|
|
414
|
+
@dataclass(slots=True)
|
|
415
|
+
class TagDetails:
|
|
416
|
+
"""Tag info returned by `tag.get_info`."""
|
|
417
|
+
|
|
418
|
+
name: str
|
|
419
|
+
url: str
|
|
420
|
+
wiki: WikiInfo = field(default_factory=WikiInfo)
|
|
421
|
+
|
|
422
|
+
def to_dict(self) -> dict[str, Any]:
|
|
423
|
+
return {
|
|
424
|
+
"tag": {
|
|
425
|
+
"name": self.name,
|
|
426
|
+
"url": self.url,
|
|
427
|
+
"wiki": self.wiki.to_dict(),
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
|
|
432
|
+
@dataclass(slots=True)
|
|
433
|
+
class CorrectionResult:
|
|
434
|
+
"""Canonical correction result for `artist.get_correction` or `track.get_correction`."""
|
|
435
|
+
|
|
436
|
+
name: str
|
|
437
|
+
url: str
|
|
438
|
+
artist_name: str | None = None
|
|
439
|
+
artist_url: str | None = None
|
|
440
|
+
|
|
441
|
+
def to_dict(self) -> dict[str, Any]:
|
|
442
|
+
if self.artist_name is not None:
|
|
443
|
+
return {
|
|
444
|
+
"corrections": {
|
|
445
|
+
"correction": {
|
|
446
|
+
"track": {
|
|
447
|
+
"name": self.name,
|
|
448
|
+
"url": self.url,
|
|
449
|
+
"artist": {
|
|
450
|
+
"name": self.artist_name,
|
|
451
|
+
"url": self.artist_url or "",
|
|
452
|
+
},
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
}
|
|
457
|
+
return {
|
|
458
|
+
"corrections": {
|
|
459
|
+
"correction": {
|
|
460
|
+
"artist": {
|
|
461
|
+
"name": self.name,
|
|
462
|
+
"url": self.url,
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
|
|
469
|
+
@dataclass(slots=True)
|
|
470
|
+
class ArtistListPage:
|
|
471
|
+
"""Paginated artist list (topartists / artists / similarartists)."""
|
|
472
|
+
|
|
473
|
+
artists: list[ArtistEntry]
|
|
474
|
+
attr: PaginationAttr
|
|
475
|
+
root_key: str = "topartists"
|
|
476
|
+
|
|
477
|
+
def to_dict(self) -> dict[str, Any]:
|
|
478
|
+
return {
|
|
479
|
+
self.root_key: {
|
|
480
|
+
"artist": [a.to_dict() for a in self.artists],
|
|
481
|
+
"@attr": self.attr.to_dict(),
|
|
482
|
+
}
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
|
|
486
|
+
@dataclass(slots=True)
|
|
487
|
+
class AlbumListPage:
|
|
488
|
+
"""Paginated album list (topalbums / albums)."""
|
|
489
|
+
|
|
490
|
+
albums: list[AlbumEntry]
|
|
491
|
+
attr: PaginationAttr
|
|
492
|
+
root_key: str = "topalbums"
|
|
493
|
+
|
|
494
|
+
def to_dict(self) -> dict[str, Any]:
|
|
495
|
+
return {
|
|
496
|
+
self.root_key: {
|
|
497
|
+
"album": [a.to_dict() for a in self.albums],
|
|
498
|
+
"@attr": self.attr.to_dict(),
|
|
499
|
+
}
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
|
|
503
|
+
@dataclass(slots=True)
|
|
504
|
+
class TrackListPage:
|
|
505
|
+
"""Paginated track list (toptracks / tracks / similartracks)."""
|
|
506
|
+
|
|
507
|
+
tracks: list[TrackEntry]
|
|
508
|
+
attr: PaginationAttr
|
|
509
|
+
root_key: str = "toptracks"
|
|
510
|
+
|
|
511
|
+
def to_dict(self) -> dict[str, Any]:
|
|
512
|
+
return {
|
|
513
|
+
self.root_key: {
|
|
514
|
+
"track": [t.to_dict() for t in self.tracks],
|
|
515
|
+
"@attr": self.attr.to_dict(),
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
|
|
520
|
+
@dataclass(slots=True)
|
|
521
|
+
class FriendsPage:
|
|
522
|
+
"""Paginated user friends list."""
|
|
523
|
+
|
|
524
|
+
friends: list[UserEntry]
|
|
525
|
+
attr: PaginationAttr
|
|
526
|
+
|
|
527
|
+
def to_dict(self) -> dict[str, Any]:
|
|
528
|
+
return {
|
|
529
|
+
"friends": {
|
|
530
|
+
"user": [u.to_dict() for u in self.friends],
|
|
531
|
+
"@attr": self.attr.to_dict(),
|
|
532
|
+
}
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
@dataclass(slots=True)
|
|
537
|
+
class TagsListResult:
|
|
538
|
+
"""List of tags returned by `*.get_top_tags` or `tag.get_similar`."""
|
|
539
|
+
|
|
540
|
+
tags: list[TagInfo]
|
|
541
|
+
root_key: str = "toptags"
|
|
542
|
+
|
|
543
|
+
def to_dict(self) -> dict[str, Any]:
|
|
544
|
+
return {self.root_key: {"tag": [t.to_dict() for t in self.tags]}}
|
|
545
|
+
|
|
546
|
+
|
|
547
|
+
@dataclass(slots=True)
|
|
548
|
+
class LibraryPlays:
|
|
549
|
+
"""User library playcount for a specific artist, album, or track."""
|
|
550
|
+
|
|
551
|
+
user: str
|
|
552
|
+
artist: str
|
|
553
|
+
playcount: int
|
|
554
|
+
url: str
|
|
555
|
+
album: str | None = None
|
|
556
|
+
track: str | None = None
|
|
557
|
+
tracks: list[TrackEntry] = field(default_factory=list)
|
|
558
|
+
|
|
559
|
+
def to_dict(self) -> dict[str, Any]:
|
|
560
|
+
data: dict[str, Any] = {
|
|
561
|
+
"user": self.user,
|
|
562
|
+
"artist": self.artist,
|
|
563
|
+
"playcount": str(self.playcount),
|
|
564
|
+
"url": self.url,
|
|
565
|
+
}
|
|
566
|
+
if self.album is not None:
|
|
567
|
+
data["album"] = self.album
|
|
568
|
+
if self.track is not None:
|
|
569
|
+
data["track"] = self.track
|
|
570
|
+
if self.tracks:
|
|
571
|
+
data["tracks"] = {"track": [t.to_dict() for t in self.tracks]}
|
|
572
|
+
return {"library": data}
|
|
573
|
+
|
|
574
|
+
|
|
575
|
+
@dataclass(slots=True)
|
|
576
|
+
class SearchResultsPage:
|
|
577
|
+
"""Search results wrapper matching Last.fm's `results` structure."""
|
|
578
|
+
|
|
579
|
+
items: list[ArtistEntry] | list[AlbumEntry] | list[TrackEntry]
|
|
580
|
+
attr: PaginationAttr
|
|
581
|
+
match_key: str # "artistmatches" | "albummatches" | "trackmatches"
|
|
582
|
+
item_key: str # "artist" | "album" | "track"
|
|
583
|
+
|
|
584
|
+
def to_dict(self) -> dict[str, Any]:
|
|
585
|
+
return {
|
|
586
|
+
"results": {
|
|
587
|
+
"opensearch:totalResults": str(self.attr.total),
|
|
588
|
+
"opensearch:startIndex": str((self.attr.page - 1) * self.attr.per_page),
|
|
589
|
+
"opensearch:itemsPerPage": str(self.attr.per_page),
|
|
590
|
+
self.match_key: {
|
|
591
|
+
self.item_key: [item.to_dict() for item in self.items],
|
|
592
|
+
},
|
|
593
|
+
}
|
|
594
|
+
}
|
fmscrape/normalize.py
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
"""Normalization helpers for numbers, UTC timestamps, URLs, and Last.fm images."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from datetime import datetime, timezone
|
|
7
|
+
from urllib.parse import urljoin
|
|
8
|
+
|
|
9
|
+
BASE_URL = "https://www.last.fm"
|
|
10
|
+
|
|
11
|
+
_IMAGE_SIZE_RE = re.compile(
|
|
12
|
+
r"^(https?://[^/]+/i/u/)([^/]+)(/[^/?#]+(?:\.[a-zA-Z0-9]+)?)$"
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
_IMAGE_SIZES: list[tuple[str, str]] = [
|
|
16
|
+
("medium", "500x500"),
|
|
17
|
+
("large", "1000x1000"),
|
|
18
|
+
("extralarge", ""),
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
_DATE_FORMATS = (
|
|
22
|
+
"%A %d %b %Y, %I:%M%p", # Wednesday 18 Nov 2026, 7:18pm
|
|
23
|
+
"%d %b %Y, %I:%M%p", # 18 Nov 2026, 7:18pm
|
|
24
|
+
"%d %b %Y, %H:%M", # 18 Nov 2026, 19:18
|
|
25
|
+
"%d %B %Y", # 16 April 1997
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def absolute_url(path_or_url: str | None) -> str:
|
|
30
|
+
"""Resolve a Last.fm relative path to an absolute URL."""
|
|
31
|
+
if not path_or_url:
|
|
32
|
+
return ""
|
|
33
|
+
if path_or_url.startswith(("http://", "https://")):
|
|
34
|
+
return path_or_url
|
|
35
|
+
return urljoin(BASE_URL, path_or_url)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def parse_int(value: str | None) -> int | None:
|
|
39
|
+
"""Parse formatted integer strings like '1,234,567' into int."""
|
|
40
|
+
if not value:
|
|
41
|
+
return None
|
|
42
|
+
cleaned = re.sub(r"[^\d]", "", value)
|
|
43
|
+
if not cleaned:
|
|
44
|
+
return None
|
|
45
|
+
return int(cleaned)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def parse_utc_timestamp(text: str | None) -> tuple[int, str] | None:
|
|
49
|
+
"""Parse Last.fm date strings into (unix_timestamp_utc, formatted_api_text)."""
|
|
50
|
+
if not text:
|
|
51
|
+
return None
|
|
52
|
+
cleaned = " ".join(text.strip().split())
|
|
53
|
+
for fmt in _DATE_FORMATS:
|
|
54
|
+
try:
|
|
55
|
+
dt = datetime.strptime(cleaned, fmt).replace(tzinfo=timezone.utc)
|
|
56
|
+
uts = int(dt.timestamp())
|
|
57
|
+
api_text = dt.strftime("%d %b %Y, %H:%M")
|
|
58
|
+
return uts, api_text
|
|
59
|
+
except ValueError:
|
|
60
|
+
continue
|
|
61
|
+
return None
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def expand_images(src: str | None) -> list[dict[str, str]]:
|
|
65
|
+
"""Build Last.fm API-style image list (small/medium/large/extralarge) from an image URL."""
|
|
66
|
+
if not src:
|
|
67
|
+
return [{"#text": "", "size": size} for size, _ in _IMAGE_SIZES]
|
|
68
|
+
match = _IMAGE_SIZE_RE.match(src)
|
|
69
|
+
if not match:
|
|
70
|
+
return [{"#text": src, "size": size} for size, _ in _IMAGE_SIZES]
|
|
71
|
+
prefix, _, suffix = match.groups()
|
|
72
|
+
return [
|
|
73
|
+
{
|
|
74
|
+
"#text": (
|
|
75
|
+
f"{prefix}{token}{suffix}" if token else f"{prefix}{suffix.lstrip('/')}"
|
|
76
|
+
),
|
|
77
|
+
"size": size,
|
|
78
|
+
}
|
|
79
|
+
for size, token in _IMAGE_SIZES
|
|
80
|
+
]
|