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/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
+ ]
@@ -0,0 +1,2 @@
1
+ """HTML parsers isolated by Last.fm page type."""
2
+