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