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.
- fmscrape-0.1.0/PKG-INFO +126 -0
- fmscrape-0.1.0/README.md +112 -0
- fmscrape-0.1.0/fmscrape/__init__.py +80 -0
- fmscrape-0.1.0/fmscrape/api/__init__.py +2 -0
- fmscrape-0.1.0/fmscrape/api/album.py +80 -0
- fmscrape-0.1.0/fmscrape/api/artist.py +265 -0
- fmscrape-0.1.0/fmscrape/api/auth.py +21 -0
- fmscrape-0.1.0/fmscrape/api/base.py +185 -0
- fmscrape-0.1.0/fmscrape/api/chart.py +71 -0
- fmscrape-0.1.0/fmscrape/api/geo.py +22 -0
- fmscrape-0.1.0/fmscrape/api/library.py +272 -0
- fmscrape-0.1.0/fmscrape/api/tag.py +174 -0
- fmscrape-0.1.0/fmscrape/api/track.py +144 -0
- fmscrape-0.1.0/fmscrape/api/user.py +638 -0
- fmscrape-0.1.0/fmscrape/client.py +474 -0
- fmscrape-0.1.0/fmscrape/errors.py +37 -0
- fmscrape-0.1.0/fmscrape/models.py +594 -0
- fmscrape-0.1.0/fmscrape/normalize.py +80 -0
- fmscrape-0.1.0/fmscrape/parsers/__init__.py +2 -0
- fmscrape-0.1.0/fmscrape/parsers/album.py +152 -0
- fmscrape-0.1.0/fmscrape/parsers/artist.py +305 -0
- fmscrape-0.1.0/fmscrape/parsers/chart.py +118 -0
- fmscrape-0.1.0/fmscrape/parsers/common.py +120 -0
- fmscrape-0.1.0/fmscrape/parsers/tag.py +207 -0
- fmscrape-0.1.0/fmscrape/parsers/track.py +184 -0
- fmscrape-0.1.0/fmscrape/parsers/user_lists.py +462 -0
- fmscrape-0.1.0/fmscrape/parsers/user_recent.py +190 -0
- fmscrape-0.1.0/fmscrape.egg-info/PKG-INFO +126 -0
- fmscrape-0.1.0/fmscrape.egg-info/SOURCES.txt +36 -0
- fmscrape-0.1.0/fmscrape.egg-info/dependency_links.txt +1 -0
- fmscrape-0.1.0/fmscrape.egg-info/requires.txt +8 -0
- fmscrape-0.1.0/fmscrape.egg-info/top_level.txt +1 -0
- fmscrape-0.1.0/pyproject.toml +45 -0
- fmscrape-0.1.0/setup.cfg +4 -0
- fmscrape-0.1.0/tests/test_all_groups.py +303 -0
- fmscrape-0.1.0/tests/test_client.py +110 -0
- fmscrape-0.1.0/tests/test_normalize.py +33 -0
- fmscrape-0.1.0/tests/test_user_recent.py +138 -0
fmscrape-0.1.0/PKG-INFO
ADDED
|
@@ -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
|
+
```
|
fmscrape-0.1.0/README.md
ADDED
|
@@ -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,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
|
+
|