soco.services module

Classes representing Sonos UPnP services.

>>> import soco
>>> device = soco.SoCo('192.168.1.102')
>>> print(RenderingControl(device).GetMute([('InstanceID', 0),
...     ('Channel', 'Master')]))
{'CurrentMute': '0'}
>>> r = ContentDirectory(device).Browse([
...    ('ObjectID', 'Q:0'),
...    ('BrowseFlag', 'BrowseDirectChildren'),
...    ('Filter', '*'),
...    ('StartingIndex', '0'),
...    ('RequestedCount', '100'),
...    ('SortCriteria', '')
...    ])
>>> print(r['Result'])
<?xml version="1.0" ?><DIDL-Lite xmlns="urn:schemas-upnp-org:metadata ...
>>> for action, in_args, out_args in AlarmClock(device).iter_actions():
...    print(action, in_args, out_args)
...
SetFormat [Argument(name='DesiredTimeFormat', vartype='string'), Argument(
name='DesiredDateFormat', vartype='string')] []
GetFormat [] [Argument(name='CurrentTimeFormat', vartype='string'),
Argument(name='CurrentDateFormat', vartype='string')] ...
class soco.services.Action[source]

A UPnP Action and its arguments.

Create new instance of ActionBase(name, in_args, out_args)

class soco.services.Argument[source]

A UPnP Argument and its type.

Create new instance of ArgumentBase(name, vartype)

class soco.services.Vartype[source]

An argument type with default value and range.

Create new instance of VartypeBase(datatype, default, list, range)

class soco.services.Service(soco)[source]

A class representing a UPnP service.

This is the base class for all Sonos Service classes. This class has a dynamic method dispatcher. Calls to methods which are not explicitly defined here are dispatched automatically to the service action with the same name.

Parameters

soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent

soco = None

The SoCo instance to which UPnP Actions are sent

Type

SoCo

service_type = None

The UPnP service type.

Type

str

version = None

The UPnP service version.

Type

str

base_url = None

The base URL for sending UPnP Actions.

Type

str

control_url = None

The UPnP Control URL.

Type

str

scpd_url = None

The service control protocol description URL.

Type

str

event_subscription_url = None

The service eventing subscription URL.

Type

str

cache = None

A cache for storing the result of network calls. By default, this is a TimedCache with a default timeout=0.

static wrap_arguments(args=None)[source]

Wrap a list of tuples in xml ready to pass into a SOAP request.

Parameters

args (list) – a list of (name, value) tuples specifying the name of each argument and its value, eg [('InstanceID', 0), ('Speed', 1)]. The value can be a string or something with a string representation. The arguments are escaped and wrapped in <name> and <value> tags.

Example

>>> from soco import SoCo
>>> device = SoCo('192.168.1.101')
>>> s = Service(device)
>>> print(s.wrap_arguments([('InstanceID', 0), ('Speed', 1)]))
<InstanceID>0</InstanceID><Speed>1</Speed>'
static unwrap_arguments(xml_response)[source]

Extract arguments and their values from a SOAP response.

Parameters

xml_response (str) – SOAP/xml response text (unicode, not utf-8).

Returns

a dict of {argument_name: value} items.

Return type

dict

compose_args(action_name, in_argdict)[source]

Compose the argument list from an argument dictionary, with respect for default values.

Parameters
  • action_name (str) – The name of the action to be performed.

  • in_argdict (dict) – Arguments as a dict, eg ``{‘InstanceID’: 0, ‘Speed’: 1}. The values can be a string or something with a string representation.

Returns

a list of (name, value) tuples.

Return type

list

Raises
  • AttributeError – If this service does not support the action.

  • ValueError – If the argument lists do not match the action signature.

build_command(action, args=None)[source]

Build a SOAP request.

Parameters
  • action (str) – the name of an action (a string as specified in the service description XML file) to be sent.

  • args (list, optional) – Relevant arguments as a list of (name, value) tuples.

Returns

a tuple containing the POST headers (as a dict) and a

string containing the relevant SOAP body. Does not set content-length, or host headers, which are completed upon sending.

Return type

tuple

send_command(action, args=None, cache=None, cache_timeout=None, **kwargs)[source]

Send a command to a Sonos device.

Parameters
  • action (str) – the name of an action (a string as specified in the service description XML file) to be sent.

  • args (list, optional) – Relevant arguments as a list of (name, value) tuples, as an alternative to kwargs.

  • cache (Cache) – A cache is operated so that the result will be stored for up to cache_timeout seconds, and a subsequent call with the same arguments within that period will be returned from the cache, saving a further network call. The cache may be invalidated or even primed from another thread (for example if a UPnP event is received to indicate that the state of the Sonos device has changed). If cache_timeout is missing or None, the cache will use a default value (which may be 0 - see cache). By default, the cache identified by the service’s cache attribute will be used, but a different cache object may be specified in the cache parameter.

  • kwargs – Relevant arguments for the command.

Returns

a dict of {argument_name, value} items.

Return type

dict

Raises
  • AttributeError – If this service does not support the action.

  • ValueError – If the argument lists do not match the action signature.

  • SoCoUPnPException – if a SOAP error occurs.

  • UnknownSoCoException – if an unknonwn UPnP error occurs.

  • requests.exceptions.HTTPError – if an http error occurs.

handle_upnp_error(xml_error)[source]

Disect a UPnP error, and raise an appropriate exception.

Parameters

xml_error (str) – a unicode string containing the body of the UPnP/SOAP Fault response. Raises an exception containing the error code.

subscribe(requested_timeout=None, auto_renew=False, event_queue=None, strict=True)[source]

Subscribe to the service’s events.

Parameters
  • requested_timeout (int, optional) – If requested_timeout is provided, a subscription valid for that number of seconds will be requested, but not guaranteed. Check Subscription.timeout on return to find out what period of validity is actually allocated.

  • auto_renew (bool) – If auto_renew is True, the subscription will automatically be renewed just before it expires, if possible. Default is False.

  • event_queue (Queue) – a thread-safe queue object on which received events will be put. If not specified, a (Queue) will be created and used.

  • strict (bool, optional) – If True and an Exception occurs during execution, the Exception will be raised or, if False, the Exception will be logged and the Subscription instance will be returned. Default True.

Returns

an instance of Subscription,

representing the new subscription. If config.EVENTS_MODULE has been set to refer to events_twisted, a deferred will be returned with the Subscription as its result and deferred.subscription will be set to refer to the Subscription.

Return type

Subscription

To unsubscribe, call the unsubscribe method on the returned object.

property actions

The service’s actions with their arguments.

Returns

A list of Action namedtuples, consisting of action_name (str), in_args (list of Argument namedtuples, consisting of name and argtype), and out_args (ditto).

Return type

list(Action)

The return value looks like this::
[
Action(

name=’GetMute’, in_args=[

System Message: ERROR/3 (/builddir/build/BUILD/soco-0.19/soco/services.py:docstring of soco.services.Service.actions, line 13)

Unexpected indentation.

Argument(name=’InstanceID’, …), Argument(

System Message: ERROR/3 (/builddir/build/BUILD/soco-0.19/soco/services.py:docstring of soco.services.Service.actions, line 15)

Unexpected indentation.

name=’Channel’, vartype=’string’, list=[‘Master’, ‘LF’, ‘RF’, ‘SpeakerOnly’], range=None

System Message: WARNING/2 (/builddir/build/BUILD/soco-0.19/soco/services.py:docstring of soco.services.Service.actions, line 19)

Block quote ends without a blank line; unexpected unindent.

)

System Message: WARNING/2 (/builddir/build/BUILD/soco-0.19/soco/services.py:docstring of soco.services.Service.actions, line 20)

Block quote ends without a blank line; unexpected unindent.

], out_args=[

System Message: ERROR/3 (/builddir/build/BUILD/soco-0.19/soco/services.py:docstring of soco.services.Service.actions, line 22)

Unexpected indentation.

Argument(name=’CurrentMute, …)

System Message: WARNING/2 (/builddir/build/BUILD/soco-0.19/soco/services.py:docstring of soco.services.Service.actions, line 23)

Block quote ends without a blank line; unexpected unindent.

]

System Message: WARNING/2 (/builddir/build/BUILD/soco-0.19/soco/services.py:docstring of soco.services.Service.actions, line 24)

Definition list ends without a blank line; unexpected unindent.

) Action(…)

System Message: WARNING/2 (/builddir/build/BUILD/soco-0.19/soco/services.py:docstring of soco.services.Service.actions, line 26)

Definition list ends without a blank line; unexpected unindent.

]

Its string representation will look like this::

GetMute(InstanceID: ui4, Channel: [Master, LF, RF, SpeakerOnly]) -> {CurrentMute: boolean}

iter_actions()[source]

Yield the service’s actions with their arguments.

Yields

Action – the next action.

Each action is an Action namedtuple, consisting of action_name (a string), in_args (a list of Argument namedtuples consisting of name and argtype), and out_args (ditto), eg:

Action(
    name='SetFormat',
    in_args=[
        Argument(name='DesiredTimeFormat', vartype=<Vartype>),
        Argument(name='DesiredDateFormat', vartype=<Vartype>)],
    out_args=[]
)
property event_vars

The service’s eventable variables.

Returns

A list of (variable name, data type) tuples.

Return type

list(tuple)

iter_event_vars()[source]

Yield the services eventable variables.

Yields

tuple – a tuple of (variable name, data type).

class soco.services.AlarmClock(soco)[source]

Sonos alarm service, for setting and getting time and alarms.

class soco.services.MusicServices(soco)[source]

Sonos music services service, for functions related to 3rd party music services.

Parameters

soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent

class soco.services.DeviceProperties(soco)[source]

Sonos device properties service, for functions relating to zones, LED state, stereo pairs etc.

Parameters

soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent

class soco.services.SystemProperties(soco)[source]

Sonos system properties service, for functions relating to authentication etc.

Parameters

soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent

class soco.services.ZoneGroupTopology(soco)[source]

Sonos zone group topology service, for functions relating to network topology, diagnostics and updates.

Parameters

soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent

GetZoneGroupState(*args, **kwargs)[source]

Overrides default handling to use the global shared zone group state cache, unless another cache is specified.

class soco.services.GroupManagement(soco)[source]

Sonos group management service, for services relating to groups.

Parameters

soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent

class soco.services.QPlay(soco)[source]

Sonos Tencent QPlay service (a Chinese music service)

Parameters

soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent

class soco.services.ContentDirectory(soco)[source]

UPnP standard Content Directory service, for functions relating to browsing, searching and listing available music.

class soco.services.MS_ConnectionManager(soco)[source]

UPnP standard connection manager service for the media server.

class soco.services.RenderingControl(soco)[source]

UPnP standard rendering control service, for functions relating to playback rendering, eg bass, treble, volume and EQ.

class soco.services.MR_ConnectionManager(soco)[source]

UPnP standard connection manager service for the media renderer.

class soco.services.AVTransport(soco)[source]

UPnP standard AV Transport service, for functions relating to transport management, eg play, stop, seek, playlists etc.

class soco.services.Queue(soco)[source]

Sonos queue service, for functions relating to queue management, saving queues etc.

class soco.services.GroupRenderingControl(soco)[source]

Sonos group rendering control service, for functions relating to group volume etc.