fmscrape 0.1.0__tar.gz

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.

Files changed (38) hide show
  1. fmscrape-0.1.0/PKG-INFO +126 -0
  2. fmscrape-0.1.0/README.md +112 -0
  3. fmscrape-0.1.0/fmscrape/__init__.py +80 -0
  4. fmscrape-0.1.0/fmscrape/api/__init__.py +2 -0
  5. fmscrape-0.1.0/fmscrape/api/album.py +80 -0
  6. fmscrape-0.1.0/fmscrape/api/artist.py +265 -0
  7. fmscrape-0.1.0/fmscrape/api/auth.py +21 -0
  8. fmscrape-0.1.0/fmscrape/api/base.py +185 -0
  9. fmscrape-0.1.0/fmscrape/api/chart.py +71 -0
  10. fmscrape-0.1.0/fmscrape/api/geo.py +22 -0
  11. fmscrape-0.1.0/fmscrape/api/library.py +272 -0
  12. fmscrape-0.1.0/fmscrape/api/tag.py +174 -0
  13. fmscrape-0.1.0/fmscrape/api/track.py +144 -0
  14. fmscrape-0.1.0/fmscrape/api/user.py +638 -0
  15. fmscrape-0.1.0/fmscrape/client.py +474 -0
  16. fmscrape-0.1.0/fmscrape/errors.py +37 -0
  17. fmscrape-0.1.0/fmscrape/models.py +594 -0
  18. fmscrape-0.1.0/fmscrape/normalize.py +80 -0
  19. fmscrape-0.1.0/fmscrape/parsers/__init__.py +2 -0
  20. fmscrape-0.1.0/fmscrape/parsers/album.py +152 -0
  21. fmscrape-0.1.0/fmscrape/parsers/artist.py +305 -0
  22. fmscrape-0.1.0/fmscrape/parsers/chart.py +118 -0
  23. fmscrape-0.1.0/fmscrape/parsers/common.py +120 -0
  24. fmscrape-0.1.0/fmscrape/parsers/tag.py +207 -0
  25. fmscrape-0.1.0/fmscrape/parsers/track.py +184 -0
  26. fmscrape-0.1.0/fmscrape/parsers/user_lists.py +462 -0
  27. fmscrape-0.1.0/fmscrape/parsers/user_recent.py +190 -0
  28. fmscrape-0.1.0/fmscrape.egg-info/PKG-INFO +126 -0
  29. fmscrape-0.1.0/fmscrape.egg-info/SOURCES.txt +36 -0
  30. fmscrape-0.1.0/fmscrape.egg-info/dependency_links.txt +1 -0
  31. fmscrape-0.1.0/fmscrape.egg-info/requires.txt +8 -0
  32. fmscrape-0.1.0/fmscrape.egg-info/top_level.txt +1 -0
  33. fmscrape-0.1.0/pyproject.toml +45 -0
  34. fmscrape-0.1.0/setup.cfg +4 -0
  35. fmscrape-0.1.0/tests/test_all_groups.py +303 -0
  36. fmscrape-0.1.0/tests/test_client.py +110 -0
  37. fmscrape-0.1.0/tests/test_normalize.py +33 -0
  38. fmscrape-0.1.0/tests/test_user_recent.py +138 -0
@@ -0,0 +1,126 @@
1
+ Metadata-Version: 2.4
2
+ Name: fmscrape
3
+ Version: 0.1.0
4
+ Summary: Last.fm public HTML scraper with an API-compatible interface (no API key required).
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: httpx>=0.27.0
8
+ Requires-Dist: beautifulsoup4>=4.12.0
9
+ Requires-Dist: lxml>=5.0.0
10
+ Provides-Extra: dev
11
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
12
+ Requires-Dist: mypy>=1.10.0; extra == "dev"
13
+ Requires-Dist: ruff>=0.4.0; extra == "dev"
14
+
15
+ # fmscrape
16
+
17
+ Python library for reading public **Last.fm** data without an API key, with an interface compatible with the official Last.fm API v2. Returns JSON-ready `dict`s by default, or typed `dataclasses` when `raw_json=False`.
18
+
19
+ > **Disclaimer**: Use of this library is subject to Last.fm's Terms of Service. Data is parsed from public HTML pages on `last.fm`, so parsing may break if Last.fm changes its layout or access rules. This project is not affiliated with Last.fm.
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ cd fmscrape
25
+ python -m venv --system-site-packages .venv
26
+ .\.venv\Scripts\activate
27
+ pip install -e .
28
+ ```
29
+
30
+ > **Note**: Do not run scripts that `import fmscrape` from the parent directory containing the `fmscrape/` project folder, as Python will treat that folder as an empty namespace package. Run from inside `fmscrape/` or another directory.
31
+
32
+ ## Usage
33
+
34
+ ### Without Cookies
35
+
36
+ ```python
37
+ import json
38
+ from fmscrape import LastFmClient
39
+
40
+ with LastFmClient(rate_limit=1.0, cache_ttl=60.0) as client:
41
+ recent = client.user.get_recent_tracks("rj", limit=10)
42
+ print(json.dumps(recent, indent=2, ensure_ascii=False))
43
+
44
+ artist = client.artist.get_info("Radiohead")
45
+ print(artist["artist"]["name"], artist["artist"]["stats"])
46
+
47
+ for album in client.artist.iter_top_albums("Radiohead", max_pages=1):
48
+ print(album["name"])
49
+
50
+ # Typed dataclasses instead of dicts
51
+ with LastFmClient(raw_json=False) as client:
52
+ artist = client.artist.get_info("Radiohead")
53
+ print(artist.name, artist.stats.listeners)
54
+ ```
55
+
56
+ ### With User Cookies
57
+
58
+ Some user endpoints (`/user/<user>`, `/library/tracks`, `/loved`, `/tags`, and `period` / `from_ts` / `to_ts` filters) require browser session cookies. Only these 4 cookies are required: `sessionid`, `csrftoken`, `fsuid`, and `lfmanon=0`.
59
+
60
+ ```python
61
+ from fmscrape import LastFmClient
62
+
63
+ cookies = "sessionid=...; csrftoken=...; fsuid=...; lfmanon=0"
64
+ with LastFmClient(cookies=cookies) as client:
65
+ profile = client.user.get_info("user")
66
+ top_tracks = client.user.get_top_tracks("user", period="7day", page=2)
67
+
68
+ # Unix GMT timestamp filters work across library endpoints
69
+ artists_range = client.library.get_artists(
70
+ "user", from_ts=1792324800, to_ts=1792929600
71
+ )
72
+
73
+ # Total plays for a specific album or track (with or without filters)
74
+ album_plays = client.library.get_album_plays(
75
+ "user", "Radiohead", "The Bends"
76
+ )
77
+ track_plays = client.library.get_track_plays(
78
+ "user", "Radiohead", "High and Dry",
79
+ from_ts=1792324800, to_ts=1792929600,
80
+ )
81
+ print(album_plays["library"]["playcount"], track_plays["library"]["playcount"])
82
+ ```
83
+
84
+ ### Async Client
85
+
86
+ ```python
87
+ import asyncio
88
+ from fmscrape import AsyncLastFmClient
89
+
90
+ async def main() -> None:
91
+ async with AsyncLastFmClient() as client:
92
+ info = await client.album.get_info("Radiohead", "OK Computer")
93
+ print(info["album"]["name"], len(info["album"]["tracks"]["track"]))
94
+
95
+ asyncio.run(main())
96
+ ```
97
+
98
+ ### `robots.txt`
99
+
100
+ By default, `respect_robots=True` enforces Last.fm's `robots.txt`, which disallows `/search*`, `/tag/*`, `/music/*/+tags*`, and `/music/*?`. Initialize with `LastFmClient(respect_robots=False)` if you need those routes.
101
+
102
+ ## API Compatibility
103
+
104
+ See [docs/map.md](docs/map.md) for the full URL and field mapping.
105
+
106
+ | Group | Public | With User Cookies | Unsupported |
107
+ | :--- | :--- | :--- | :--- |
108
+ | `user` | `get_recent_tracks`, `get_top_artists` (`overall`), `get_top_albums` (`overall`), `get_friends`, `get_personal_tags` | `get_info`, `get_top_tracks`, `get_loved_tracks`, `get_top_tags`, `period` (`7day`–`12month`), `from_ts`/`to_ts`, `get_weekly_artist_chart`, `get_weekly_album_chart`, `get_weekly_track_chart` | `get_weekly_chart_list` |
109
+ | `artist` | `get_info`, `get_similar`, `get_top_albums`, `get_top_tracks`, `get_correction`, `get_top_tags`\*, `search`\* | Same | `add_tags`, `remove_tag` |
110
+ | `album` | `get_info`, `get_top_tags`\*, `search`\* | Same | `add_tags`, `remove_tag` |
111
+ | `track` | `get_info`, `get_similar`, `get_correction`, `get_top_tags`\*, `search`\* | Same | `scrobble`, `love`, `unlove`, `update_now_playing`, `add_tags`, `remove_tag` |
112
+ | `tag` | `get_info`\*, `get_similar`\*, `get_top_artists`\*, `get_top_albums`\*, `get_top_tracks`\* | Same | `get_top_tags`, `get_weekly_chart_list` |
113
+ | `chart` | `get_top_artists`, `get_top_tracks` | Same | `get_top_tags` |
114
+ | `geo` | — | — | `get_top_artists`, `get_top_tracks` |
115
+ | `library` | `get_artists` | Same | — |
116
+ | `auth` | — | — | `get_token`, `get_session`, `get_mobile_session` |
117
+
118
+ \* Disallowed in `robots.txt`; requires `respect_robots=False`.
119
+
120
+ ## Tests
121
+
122
+ ```bash
123
+ pytest -v
124
+ mypy fmscrape
125
+ pytest -m live
126
+ ```
@@ -0,0 +1,112 @@
1
+ # fmscrape
2
+
3
+ Python library for reading public **Last.fm** data without an API key, with an interface compatible with the official Last.fm API v2. Returns JSON-ready `dict`s by default, or typed `dataclasses` when `raw_json=False`.
4
+
5
+ > **Disclaimer**: Use of this library is subject to Last.fm's Terms of Service. Data is parsed from public HTML pages on `last.fm`, so parsing may break if Last.fm changes its layout or access rules. This project is not affiliated with Last.fm.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ cd fmscrape
11
+ python -m venv --system-site-packages .venv
12
+ .\.venv\Scripts\activate
13
+ pip install -e .
14
+ ```
15
+
16
+ > **Note**: Do not run scripts that `import fmscrape` from the parent directory containing the `fmscrape/` project folder, as Python will treat that folder as an empty namespace package. Run from inside `fmscrape/` or another directory.
17
+
18
+ ## Usage
19
+
20
+ ### Without Cookies
21
+
22
+ ```python
23
+ import json
24
+ from fmscrape import LastFmClient
25
+
26
+ with LastFmClient(rate_limit=1.0, cache_ttl=60.0) as client:
27
+ recent = client.user.get_recent_tracks("rj", limit=10)
28
+ print(json.dumps(recent, indent=2, ensure_ascii=False))
29
+
30
+ artist = client.artist.get_info("Radiohead")
31
+ print(artist["artist"]["name"], artist["artist"]["stats"])
32
+
33
+ for album in client.artist.iter_top_albums("Radiohead", max_pages=1):
34
+ print(album["name"])
35
+
36
+ # Typed dataclasses instead of dicts
37
+ with LastFmClient(raw_json=False) as client:
38
+ artist = client.artist.get_info("Radiohead")
39
+ print(artist.name, artist.stats.listeners)
40
+ ```
41
+
42
+ ### With User Cookies
43
+
44
+ Some user endpoints (`/user/<user>`, `/library/tracks`, `/loved`, `/tags`, and `period` / `from_ts` / `to_ts` filters) require browser session cookies. Only these 4 cookies are required: `sessionid`, `csrftoken`, `fsuid`, and `lfmanon=0`.
45
+
46
+ ```python
47
+ from fmscrape import LastFmClient
48
+
49
+ cookies = "sessionid=...; csrftoken=...; fsuid=...; lfmanon=0"
50
+ with LastFmClient(cookies=cookies) as client:
51
+ profile = client.user.get_info("user")
52
+ top_tracks = client.user.get_top_tracks("user", period="7day", page=2)
53
+
54
+ # Unix GMT timestamp filters work across library endpoints
55
+ artists_range = client.library.get_artists(
56
+ "user", from_ts=1792324800, to_ts=1792929600
57
+ )
58
+
59
+ # Total plays for a specific album or track (with or without filters)
60
+ album_plays = client.library.get_album_plays(
61
+ "user", "Radiohead", "The Bends"
62
+ )
63
+ track_plays = client.library.get_track_plays(
64
+ "user", "Radiohead", "High and Dry",
65
+ from_ts=1792324800, to_ts=1792929600,
66
+ )
67
+ print(album_plays["library"]["playcount"], track_plays["library"]["playcount"])
68
+ ```
69
+
70
+ ### Async Client
71
+
72
+ ```python
73
+ import asyncio
74
+ from fmscrape import AsyncLastFmClient
75
+
76
+ async def main() -> None:
77
+ async with AsyncLastFmClient() as client:
78
+ info = await client.album.get_info("Radiohead", "OK Computer")
79
+ print(info["album"]["name"], len(info["album"]["tracks"]["track"]))
80
+
81
+ asyncio.run(main())
82
+ ```
83
+
84
+ ### `robots.txt`
85
+
86
+ By default, `respect_robots=True` enforces Last.fm's `robots.txt`, which disallows `/search*`, `/tag/*`, `/music/*/+tags*`, and `/music/*?`. Initialize with `LastFmClient(respect_robots=False)` if you need those routes.
87
+
88
+ ## API Compatibility
89
+
90
+ See [docs/map.md](docs/map.md) for the full URL and field mapping.
91
+
92
+ | Group | Public | With User Cookies | Unsupported |
93
+ | :--- | :--- | :--- | :--- |
94
+ | `user` | `get_recent_tracks`, `get_top_artists` (`overall`), `get_top_albums` (`overall`), `get_friends`, `get_personal_tags` | `get_info`, `get_top_tracks`, `get_loved_tracks`, `get_top_tags`, `period` (`7day`–`12month`), `from_ts`/`to_ts`, `get_weekly_artist_chart`, `get_weekly_album_chart`, `get_weekly_track_chart` | `get_weekly_chart_list` |
95
+ | `artist` | `get_info`, `get_similar`, `get_top_albums`, `get_top_tracks`, `get_correction`, `get_top_tags`\*, `search`\* | Same | `add_tags`, `remove_tag` |
96
+ | `album` | `get_info`, `get_top_tags`\*, `search`\* | Same | `add_tags`, `remove_tag` |
97
+ | `track` | `get_info`, `get_similar`, `get_correction`, `get_top_tags`\*, `search`\* | Same | `scrobble`, `love`, `unlove`, `update_now_playing`, `add_tags`, `remove_tag` |
98
+ | `tag` | `get_info`\*, `get_similar`\*, `get_top_artists`\*, `get_top_albums`\*, `get_top_tracks`\* | Same | `get_top_tags`, `get_weekly_chart_list` |
99
+ | `chart` | `get_top_artists`, `get_top_tracks` | Same | `get_top_tags` |
100
+ | `geo` | — | — | `get_top_artists`, `get_top_tracks` |
101
+ | `library` | `get_artists` | Same | — |
102
+ | `auth` | — | — | `get_token`, `get_session`, `get_mobile_session` |
103
+
104
+ \* Disallowed in `robots.txt`; requires `respect_robots=False`.
105
+
106
+ ## Tests
107
+
108
+ ```bash
109
+ pytest -v
110
+ mypy fmscrape
111
+ pytest -m live
112
+ ```
@@ -0,0 +1,80 @@
1
+ """fmscrape: Last.fm public HTML scraper with an API-compatible interface."""
2
+
3
+ from fmscrape.client import AsyncLastFmClient, LastFmClient
4
+ from fmscrape.errors import (
5
+ FmScrapeError,
6
+ NetworkError,
7
+ NotFoundError,
8
+ NotSupportedError,
9
+ ParseError,
10
+ RateLimitError,
11
+ RobotsDisallowedError,
12
+ )
13
+ from fmscrape.models import (
14
+ AlbumEntry,
15
+ AlbumInfo,
16
+ AlbumListPage,
17
+ AlbumRef,
18
+ ArtistEntry,
19
+ ArtistInfo,
20
+ ArtistListPage,
21
+ ArtistRef,
22
+ CorrectionResult,
23
+ DateInfo,
24
+ FriendsPage,
25
+ Image,
26
+ LibraryPlays,
27
+ PaginationAttr,
28
+ RecentTrack,
29
+ RecentTracksPage,
30
+ SearchResultsPage,
31
+ StatsInfo,
32
+ TagDetails,
33
+ TagInfo,
34
+ TagsListResult,
35
+ TrackEntry,
36
+ TrackInfo,
37
+ TrackListPage,
38
+ UserEntry,
39
+ UserInfo,
40
+ WikiInfo,
41
+ )
42
+
43
+ __all__ = [
44
+ "AlbumEntry",
45
+ "AlbumInfo",
46
+ "AlbumListPage",
47
+ "AlbumRef",
48
+ "ArtistEntry",
49
+ "ArtistInfo",
50
+ "ArtistListPage",
51
+ "ArtistRef",
52
+ "AsyncLastFmClient",
53
+ "CorrectionResult",
54
+ "DateInfo",
55
+ "FmScrapeError",
56
+ "FriendsPage",
57
+ "Image",
58
+ "LastFmClient",
59
+ "LibraryPlays",
60
+ "NetworkError",
61
+ "NotFoundError",
62
+ "NotSupportedError",
63
+ "PaginationAttr",
64
+ "ParseError",
65
+ "RateLimitError",
66
+ "RecentTrack",
67
+ "RecentTracksPage",
68
+ "RobotsDisallowedError",
69
+ "SearchResultsPage",
70
+ "StatsInfo",
71
+ "TagDetails",
72
+ "TagInfo",
73
+ "TagsListResult",
74
+ "TrackEntry",
75
+ "TrackInfo",
76
+ "TrackListPage",
77
+ "UserEntry",
78
+ "UserInfo",
79
+ "WikiInfo",
80
+ ]
@@ -0,0 +1,2 @@
1
+ """API namespace modules mirroring Last.fm API v2."""
2
+
@@ -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
+ )
@@ -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
+ )
@@ -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
+