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 NAMESPACES variable.

DidlObject

class soco.data_structures.DidlObject(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlMetaClass

Abstract base class for all DIDL-Lite items.

You should not need to instantiate this.

item_class

str

The DIDL Lite class for this object

tag

str

The XML element tag name used for this instance

_translation

dict

A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Overridden and extended by subclasses.

__init__(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Construct and initialize a DidlObject.

Parameters:
  • title (str) – The title for the item
  • parent_id (str) – The parent ID for the item
  • item_id (str) – The ID for the item
  • restricted (bool) – Whether the item can be modified
  • resources (list) – A list of resources for this object
  • desc (str) – A didl descriptor, default RINCON_AssociatedZPUDN. This is not the same as “description”! It is used for identifying the relevant music service
  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class
__eq__(playable_item)

Compare with another playable_item.

Returns:True if items are equal, else False
Return type:(bool)
__repr__()

Return the repr value for the item.

The repr is of 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)

Compare with another playable_item.

Returns:True if items are equal, else False
Return type:(bool)
__init__(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Construct and initialize a DidlObject.

Parameters:
  • title (str) – The title for the item
  • parent_id (str) – The parent ID for the item
  • item_id (str) – The ID for the item
  • restricted (bool) – Whether the item can be modified
  • resources (list) – A list of resources for this object
  • desc (str) – A didl descriptor, default RINCON_AssociatedZPUDN. This is not the same as “description”! It is used for identifying the relevant music service
  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class
__ne__(playable_item)

Compare with another playable_item.

Returns:True if items are unequal, else False
Return type:(bool)
__repr__()

Return the repr value for the item.

The repr is of 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.

classmethod from_dict(content)

Create an instance from a dict.

An alternative constructor. Equivalent to DidlObject(**content).

Arg:
content (dict): Dict containing metadata information.Required and valid arguments are the same as for the __init__ method.
classmethod from_element(element)

Create an instance of this class from an ElementTree xml Element.

An alternative constructor. The element must be a DIDL-Lite <item> or <container> element, and must be properly namespaced.

Arg:
xml (Element): An xml.etree.ElementTree.Element object.
to_dict()

Return the dict representation of the instance.

to_element(include_namespaces=False)

Return an ElementTree Element representing this instance.

Arg:
include_namespaces (bool, optional): If True, include xml
namespace attributes on the root element
Returns:An ElementTree Element
<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>

DidlContainer

class soco.data_structures.DidlContainer(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlObject

Class that represents a music library container.

DidlItem

class soco.data_structures.DidlItem(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlObject

A basic content directory item.

DidlMusicTrack

class soco.data_structures.DidlMusicTrack(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlAudioItem

Class that represents a music library track.

DidlMusicAlbum

class soco.data_structures.DidlMusicAlbum(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlAlbum

Class that represents a music library album.

DidlMusicArtist

class soco.data_structures.DidlMusicArtist(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlPerson

Class that represents a music library artist.

DidlMusicGenre

class soco.data_structures.DidlMusicGenre(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlGenre

Class that represents a music genre.

DidlAlbumList

class soco.data_structures.DidlAlbumList(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlContainer

Class that represents a music library album list.

DidlComposer

class soco.data_structures.DidlComposer(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlPerson

Class that represents a music library composer.

DidlPlaylistContainer

class soco.data_structures.DidlPlaylistContainer(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlContainer

Class that represents a music library play list.

DidlAudioBroadcast

class soco.data_structures.DidlAudioBroadcast(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlAudioItem

Class that represents an audio broadcast.

DidlContainer

class soco.data_structures.DidlContainer(title, parent_id, item_id, restricted=True, resources=None, desc=u'RINCON_AssociatedZPUDN', **kwargs)

Bases: soco.data_structures.DidlObject

Class that represents a music library container.