The `data_structures` sub module¶

Introduction¶

The majority of the data structures in this module are used to represent the metadata for music items, such as music tracks, genres and playlists. The data structure classes are documented in the sections below and the rest of this section contains a more thorough introduction.

Many music related items have a lot of metadata in common. For example, a music track and an album may both have artist and title metadata. It is possible therefore to derive a hierarchy of items, and to implement them as a class structure. The hierarchy which Sonos has adopted is represented by the DIDL Lite xml schema (DIDL stands for ‘Digital Item Description Language’. For more details, see the UPnP specifications (PDF).

In the data_structures module, each class represents a particular DIDL-Lite object and is illustrated in 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 subclasses of the abstract Didl Object item class. You should never need to instantiate this directly. The subclasses are divided into Containers and Items. In general, Containers are things, like playlists, which are intended to contain other items.

At the bottom of the class hierarchy are 10 types of DIDL items. On each of these classes, relevant metadata items are available as attributes (though they may be implemented as properties). Each has a title, a URI, an item id and a UPnP class. Some have other attributes. For example, DidlMusicTrack and DidlMusicAlbum have some extra fields such as album, album_art_uri and creator.

One of the more important attributes which each class has is didl_metadata. It is used to produce the metadata that is sent to the Sonos® units in the form of XML. This metadata is created in an almost identical way for each class, which is why it is implemented in DidlObject. It uses the URI, the UPnP class and the title that the items are instantiated with, along with the two class variables parent_id and _translation.

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_didl_object(xml)¶: Return the DIDL object that corresponds to xml. The class is identified by getting the UPNP class making a lookup in the DIDL_CLASS_TO_CLASS module variable dictionary.

DidlObject¶

class soco.data_structures.DidlObject(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlMetaClass

Abstract base class for all content directory objects

You should not need to instantiate this

Variables:

item_class – According to the spec, the DIDL Lite class for DIDL items is object, 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'),
    'creator': ('dc', 'creator'),
}
```

__init__(uri, title, parent_id, item_id, **kwargs)¶

Initialize the DidlObject from parameter arguments.

Parameters:	uri – The URI for the item title – The title for the item parent_id – The parent ID for the item item_id – The ID 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.

__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.

__eq__(playable_item): Return the equals comparison result to another playable_item.

__init__(uri, title, parent_id, item_id, **kwargs)

Initialize the DidlObject from parameter arguments.

Parameters:	uri – The URI for the item title – The title for the item parent_id – The parent ID for the item item_id – The ID 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.

__ne__(playable_item)¶: Return the not 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.

creator¶: Get and set the creator as an unicode object.

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)¶

An alternative constructor to create instance 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)¶

An alternative constructor to create an instance of this class 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_id¶: Return the id.

parent_id¶: Get and set the parent ID.

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.

DidlContainer¶

class soco.data_structures.DidlContainer(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlObject

Class that represents a music library container.

Variables:	item_class – The item_class for the DidlContainer is ‘object.container’ _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlContainer from XML is inherited from `DidlObject`.

DidlItem¶

class soco.data_structures.DidlItem(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlObject

A basic content directory item

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

radio_show¶: Get and set the radio show metadata as an unicode object.

stream_content¶: Get and set the stream content URI as an unicode object.

DidlMusicTrack¶

class soco.data_structures.DidlMusicTrack(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlAudioItem

Class that represents a music track.

Variables:

_translation –

The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlMusicTrack 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')
}

album¶: Get and set the album as an unicode object.

original_track_number¶: Get and set the original track number as an int.

DidlMusicAlbum¶

class soco.data_structures.DidlMusicAlbum(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlAlbum

Class that represents a music library album.

Variables:	item_class – The item_class for DidlMusicTrack is ‘object.container.album.musicAlbum’ _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlAlbum from XML. The value is shown below # key: (ns, tag) _translation = { 'title': ('dc', 'title'), 'creator': ('dc', 'creator'), 'album_art_uri': ('upnp', 'albumArtURI'), 'uri': ('', 'res') }

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

DidlMusicArtist¶

class soco.data_structures.DidlMusicArtist(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlPerson

Class that represents an artist.

Variables:	item_class – The item_class for DidlMusicArtist is ‘object.container.person.musicArtist’ _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlMusicArtist from XML is inherited from `DidlObject`.

DidlMusicGenre¶

class soco.data_structures.DidlMusicGenre(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlGenre

Class that represents a music genre.

Variables:	item_class – The item class for the DidlGenre is ‘object.container.genre.musicGenre’ _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlGenre from XML is inherited from `DidlObject`.

DidlAlbumList¶

class soco.data_structures.DidlAlbumList(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlContainer

Class that represents an album list.

Variables:	item_class – The item_class for DidlAlbumList is ‘object.container.albumlist’ _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlAlbumList from XML is inherited from `DidlObject`.

DidlComposer¶

class soco.data_structures.DidlComposer(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlPerson

Class that represents a composer.

Variables:	item_class – The item_class for DidlComposer is ‘object.container.person.composer’ _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlComposer from XML is inherited from `DidlObject`.

DidlPlaylistContainer¶

class soco.data_structures.DidlPlaylistContainer(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlContainer

Class that represents a play list.

Variables:	item_class – The item_class for the DidlPlaylistContainer is ‘object.container.playlistContainer’ _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlPlaylistContainer from XML is inherited from `DidlObject`.

DidlAudioBroadcast¶

class soco.data_structures.DidlAudioBroadcast(uri, title, parent_id, item_id, **kwargs)¶

Bases: soco.data_structures.DidlAudioItem

Class that represents an audio broadcast.

DidlContainer¶

class soco.data_structures.DidlContainer(uri, title, parent_id, item_id, **kwargs)

Bases: soco.data_structures.DidlObject

Class that represents a music library container.

Variables:	item_class – The item_class for the DidlContainer is ‘object.container’ _translation – The dictionary-key-to-xml-tag-and-namespace- translation used when instantiating a DidlContainer from XML is inherited from `DidlObject`.

The data_structures sub module¶

Introduction¶

Functions¶

DidlObject¶

DidlContainer¶

DidlItem¶

DidlMusicTrack¶

DidlMusicAlbum¶

DidlMusicArtist¶

DidlMusicGenre¶

DidlAlbumList¶

DidlComposer¶

DidlPlaylistContainer¶

DidlAudioBroadcast¶

DidlContainer¶

The `data_structures` sub module¶