CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-mopidy

Mopidy is an extensible music server written in Python

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

models.mddocs/

Models and Data Structures

Mopidy's immutable data models represent music metadata and provide the foundation for all music-related operations. These models are designed to be immutable, validated, and serializable, ensuring data consistency throughout the system.

Capabilities

Base Model Classes

Foundation classes for all Mopidy models providing immutability, validation, and serialization capabilities.

class ImmutableObject:
    """Base class for immutable objects with keyword-only construction."""
    def __init__(self, **kwargs): ...
    def replace(self, **kwargs): ...

class ValidatedImmutableObject(ImmutableObject):
    """Base class with field validation and type checking."""
    def __init__(self, **kwargs): ...

Reference Objects

Lightweight URI references with human-friendly names and type information, used for browsing and navigation without full metadata.

class Ref(ValidatedImmutableObject):
    """
    Model to represent URI references with a human friendly name and type.
    
    Parameters:
    - uri (str): Object URI
    - name (str): Human-readable name  
    - type (str): Object type ('artist', 'album', 'track', 'playlist', 'directory')
    """
    uri: str
    name: str
    type: str
    
    # Type constants
    ALBUM = "album"
    ARTIST = "artist" 
    DIRECTORY = "directory"
    PLAYLIST = "playlist"
    TRACK = "track"
    
    @classmethod
    def album(cls, **kwargs): ...
    
    @classmethod
    def artist(cls, **kwargs): ...
    
    @classmethod
    def directory(cls, **kwargs): ...
    
    @classmethod
    def playlist(cls, **kwargs): ...
    
    @classmethod
    def track(cls, **kwargs): ...

Usage example:

# Create references using factory methods
artist_ref = Ref.artist(uri="spotify:artist:123", name="The Beatles")
album_ref = Ref.album(uri="spotify:album:456", name="Abbey Road")
track_ref = Ref.track(uri="spotify:track:789", name="Come Together")

Artist Metadata

Artist information including identifiers, names, and metadata for music organization and display.

class Artist(ValidatedImmutableObject):
    """
    Artist metadata model.
    
    Parameters:
    - uri (str): Artist URI
    - name (str): Artist name
    - sortname (str, optional): Artist name for sorting (e.g., without articles)
    - musicbrainz_id (str, optional): MusicBrainz identifier
    """
    uri: str
    name: str
    sortname: str
    musicbrainz_id: str

Usage example:

artist = Artist(
    uri="local:artist:the-beatles",
    name="The Beatles",
    sortname="Beatles, The",
    musicbrainz_id="b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d"
)

Album Metadata

Album information including tracks, release details, and associated artists.

class Album(ValidatedImmutableObject):
    """
    Album metadata model.
    
    Parameters:
    - uri (str): Album URI
    - name (str): Album name
    - artists (frozenset[Artist]): Album artists
    - num_tracks (int, optional): Number of tracks in album
    - num_discs (int, optional): Number of discs in album
    - date (str, optional): Release date (YYYY or YYYY-MM-DD)
    - musicbrainz_id (str, optional): MusicBrainz identifier
    """
    uri: str
    name: str
    artists: frozenset[Artist]
    num_tracks: int
    num_discs: int
    date: str
    musicbrainz_id: str

Usage example:

album = Album(
    uri="local:album:abbey-road",
    name="Abbey Road",
    artists=frozenset([artist]),
    num_tracks=17,
    date="1969-09-26",
    musicbrainz_id="7fb57fde-258e-4430-b23c-14dac0f8bb0b"
)

Track Metadata

Complete track information including audio metadata, relationships, and technical details.

class Track(ValidatedImmutableObject):
    """
    Track metadata model.
    
    Parameters:
    - uri (str): Track URI
    - name (str): Track name
    - artists (frozenset[Artist], optional): Track artists
    - album (Album, optional): Track album
    - composers (frozenset[Artist], optional): Track composers
    - performers (frozenset[Artist], optional): Track performers
    - genre (str, optional): Track genre
    - track_no (int, optional): Track number in album
    - disc_no (int, optional): Disc number in album
    - date (str, optional): Track release date (YYYY or YYYY-MM-DD)
    - length (int, optional): Track length in milliseconds
    - bitrate (int, optional): Bitrate in kbit/s
    - comment (str, optional): Track comment
    - musicbrainz_id (str, optional): MusicBrainz identifier
    - last_modified (int, optional): Last modification time (Unix epoch ms)
    """
    uri: str
    name: str
    artists: frozenset[Artist]
    album: Album
    composers: frozenset[Artist]
    performers: frozenset[Artist]
    genre: str
    track_no: int
    disc_no: int
    date: str
    length: int
    bitrate: int
    comment: str
    musicbrainz_id: str
    last_modified: int

Usage example:

track = Track(
    uri="local:track:come-together.mp3",
    name="Come Together",
    artists=frozenset([artist]),
    album=album,
    track_no=1,
    length=259000,  # 4:19 in milliseconds
    bitrate=320
)

Tracklist Tracks

Tracklist-specific track wrappers that allow the same track to appear multiple times with unique identifiers.

class TlTrack(ValidatedImmutableObject):
    """
    A tracklist track wrapping a regular track with a tracklist ID.
    
    Parameters:
    - tlid (int): Tracklist ID
    - track (Track): The track object
    """
    tlid: int
    track: Track
    
    def __init__(self, *args, **kwargs):
        """Supports positional arguments: TlTrack(tlid, track)"""
        ...
    
    def __iter__(self):
        """Supports iteration: tlid, track = tl_track"""
        ...

Usage example:

tl_track = TlTrack(tlid=1, track=track)
# Or using positional arguments
tl_track = TlTrack(1, track)
# Or using iteration
tlid, track_obj = tl_track

Playlist Metadata

Playlist information including tracks, modification times, and metadata.

class Playlist(ValidatedImmutableObject):
    """
    Playlist metadata model.
    
    Parameters:
    - uri (str): Playlist URI
    - name (str): Playlist name
    - tracks (tuple[Track]): Playlist tracks
    - last_modified (int, optional): Modification time (Unix epoch ms)
    """
    uri: str
    name: str
    tracks: tuple[Track]
    last_modified: int
    
    @property
    def length(self) -> int:
        """The number of tracks in the playlist."""
        ...

Usage example:

playlist = Playlist(
    uri="m3u:playlist:favorites.m3u",
    name="My Favorites",
    tracks=(track1, track2, track3),
    last_modified=1640995200000
)
print(f"Playlist has {playlist.length} tracks")

Search Results

Container for search results across different media types with organized results by category.

class SearchResult(ValidatedImmutableObject):
    """
    Search result container organizing matches by type.
    
    Parameters:
    - uri (str, optional): Search result URI
    - tracks (tuple[Track], optional): Matching tracks
    - artists (tuple[Artist], optional): Matching artists  
    - albums (tuple[Album], optional): Matching albums
    """
    uri: str
    tracks: tuple[Track]
    artists: tuple[Artist]
    albums: tuple[Album]

Usage example:

search_result = SearchResult(
    uri="spotify:search:beatles",
    tracks=(track1, track2),
    artists=(artist,),
    albums=(album1, album2)
)

Image Metadata

Image information for album art, artist photos, and other visual content.

class Image(ValidatedImmutableObject):
    """
    Image metadata model.
    
    Parameters:
    - uri (str): Image URI
    - width (int, optional): Image width in pixels
    - height (int, optional): Image height in pixels
    """
    uri: str
    width: int
    height: int

Usage example:

image = Image(
    uri="https://example.com/album-art.jpg",
    width=600,
    height=600
)

JSON Serialization

Utilities for converting models to and from JSON representations for storage and transmission.

class ModelJSONEncoder(json.JSONEncoder):
    """JSON encoder for Mopidy model objects."""
    def default(self, obj): ...

def model_json_decoder(dct):
    """
    JSON decoder for reconstructing Mopidy model objects.
    
    Parameters:
    - dct (dict): Dictionary from JSON parsing
    
    Returns:
    - Model object or original dict
    """
    ...

Usage example:

import json

# Serialize models to JSON
encoder = ModelJSONEncoder()
json_data = encoder.encode(track)

# Deserialize models from JSON
track_obj = json.loads(json_data, object_hook=model_json_decoder)

Types

# Type definitions used throughout models
Uri = str
UriScheme = str
QueryValue = Union[str, int]
Query = Dict[str, List[QueryValue]]

docs

audio-system.md

backend-system.md

configuration.md

core-controllers.md

extension-system.md

index.md

models.md

tile.json