Data models

These immutable data models are used for all data transfer within the Mopidy backends and between the backends and the MPD frontend. All fields are optional and immutable. In other words, they can only be set through the class constructor during instance creation.

If you want to modify a model, use the copy() method. It accepts keyword arguments for the parts of the model you want to change, and copies the rest of the data from the model you call it on. Example:

>>> from mopidy.models import Track
>>> track1 = Track(name='Christmas Carol', length=171)
>>> track1
Track(artists=[], length=171, name='Christmas Carol')
>>> track2 = track1.copy(length=37)
>>> track2
Track(artists=[], length=37, name='Christmas Carol')
>>> track1
Track(artists=[], length=171, name='Christmas Carol')

Data model relations

digraph model_relations {
Playlist -> Track [ label="has 0..n" ]
Track -> Album [ label="has 0..1" ]
Track -> Artist [ label="has 0..n" ]
Album -> Artist [ label="has 0..n" ]

SearchResult -> Artist [ label="has 0..n" ]
SearchResult -> Album [ label="has 0..n" ]
SearchResult -> Track [ label="has 0..n" ]
}

Data model API

class mopidy.models.Album(*args, **kwargs)[source]
Parameters:
  • uri (string) – album URI
  • name (string) – album name
  • artists (list of Artist) – album artists
  • num_tracks (integer or None if unknown) – number of tracks in album
  • num_discs (integer or None if unknown) – number of discs in album
  • date (string) – album release date (YYYY or YYYY-MM-DD)
  • musicbrainz_id (string) – MusicBrainz ID
  • images (list of strings) – album image URIs
artists = frozenset([])

A set of album artists. Read-only.

date = None

The album release date. Read-only.

images = frozenset([])

The album image URIs. Read-only.

musicbrainz_id = None

The MusicBrainz ID of the album. Read-only.

name = None

The album name. Read-only.

num_discs = None

The number of discs in the album. Read-only.

num_tracks = None

The number of tracks in the album. Read-only.

uri = None

The album URI. Read-only.

class mopidy.models.Artist(*args, **kwargs)[source]
Parameters:
  • uri (string) – artist URI
  • name (string) – artist name
  • musicbrainz_id (string) – MusicBrainz ID
musicbrainz_id = None

The MusicBrainz ID of the artist. Read-only.

name = None

The artist name. Read-only.

uri = None

The artist URI. Read-only.

class mopidy.models.ImmutableObject(*args, **kwargs)[source]

Superclass for immutable objects whose fields can only be modified via the constructor.

Parameters:kwargs (any) – kwargs to set as fields on the object
copy(**values)[source]

Copy the model with field updated to new value.

Examples:

# Returns a track with a new name
Track(name='foo').copy(name='bar')
# Return an album with a new number of tracks
Album(num_tracks=2).copy(num_tracks=5)
Parameters:values (dict) – the model fields to modify
Return type:new instance of the model being copied
class mopidy.models.ModelJSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None)[source]

Automatically serialize Mopidy models to JSON.

Usage:

>>> import json
>>> json.dumps({'a_track': Track(name='name')}, cls=ModelJSONEncoder)
'{"a_track": {"__model__": "Track", "name": "name"}}'
class mopidy.models.Playlist(*args, **kwargs)[source]
Parameters:
  • uri (string) – playlist URI
  • name (string) – playlist name
  • tracks (list of Track elements) – playlist’s tracks
  • last_modified (int) – playlist’s modification time in milliseconds since Unix epoch
last_modified = None

The playlist modification time in milliseconds since Unix epoch. Read-only.

Integer, or None if unknown.

length

The number of tracks in the playlist. Read-only.

name = None

The playlist name. Read-only.

tracks = ()

The playlist’s tracks. Read-only.

uri = None

The playlist URI. Read-only.

class mopidy.models.Ref(*args, **kwargs)[source]

Model to represent URI references with a human friendly name and type attached. This is intended for use a lightweight object “free” of metadata that can be passed around instead of using full blown models.

Parameters:
  • uri (string) – object URI
  • name (string) – object name
  • type – object type
ALBUM = u'album'

Constant used for comparison with the type field.

ARTIST = u'artist'

Constant used for comparison with the type field.

DIRECTORY = u'directory'

Constant used for comparison with the type field.

PLAYLIST = u'playlist'

Constant used for comparison with the type field.

TRACK = u'track'

Constant used for comparison with the type field.

classmethod album(**kwargs)[source]

Create a Ref with type ALBUM.

classmethod artist(**kwargs)[source]

Create a Ref with type ARTIST.

classmethod directory(**kwargs)[source]

Create a Ref with type DIRECTORY.

name = None

The object name. Read-only.

classmethod playlist(**kwargs)[source]

Create a Ref with type PLAYLIST.

classmethod track(**kwargs)[source]

Create a Ref with type TRACK.

type = None

The object type, e.g. “artist”, “album”, “track”, “playlist”, “directory”. Read-only.

uri = None

The object URI. Read-only.

class mopidy.models.SearchResult(*args, **kwargs)[source]
Parameters:
  • uri (string) – search result URI
  • tracks (list of Track elements) – matching tracks
  • artists (list of Artist elements) – matching artists
  • albums (list of Album elements) – matching albums
class mopidy.models.TlTrack(*args, **kwargs)[source]

A tracklist track. Wraps a regular track and it’s tracklist ID.

The use of TlTrack allows the same track to appear multiple times in the tracklist.

This class also accepts it’s parameters as positional arguments. Both arguments must be provided, and they must appear in the order they are listed here.

This class also supports iteration, so your extract its values like this:

(tlid, track) = tl_track
Parameters:
  • tlid (int) – tracklist ID
  • track (Track) – the track
tlid = None

The tracklist ID. Read-only.

track = None

The track. Read-only.

class mopidy.models.Track(*args, **kwargs)[source]
Parameters:
  • uri (string) – track URI
  • name (string) – track name
  • artists (list of Artist) – track artists
  • album (Album) – track album
  • composers (string) – track composers
  • performers (string) – track performers
  • genre (string) – track genre
  • track_no (integer or None if unknown) – track number in album
  • disc_no (integer or None if unknown) – disc number in album
  • date (string) – track release date (YYYY or YYYY-MM-DD)
  • length (integer) – track length in milliseconds
  • bitrate (integer) – bitrate in kbit/s
  • comment (string) – track comment
  • musicbrainz_id (string) – MusicBrainz ID
  • last_modified (integer or None if unknown) – Represents last modification time
album = None

The track Album. Read-only.

artists = frozenset([])

A set of track artists. Read-only.

bitrate = None

The track’s bitrate in kbit/s. Read-only.

comment = None

The track comment. Read-only.

composers = frozenset([])

A set of track composers. Read-only.

date = None

The track release date. Read-only.

disc_no = None

The disc number in the album. Read-only.

genre = None

The track genre. Read-only.

last_modified = None

Integer representing when the track was last modified, exact meaning depends on source of track. For local files this is the mtime, for other backends it could be a timestamp or simply a version counter.

length = None

The track length in milliseconds. Read-only.

musicbrainz_id = None

The MusicBrainz ID of the track. Read-only.

name = None

The track name. Read-only.

performers = frozenset([])

A set of track performers`. Read-only.

track_no = None

The track number in the album. Read-only.

uri = None

The track URI. Read-only.

mopidy.models.model_json_decoder(dct)[source]

Automatically deserialize Mopidy models from JSON.

Usage:

>>> import json
>>> json.loads(
...     '{"a_track": {"__model__": "Track", "name": "name"}}',
...     object_hook=model_json_decoder)
{u'a_track': Track(artists=[], name=u'name')}