2. API Reference
This page lists all of the last.fm interfaces exposed by the pydrag package.
2.1. Track Class
- class pydrag.Track(name, artist, url=None, mbid=None, image=None, playcount=None, userplaycount=None, listeners=None, duration=None, match=None, wiki=None, album=None, top_tags=None, loved=None, timestamp=None, rank=None)[source]
Bases:
pydrag.services.ApiMixin,pydrag.models.common.BaseModelLast.FM track, chart and geo api wrapper.
- Parameters
name (
str) – Track name/titleartist (
Artist) – Artist nameuserplaycount (
Optional[int]) – The user context total track playcountduration (
Optional[int]) – Track duration in seconds, should be intrank (
Optional[int]) – Rank of the track based on the requested resourcetimestamp (
Optional[int]) – Unix timestamp the user listened or loved this trackloved (
Optional[bool]) – True/False if the track is one of the user’s loved ones
- property date: Optional[datetime.datetime]
If the timestamp property is available return a datetime instance.
- Return type
- classmethod from_dict(data)[source]
Construct a BaseModel from a dictionary based on the class fields type annotations. Only primitive types are supported.
- get_info(user=None, lang='en')[source]
There are many ways we end up with an incomplete instance of a track instance likes charts, tags etc, This is a quick method to refresh our object with complete data from the find methods.
- classmethod get_correction(track, artist)[source]
Use the last.fm corrections data to check whether the supplied track has a correction to a canonical track.
- Return type
- classmethod search(track, limit=50, page=1)[source]
Search for an track by name. Returns track matches sorted by relevance.
- Parameters
- Return type
- classmethod get_top_tracks_chart(limit=50, page=1)[source]
Get the top tracks chart.
- Parameters
- Return type
- add_tags(tags)[source]
Tag an track with one or more user supplied tags.
- remove_tag(tag)[source]
Remove a user’s tag from an track.
- Parameters
tag (
str) – A single user tag to remove from this track.- Return type
- get_similar(limit=50)[source]
Get all the tracks similar to this track.
- Parameters
limit (
int) – Limit the number of similar tracks returned- Return type
- get_tags(user)[source]
Get the tags applied by an individual user to an track on Last.fm.
- Parameters
user (
str) – The username for the context of the request.- Return type
- get_top_tags()[source]
Get the top tags for an track on Last.fm, ordered by popularity.
- Return type
- classmethod scrobble_tracks(tracks, batch_size=10)[source]
Split tracks into the desired batch size, with maximum size set to 50 and send the tracks for processing, I am debating if this even belongs here.
- Parameters
tracks (
List[ScrobbleTrack]) – The tracks to scrobblebatch_size – The number of tracks to submit per cycle
- Return type
pydrag.models.common.ListModelofScrobbleTrack
- classmethod update_now_playing(artist, track, album=None, track_number=None, context=None, duration=None, album_artist=None)[source]
2.2. Album Class
- class pydrag.Album(name, mbid=None, url=None, image=None, playcount=None, artist=None, listeners=None, tags=None, tracks=None, wiki=None, rank=None)[source]
Bases:
pydrag.models.common.BaseModel,pydrag.services.ApiMixinLast.FM track, chart and geo api wrapper.
- Parameters
- classmethod from_dict(data)[source]
Construct a BaseModel from a dictionary based on the class fields type annotations. Only primitive types are supported.
- classmethod find(artist, album, user=None, lang='en')[source]
Get the metadata and tracklist for an album on Last.fm.
- Parameters
- Return type
- classmethod find_by_mbid(mbid, user=None, lang='en')[source]
Get the metadata and tracklist for an album on Last.fm.
- get_info(user=None, lang='en')[source]
There are many ways we end up with an incomplete instance of an album instance likes charts, tags etc, This is a quick method to refresh our object with complete data from the find methods.
- classmethod search(album, limit=50, page=1)[source]
Search for an album by name.Returns album matches sorted by relevance.
- Parameters
- Return type
- add_tags(tags)[source]
Tag an album using a list of user supplied tags.
- remove_tag(tag)[source]
Remove a user’s tag from an album.
- Parameters
tag (
str) – A single user tag to remove from this album.- Return type
- get_tags(user)[source]
Get the tags applied by an individual user to an album on Last.fm.
- Parameters
user (
str) – The username for the context of the request.- Return type
2.3. Artist Class
- class pydrag.Artist(name, mbid=None, url=None, tag_count=None, listeners=None, playcount=None, userplaycount=None, image=None, match=None, tags=None, bio=None, on_tour=None, similar=None, rank=None)[source]
Bases:
pydrag.models.common.BaseModel,pydrag.services.ApiMixinLast.FM track, chart and geo api wrapper.
- Parameters
- classmethod from_dict(data)[source]
Construct a BaseModel from a dictionary based on the class fields type annotations. Only primitive types are supported.
- classmethod find(artist, user=None, lang='en')[source]
Get the metadata for an artist. Includes biography, truncated at 300 characters.
- classmethod find_by_mbid(mbid, user=None, lang='en')[source]
Get the metadata for an artist. Includes biography, truncated at 300 characters.
- get_info(user=None, lang='en')[source]
There are many ways we end up with an incomplete instance of an artist instance likes charts, tags etc, This is a quick method to refresh our object with complete data from the find methods.
- classmethod search(artist, limit=50, page=1)[source]
Search for an artist by name. Returns artist matches sorted by relevance.
- Parameters
- Return type
- classmethod get_top_artists_chart(limit=50, page=1)[source]
Get the top artists chart.
- Parameters
- Return type
- add_tags(tags)[source]
Tag an artist with one or more user supplied tags.
- remove_tag(tag)[source]
Remove a user’s tag from an artist.
- Parameters
tag (
str) – A single user tag to remove from this artist.- Return type
- get_correction()[source]
Use the last.fm corrections data to check whether the supplied artist has a correction to a canonical artist.
- Return type
- get_similar(limit=50)[source]
Get all the artists similar to this artist.
- Parameters
limit (
int) – Limit the number of similar artists returned- Return type
- get_tags(user)[source]
Get the tags applied by an individual user to an artist on Last.fm.
- Parameters
user (
str) – The username for the context of the request.- Return type
2.4. User Class
- class pydrag.User(playlists, playcount, gender, name, url, country, image, age, registered, real_name=None, recent_track=None)[source]
Bases:
pydrag.models.common.BaseModel,pydrag.services.ApiMixinLast.FM user and user library api wrapper.
- Parameters
playcount (
int) – Total track playcountgender (
str) – Gendername (
str) – Display nameurl (
str) – Last.fm profile urlcountry (
str) – Country nameage (
int) – Self explanatoryregistered (
int) – Unix timestamp of the registration daterecent_track (
Optional[Track]) – User’s most recent scrobble track
- property date_registered: datetime.datetime
Return a datetime instance of the user’s registration date.
- Return type
- classmethod from_dict(data)[source]
Construct a BaseModel from a dictionary based on the class fields type annotations. Only primitive types are supported.
- get_artists(limit=50, page=1)[source]
Retrieve a paginated list of all the artists in the user’s library, with playcounts and tagcounts.
- get_artist_tracks(artist, from_date=None, to_date=None, page=1)[source]
Get a list of tracks by a given artist scrobbled by this user, including scrobble time. Can be limited to specific timeranges, defaults to all time.
- get_recent_tracks(from_date=None, to_date=None, limit=50, page=1)[source]
Get a list of the recent tracks listened to by this user. Also includes the currently playing track with the nowplaying=”true” attribute if the user is currently listening.
- Parameters
from_date (
Optional[str]) – Beginning timestamp of a range - only display scrobbles after this time, in UNIX timestamp format (integer number of seconds since 00:00:00, January 1st 1970 UTC). This must be in the UTC time zone.to_date (
Optional[str]) – End timestamp of a range - only display scrobbles before this time, in UNIX timestamp format (integer number of seconds since 00:00:00, January 1st 1970 UTC). This must be in the UTC time zone.limit (
int) – The number of results to fetch per page.page (
int) – The page number to fetch.
- Return type
- get_top_albums(period, limit=50, page=1)[source]
Get the top albums listened to by a user. You can stipulate a time period.
- get_top_artists(period, limit=50, page=1)[source]
Get the top artists listened to by a user. You can stipulate a time period.
- get_top_tracks(period, limit=50, page=1)[source]
Get the top tracks listened to by a user. You can stipulate a time period.
- get_weekly_artist_chart(from_date=None, to_date=None)[source]
Get an album chart for a user profile, for a given date range. If no date range is supplied, it will return the most recent album chart for this user.
- get_weekly_chart_list()[source]
Get an artist chart for a user profile, for a given date range. If no date range is supplied, it will return the most recent artist chart for this user.
2.5. Tag Class
- class pydrag.Tag(name, reach=None, url=None, taggings=None, count=None, total=None, wiki=None)[source]
Bases:
pydrag.models.common.BaseModel,pydrag.services.ApiMixinLast.FM tag, chart and geo api wrapper.
- Parameters
- classmethod from_dict(data)[source]
Construct a BaseModel from a dictionary based on the class fields type annotations. Only primitive types are supported.
- classmethod get_top_tags(limit=50, page=1)[source]
Fetches the top global tags on Last.fm, sorted by popularity Old school pagination on this endpoint, keep uniformity.
- Parameters
- Return type
- classmethod get_top_tags_chart(limit=50, page=1)[source]
Get the top tags chart.
- Parameters
- Return type
- get_similar()[source]
Search for tags similar to this one. Returns tags ranked by similarity, based on listening data.
- Return type
- get_top_albums(limit=50, page=1)[source]
Get the top albums tagged by this tag, ordered by tag count.
- Parameters
- Return type
- get_top_artists(limit=50, page=1)[source]
Get the top artists tagged by this tag, ordered by tag count.
- Parameters
- Return type
- get_top_tracks(limit=50, page=1)[source]
Get the top tracks tagged by this tag, ordered by tag count.
- Parameters
- Return type
2.6. Common Classes
- class pydrag.models.common.BaseModel[source]
Bases:
objectPydrag Base Model.
- Parameters
params – The params used to fetch the api response data
- class pydrag.models.common.ListModel(data=<factory>, page=None, limit=None, total=None, tag=None, user=None, artist=None, track=None, album=None, country=None, from_date=None, to_date=None, search_terms=None)[source]
Bases:
collections.UserList,Sequence[T],pydrag.models.common.BaseModelWrap a list of
BaseModelobjects with metadata.- Parameters
data (
List[~T]) – Our list of objects
- class pydrag.models.common.RawResponse(data=None)[source]
Bases:
pydrag.models.common.BaseModelMost of the write operations don’t return any response body but still for consistency we need to return a BaseModel with all the metadata params.
- class pydrag.models.common.Config(api_key, api_secret, username, password, session=None)[source]
Bases:
objectPydrag config object for your last.fm api.
2.7. Api Mixin
- class pydrag.services.ApiMixin[source]
Bases:
object- classmethod get_session()[source]
Return the session from configuration or attempt to authenticate the configuration user.
- Return type
AuthSession
- classmethod retrieve(bind, flatten=None, params=None)[source]
Perform an api retrieve/get resource action.
- classmethod submit(bind, flatten=None, params=None, sign=False, stateful=False, authenticate=False)[source]
Perform an api write/update resource action.
- Parameters
bind (
BaseModel) – Class type to construct from the api response.flatten (str) – A dot separated string used to flatten nested list of values
params (Dict) – A dictionary of body params
sign (bool) – Sign the request with the api secret
stateful (bool) – Requires a session
authenticate (bool) – Perform an authentication request
- Return type
- classmethod prepare_params(params, sign, stateful, authenticate)[source]
Perform common parameter tasks before sending the web request.
Filter out None values,
Set the preferred api format
jsonAdd the api key, session or signature based on the state flags
- classmethod bind_data(bind, body, flatten=None)[source]
Construct a BaseModel from the response body and the flatten directive.