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(name, in_args, out_args)[source]

A UPnP Action and its arguments.

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

class soco.services.Argument(name, vartype)[source]

A UPnP Argument and its type.

Create new instance of ArgumentBase(name, vartype)

class soco.services.Vartype(datatype, default, list, range)[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

The SoCo instance to which UPnP Actions are sent

Type: SoCo

service_type

The UPnP service type.

Type: str

version

The UPnP service version.

Type: str

base_url

The base URL for sending UPnP Actions.

Type: str

control_url

The UPnP Control URL.

Type: str

scpd_url

The service control protocol description URL.

Type: str

event_subscription_url

The service eventing subscription URL.

Type: str

cache: 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, e.g. {'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 unknown 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 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=[
            Argument(name='InstanceID', ...),
            Argument(
                name='Channel',
                vartype='string',
                list=['Master', 'LF', 'RF', 'SpeakerOnly'],
                range=None
            )
        ],
        out_args=[
            Argument(name='CurrentMute, ...)
        ]
    )
    Action(...)
]

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.

Parameters

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

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.AudioIn(soco)[source]

Sonos audio in service, for functions related to RCA audio input.

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 –

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.

Parameters

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

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

UPnP standard connection manager service for the media server.

Parameters

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

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

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

Parameters

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

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

UPnP standard connection manager service for the media renderer.

Parameters

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

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

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

Parameters

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

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

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

Parameters

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

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

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

Parameters

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