tessl/pypi-pylast
A Python interface to Last.fm and Libre.fm for music data, scrobbling, and social features.
—
Pending
music-objects.mddocs/
Music Objects
Comprehensive music entity objects (Artist, Track, Album) providing access to metadata, statistics, social features, and content discovery. These objects form the core of PyLast's music data interface with rich functionality for music information retrieval and social interaction.
Capabilities
Artist Objects
Represents music artists with comprehensive metadata, statistics, social features, and discovery capabilities.
class Artist:
"""
Represents a music artist.
Args:
name (str): Artist name
network: Network instance (LastFMNetwork or LibreFMNetwork)
username (str, optional): Username for user-specific data
info (dict, optional): Preloaded artist information
"""
def __init__(self, name: str, network, username=None, info=None): ...
def get_name(self, properly_capitalized=False) -> str:
"""
Get artist name.
Args:
properly_capitalized (bool): Return properly capitalized name from Last.fm
Returns:
str: Artist name
"""
def get_correction(self) -> str:
"""Get corrected artist name from Last.fm if available."""
def get_playcount(self) -> int:
"""Get total play count for this artist."""
def get_userplaycount(self, username: str = None) -> int:
"""
Get play count for specific user.
Args:
username (str, optional): Username, uses authenticated user if None
Returns:
int: User's play count for this artist
"""
def get_listener_count(self) -> int:
"""Get total number of listeners for this artist."""
def get_mbid(self) -> str:
"""Get MusicBrainz ID for this artist."""
def get_similar(self, limit=None) -> list[SimilarItem]:
"""
Get similar artists.
Args:
limit (int, optional): Maximum number of results
Returns:
list[SimilarItem]: Similar artists with match percentages
"""
def get_top_albums(self, limit=None, cacheable=True) -> list[TopItem]:
"""Get top albums by this artist."""
def get_top_tracks(self, limit=None, cacheable=True) -> list[TopItem]:
"""Get top tracks by this artist."""
def get_top_tags(self, limit=None, cacheable=True) -> list[TopItem]:
"""Get top tags for this artist."""
def get_top_fans(self, limit=None, cacheable=True) -> list[TopItem]:
"""Get top fans (users) of this artist."""
def get_bio_published_date(self) -> str:
"""Get artist biography publication date."""
def get_bio_summary(self, language=0) -> str:
"""
Get artist biography summary.
Args:
language (int): Language domain (default: DOMAIN_ENGLISH)
Returns:
str: Biography summary
"""
def get_bio_content(self, language=0) -> str:
"""Get full artist biography content."""
def get_url(self, domain_name=0) -> str:
"""
Get Last.fm URL for this artist.
Args:
domain_name (int): Language domain
Returns:
str: Artist's Last.fm URL
"""
def get_images(self, order="popularity", limit=None) -> list[Image]:
"""
Get artist images.
Args:
order (str): Sort order ("popularity" or "dateadded")
limit (int, optional): Maximum number of images
Returns:
list[Image]: Artist images with metadata
"""Track Objects
Represents music tracks with metadata, user interactions, similarity data, and social features.
class Track:
"""
Represents a music track.
Args:
artist (str): Artist name
title (str): Track title
network: Network instance
username (str, optional): Username for user-specific data
info (dict, optional): Preloaded track information
"""
def __init__(self, artist: str, title: str, network, username=None, info=None): ...
def get_artist(self) -> Artist:
"""Get Artist object for this track's artist."""
def get_title(self) -> str:
"""Get track title."""
def get_name(self, properly_capitalized=False) -> str:
"""Get track name (alias for get_title)."""
def get_album(self) -> Album:
"""Get Album object that contains this track."""
def get_correction(self) -> str:
"""Get corrected track name from Last.fm if available."""
def get_duration(self) -> int:
"""
Get track duration in milliseconds.
Returns:
int: Duration in milliseconds, or None if unavailable
"""
def get_playcount(self) -> int:
"""Get total play count for this track."""
def get_userplaycount(self, username: str = None) -> int:
"""Get play count for specific user."""
def get_listener_count(self) -> int:
"""Get total number of listeners for this track."""
def get_userloved(self, username: str = None) -> bool:
"""
Check if user has loved this track.
Args:
username (str, optional): Username, uses authenticated user if None
Returns:
bool: True if user has loved this track
"""
def love(self) -> None:
"""Love this track (requires authentication)."""
def unlove(self) -> None:
"""Remove love from this track (requires authentication)."""
def get_similar(self, limit=None) -> list[SimilarItem]:
"""Get similar tracks."""
def get_top_fans(self, limit=None, cacheable=True) -> list[TopItem]:
"""Get top fans of this track."""
def get_cover_image(self, size=2) -> str:
"""
Get track cover art URL.
Args:
size (int): Image size (SIZE_SMALL to SIZE_MEGA)
Returns:
str: Cover image URL
"""
def get_wiki_published_date(self) -> str:
"""Get track wiki publication date."""
def get_wiki_summary(self, language=0) -> str:
"""Get track wiki summary."""
def get_wiki_content(self, language=0) -> str:
"""Get track wiki full content."""
def get_url(self, domain_name=0) -> str:
"""Get Last.fm URL for this track."""Album Objects
Represents music albums with track listings, metadata, and social features.
class Album:
"""
Represents a music album.
Args:
artist (str): Artist name
title (str): Album title
network: Network instance
username (str, optional): Username for user-specific data
info (dict, optional): Preloaded album information
"""
def __init__(self, artist: str, title: str, network, username=None, info=None): ...
def get_artist(self) -> Artist:
"""Get Artist object for this album's artist."""
def get_title(self) -> str:
"""Get album title."""
def get_name(self, properly_capitalized=False) -> str:
"""Get album name (alias for get_title)."""
def get_tracks(self) -> list[Track]:
"""
Get list of tracks on this album.
Returns:
list[Track]: All tracks on the album
"""
def get_playcount(self) -> int:
"""Get total play count for this album."""
def get_userplaycount(self, username: str = None) -> int:
"""Get play count for specific user."""
def get_listener_count(self) -> int:
"""Get total number of listeners for this album."""
def get_cover_image(self, size=2) -> str:
"""
Get album cover art URL.
Args:
size (int): Image size (SIZE_SMALL to SIZE_MEGA)
Returns:
str: Cover image URL
"""
def get_top_tags(self, limit=None, cacheable=True) -> list[TopItem]:
"""Get top tags for this album."""
def get_wiki_published_date(self) -> str:
"""Get album wiki publication date."""
def get_wiki_summary(self, language=0) -> str:
"""Get album wiki summary."""
def get_wiki_content(self, language=0) -> str:
"""Get album wiki full content."""
def get_url(self, domain_name=0) -> str:
"""Get Last.fm URL for this album."""Tag Management
All music objects (Artist, Track, Album) support tag management for categorization and discovery.
# Tag management methods (available on Artist, Track, Album)
def add_tags(self, tags: tuple[str, ...]) -> None:
"""
Add tags to this music object.
Args:
tags (tuple[str, ...]): Tags to add
"""
def remove_tag(self, tag: str) -> None:
"""
Remove a tag from this music object.
Args:
tag (str): Tag to remove
"""
def get_tags(self) -> list[Tag]:
"""
Get tags applied to this music object.
Returns:
list[Tag]: Tags applied by the authenticated user
"""
def get_top_tags(self, limit=None, cacheable=True) -> list[TopItem]:
"""
Get top tags for this music object.
Returns:
list[TopItem]: Most popular tags with weights
"""Additional Music Object Methods
Additional utility methods available on music objects for URL generation and metadata access.
# Additional methods (available on Artist, Track, Album)
def get_url(self, domain_name: int = 0) -> str:
"""
Get Last.fm URL for this music object.
Args:
domain_name (int): Language domain (DOMAIN_ENGLISH, DOMAIN_GERMAN, etc.)
Returns:
str: Last.fm URL for this object
"""
def get_mbid(self) -> str | None:
"""
Get MusicBrainz ID for this music object.
Returns:
str | None: MusicBrainz ID if available, None otherwise
"""Usage Examples
Working with Artists
import pylast
network = pylast.LastFMNetwork(api_key=API_KEY, api_secret=API_SECRET)
# Get artist and basic info
artist = network.get_artist("Radiohead")
print(f"Artist: {artist.get_name(properly_capitalized=True)}")
print(f"Listeners: {artist.get_listener_count():,}")
print(f"Play count: {artist.get_playcount():,}")
# Get similar artists
similar = artist.get_similar(limit=5)
for similar_artist in similar:
print(f"Similar: {similar_artist.item.get_name()} ({similar_artist.match}% match)")
# Get top tracks
top_tracks = artist.get_top_tracks(limit=10)
for track_item in top_tracks:
track = track_item.item
print(f"Top track: {track.get_title()} (weight: {track_item.weight})")
# Get artist biography
bio_summary = artist.get_bio_summary()
print(f"Bio: {bio_summary[:200]}...")Working with Tracks
# Get track and interact with it
track = network.get_track("Radiohead", "Paranoid Android")
print(f"Track: {track.get_title()}")
print(f"Album: {track.get_album().get_title()}")
print(f"Duration: {track.get_duration() / 1000:.1f} seconds")
# Love the track (requires authentication)
if network.session_key:
track.love()
print("Track loved!")
# Add tags
track.add_tags(("alternative rock", "90s", "progressive"))
print("Tags added!")
# Get similar tracks
similar_tracks = track.get_similar(limit=5)
for similar_track in similar_tracks:
print(f"Similar: {similar_track.item.get_artist().get_name()} - {similar_track.item.get_title()}")Working with Albums
# Get album and its tracks
album = network.get_album("Pink Floyd", "The Dark Side of the Moon")
print(f"Album: {album.get_title()}")
print(f"Artist: {album.get_artist().get_name()}")
# Get track listing
tracks = album.get_tracks()
for i, track in enumerate(tracks, 1):
duration = track.get_duration()
duration_str = f"{duration // 60000}:{(duration % 60000) // 1000:02d}" if duration else "Unknown"
print(f"{i:2d}. {track.get_title()} ({duration_str})")
# Get album artwork
cover_url = album.get_cover_image(size=pylast.SIZE_LARGE)
print(f"Cover art: {cover_url}")Batch Operations
# Work with multiple artists
artist_names = ["The Beatles", "Led Zeppelin", "Pink Floyd", "The Rolling Stones"]
artists = [network.get_artist(name) for name in artist_names]
# Get statistics for all artists
for artist in artists:
stats = {
'name': artist.get_name(),
'listeners': artist.get_listener_count(),
'playcount': artist.get_playcount()
}
print(f"{stats['name']}: {stats['listeners']:,} listeners, {stats['playcount']:,} plays")Install with Tessl CLI
npx tessl i tessl/pypi-pylast