The data_structures sub module

Introduction

The data structures are used to represent playable items like e.g. a music track or playlist. The data structure classes are documented in the sections below and the rest of this section contains a more thorough introduction.

To expand a bit, the data_structures sub-module consist of a hierarchy of classes that represent different music information items. This could be a “real” item such as a music library track, album or genre or an abstract item such as a music library item.

The main advantages of using classes as apposed to e.g. dicts to contain the information are:

  • They are easy to identify
  • It is possibly to define and agree on certain abilities such as what is the criteria for two tracks being equal
  • Certain functionality for these information object, such as producing the XML that is needed for the UPnP communication can be attached to the elements themselves.

Many of the items have a lot in common and therefore has shared functionality. This has been implemented by means of inheritance, in such a way that common functionality is always pulled up the inheritance hierarchy to the highest point that have this functionality in common. The hierarchy is illustrated in figure the figure below. The black lines are the lines of inheritance, going from the top down.

Inheritance diagram of soco.data_structures

All data structures are music information items. Three classes inherit from this top level class; the queue item, the music library item and the music service item

There are 8 types of music library items, represented by the 8 classes that inherit from it. From these classes all information items are available as named properties. All of these items contains a title, a URI and a UPnP class, so these items are defined in the MusicLibraryItem class and inherited by them all. For most items the ID can be extracted from the URI in the same way, so therefore it is defined in MusicLibraryItem.item_id and the few classes (MLTrack, MLPlaylist) that extract the ID differently from the URI then overrides this property. Besides the information items that they all share, MLTrack and MLAlbum define some extra fields such as album, album_art_uri and creator.

One of the more important attributes is didl_metadata. It is used to produce the metadata that is sent to the Sonos® units. This metadata is created in an almost identical way, which is the reason that it is implemented in MusicLibraryItem. It uses the URI (through the ID), the UPnP class and the title that the items are instantiated with and the two class variables parent_id and _translation. parent_id must be over written in each of the sub classes, whereas that is only necessary for _translation if the information fields are different from the default.

Functions

soco.data_structures.ns_tag(ns_id, tag)

Return a namespace/tag item. The ns_id is translated to a full name space via the NS module variable.

soco.data_structures.get_ml_item(xml)

Return the music library item that corresponds to xml. The class is identified by getting the parentID and making a lookup in the PARENT_ID_TO_CLASS module variable dictionary.

MusicInfoItem

class soco.data_structures.MusicInfoItem

Bases: object

Abstract class for all data structure classes

__init__()

Initialize the content as an empty dict.

__eq__(playable_item)

Return the equals comparison result to another playable_item.

__repr__()

Return the repr value for the item.

The repr is on the form:

<class_name 'middle_part[0:40]' at id_in_hex>

where middle_part is either the title item in content, if it is set, or str(content). The output is also cleared of non-ascii characters.

__str__()

Return the str value for the item:

<class_name 'middle_part[0:40]' at id_in_hex>

where middle_part is either the title item in content, if it is set, or str(content). The output is also cleared of non-ascii characters.

MusicLibraryItem

class soco.data_structures.MusicLibraryItem(uri, title, item_class, **kwargs)

Bases: soco.data_structures.MusicInfoItem

Abstract class for a queueable item from the music library.

Variables:
  • parent_id – The parent ID for the music library item is None, since it is a abstract class and it should be overwritten in the sub classes
  • _translation

    The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MusicLibraryItems from XML. The default value is shown below. This default value applies to most sub classes and the rest should overwrite it.

    # key: (ns, tag)
    _translation = {
        'title': ('dc', 'title'),
        'uri': ('', 'res'),
        'item_class': ('upnp', 'class')
    }
    
__init__(uri, title, item_class, **kwargs)

Initialize the MusicLibraryItem from parameter arguments.

Parameters:
  • uri – The URI for the item
  • title – The title for the item
  • item_class – The UPnP class for the item
  • **kwargs – Extra information items to form the music library item from. Valid keys are album, album_art_uri, creator and original_track_number. original_track_number is an int, all other values are unicode objects.
didl_metadata

Produce the DIDL metadata XML.

This method uses the item_id attribute (and via that the uri attribute), the item_class attribute and the title attribute. The metadata will be on the form:

<DIDL-Lite ..NS_INFO..>
  <item id="...self.item_id..."
    parentID="...cls.parent_id..." restricted="true">
    <dc:title>...self.title...</dc:title>
    <upnp:class>...self.item_class...</upnp:class>
    <desc id="cdudn"
      nameSpace="urn:schemas-rinconnetworks-com:metadata-1-0/">
      RINCON_AssociatedZPUDN
    </desc>
  </item>
</DIDL-Lite>
classmethod from_dict(content)

Return an instance of this class, created from a dict with parameters.

Parameters:content – Dict with information for the music library item. Required and valid arguments are the same as for the __init__ method.
classmethod from_xml(xml)

Return an instance of this class, created from xml.

Parameters:xml – An xml.etree.ElementTree.Element object. The top element usually is a DIDL-LITE item (NS[‘’]) element. Inside the item element should be the (namespace, tag_name) elements in the dictionary-key-to-xml-tag-and-namespace-translation described in the class docstring.
item_class

Get and set the UPnP object class as an unicode object.

item_id

Return the id.

The id is extracted as the part of the URI after the first # character. For the few music library types where that is not correct, this method should be overwritten.

title

Get and set the title as an unicode object.

to_dict

Get the dict representation of the instance.

uri

Get and set the URI as an unicode object.

MLTrack

class soco.data_structures.MLTrack(uri, title, item_class=u'object.item.audioItem.musicTrack', **kwargs)

Bases: soco.data_structures.MusicLibraryItem

Class that represents a music library track.

Variables:
  • parent_id – The parent ID for the MLTrack is ‘A:TRACKS’
  • _translation

    The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MLTrack from XML. The value is shown below

    # key: (ns, tag)
    _translation = {
        'title': ('dc', 'title'),
        'creator': ('dc', 'creator'),
        'album': ('upnp', 'album'),
        'album_art_uri': ('upnp', 'albumArtURI'),
        'uri': ('', 'res'),
        'original_track_number': ('upnp', 'originalTrackNumber'),
        'item_class': ('upnp', 'class')
    }
    
__init__(uri, title, item_class=u'object.item.audioItem.musicTrack', **kwargs)

Instantiate the MLTrack item by passing the arguments to the super class MusicLibraryItem.__init__().

Parameters:
  • uri – The URI for the track
  • title – The title of the track
  • item_class – The UPnP class for the track. The default value is: object.item.audioItem.musicTrack
  • **kwargs – Optional extra information items, valid keys are: album, album_art_uri, creator, original_track_number. original_track_number is an int. All other values are unicode objects.
album

Get and set the album as an unicode object.

album_art_uri

Get and set the album art URI as an unicode object.

creator

Get and set the creator as an unicode object.

item_id

Return the id.

original_track_number

Get and set the original track number as an int.

MLAlbum

class soco.data_structures.MLAlbum(uri, title, item_class=u'object.container.album.musicAlbum', **kwargs)

Bases: soco.data_structures.MusicLibraryItem

Class that represents a music library album.

Variables:
  • parent_id – The parent ID for the MLTrack is ‘A:ALBUM’
  • _translation

    The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MLAlbum from XML. The value is shown below

    # key: (ns, tag)
    _translation = {
        'title': ('dc', 'title'),
        'creator': ('dc', 'creator'),
        'album_art_uri': ('upnp', 'albumArtURI'),
        'uri': ('', 'res'),
        'item_class': ('upnp', 'class')
    }
    
__init__(uri, title, item_class=u'object.container.album.musicAlbum', **kwargs)

Instantiate the MLAlbum item by passing the arguments to the super class MusicLibraryItem.__init__().

Parameters:
  • uri – The URI for the alum
  • title – The title of the album
  • item_class – The UPnP class for the album. The default value is: object.container.album.musicAlbum
  • **kwargs – Optional extra information items, valid keys are: album_art_uri and creator. All value should be unicode objects.
album_art_uri

Get and set the album art URI as an unicode object.

creator

Get and set the creator as an unicode object.

MLArtist

class soco.data_structures.MLArtist(uri, title, item_class=u'object.container.person.musicArtist')

Bases: soco.data_structures.MusicLibraryItem

Class that represents a music library artist.

Variables:
  • parent_id – The parent ID for the MLArtist is ‘A:ARTIST’
  • _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MLArtist from XML is inherited from MusicLibraryItem.
__init__(uri, title, item_class=u'object.container.person.musicArtist')

Instantiate the MLArtist item by passing the arguments to the super class MusicLibraryItem.__init__().

Parameters:
  • uri – The URI for the artist
  • title – The title of the artist
  • item_class – The UPnP class for the artist. The default value is: object.container.person.musicArtist

MLAlbumArtist

class soco.data_structures.MLAlbumArtist(uri, title, item_class=u'object.container.person.musicArtist')

Bases: soco.data_structures.MusicLibraryItem

Class that represents a music library album artist.

Variables:
  • parent_id – The parent ID for the MLAlbumArtist is ‘A:ALBUMARTIST’
  • _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MLAlbumArtist from XML is inherited from MusicLibraryItem.
__init__(uri, title, item_class=u'object.container.person.musicArtist')

Instantiate the MLAlbumArtist item by passing the arguments to the super class MusicLibraryItem.__init__().

Parameters:
  • uri – The URI for the alum artist
  • title – The title of the album artist
  • item_class – The UPnP class for the album artist. The default value is: object.container.person.musicArtist

MLGenre

class soco.data_structures.MLGenre(uri, title, item_class=u'object.container.genre.musicGenre')

Bases: soco.data_structures.MusicLibraryItem

Class that represents a music library genre.

Variables:
  • parent_id – The parent ID for the MLGenre is ‘A:GENRE’
  • _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MLGenre from XML is inherited from MusicLibraryItem.
__init__(uri, title, item_class=u'object.container.genre.musicGenre')

Instantiate the MLGenre item by passing the arguments to the super class MusicLibraryItem.__init__().

Parameters:
  • uri – The URI for the genre
  • title – The title of the genre
  • item_class – The UPnP class for the genre. The default value is: object.container.genre.musicGenre

MLComposer

class soco.data_structures.MLComposer(uri, title, item_class=u'object.container.person.composer')

Bases: soco.data_structures.MusicLibraryItem

Class that represents a music library composer.

Variables:
  • parent_id – The parent ID for the MLComposer is ‘A:COMPOSER’
  • _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MLComposer from XML is inherited from MusicLibraryItem.
__init__(uri, title, item_class=u'object.container.person.composer')

Instantiate the MLComposer item by passing the arguments to the super class MusicLibraryItem.__init__().

Parameters:
  • uri – The URI for the composer
  • title – The title of the composer
  • item_class – The UPnP class for the composer. The default value is: object.container.person.composer

MLPlaylist

class soco.data_structures.MLPlaylist(uri, title, item_class=u'object.container.playlistContainer')

Bases: soco.data_structures.MusicLibraryItem

Class that represents a music library play list.

Variables:
  • parent_id – The parent ID for the MLPlaylist is ‘A:PLAYLIST’
  • _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MLPlaylist from XML is inherited from MusicLibraryItem.
__init__(uri, title, item_class=u'object.container.playlistContainer')

Instantiate the MLPlaylist item by passing the arguments to the super class MusicLibraryItem.__init__().

Parameters:
  • uri – The URI for the playlist
  • title – The title of the playlist
  • item_class – The UPnP class for the playlist. The default value is: object.container.playlistContainer
item_id

Returns the id.

MLShare

class soco.data_structures.MLShare(uri, title, item_class=u'object.container')

Bases: soco.data_structures.MusicLibraryItem

Class that represents a music library share.

Variables:
  • parent_id – The parent ID for the MLShare is ‘S:’
  • _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a MLShare from XML is inherited from MusicLibraryItem.
__init__(uri, title, item_class=u'object.container')

Instantiate the MLShare item by passing the arguments to the super class MusicLibraryItem.__init__().

Parameters:
  • uri – The URI for the share
  • title – The title of the share
  • item_class – The UPnP class for the share. The default value is: object.container

QueueItem

class soco.data_structures.QueueItem(uri, title, item_class=u'object.item.audioItem.musicTrack', **kwargs)

Bases: soco.data_structures.MusicInfoItem

Class that represents a queue item.

Variables:
  • parent_id – The parent ID for the QueueItem is ‘Q:0’
  • _translation

    The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a QueueItem from XML. The value is shown below

    # key: (ns, tag)
    _translation = {
        'title': ('dc', 'title'),
        'creator': ('dc', 'creator'),
        'album': ('upnp', 'album'),
        'album_art_uri': ('upnp', 'albumArtURI'),
        'uri': ('', 'res'),
        'original_track_number': ('upnp', 'originalTrackNumber'),
        'item_class': ('upnp', 'class')
    }
    
__init__(uri, title, item_class=u'object.item.audioItem.musicTrack', **kwargs)

Instantiate the QueueItem by passing the arguments to the super class MusicInfoItem.__init__().

Parameters:
  • uri – The URI for the queue item
  • title – The title of the queue item
  • item_class – The UPnP class for the queue item. The default value is: object.item.audioItem.musicTrack
  • **kwargs – Optional extra information items, valid keys are: album, album_art_uri, creator, original_track_number. original_track_number is an int. All other values are unicode objects.
album

Get and set the album as an unicode object.

album_art_uri

Get and set the album art URI as an unicode object.

creator

Get and set the creator as an unicode object.

didl_metadata

Produce the DIDL metadata XML.

classmethod from_dict(content)

Return an instance of this class, created from a dict with parameters.

Parameters:content – Dict with information for the music library item. Required and valid arguments are the same as for the __init__ method.
classmethod from_xml(xml)

Return an instance of this class, created from xml.

Parameters:xml – An xml.etree.ElementTree.Element object. The top element usually is a DIDL-LITE item (NS[‘’]) element. Inside the item element should be the (namespace, tag_name) elements in the dictionary-key-to-xml-tag-and-namespace-translation described in the class docstring.
item_class

Get and set the UPnP object class as an unicode object.

original_track_number

Get and set the original track number as an int.

title

Get and set the title as an unicode object.

to_dict

Get the dict representation of the instance.

uri

Get and set the URI as an unicode object.