The events_twisted module¶
soco.events_twisted module has been provided for those wanting to
use soco in an application built on the twisted framework who want the event
listener also to be implemented using twisted. The
page contains an example of how to use the module.
The event listener is an HTTP server that receives event notifications from
sonos devices. In the
soco.events module, it is implemented using
threading and requests. The
soco.events module will apply by default,
config.EVENTS_MODULE is set to point to the
Twisted is not a soco dependency. The existence of the events_twisted module is not a recommendation or endorsement of twisted. The events_twisted module has been provided because there are some soco users who use twisted.
If you wish to use events_twisted, it is assumed you already use and are familiar with the twisted framework. No guidance is provided here on how to install or use twisted.
soco.events_twisteduses twisted, rather than requests, for making and receiving HTTP calls. Network calls in events_twisted return at once without blocking
soco.events_twisted, the event listener runs in the main thread of execution. Threading is not used
soco.events_twistedrequires a twisted reactor to be running in the application into which it is imported. It will not install or start a reactor
soco.events_twistedis not threadsafe and should run in the main thread of execution. Therefore, subscribing to events should happen in the main thread of execution. In part, this is because a Deferred is not threadsafe
soco.events_twisted, if the requested port is not available, the event_listener will automatically try the next port, within a maximum range of 100 of the port initially requested
soco.events_twisted, subscribe, renew and unsubscribe return a Deferred the result of which will be the
soco.events_twisted.Subscriptioninstance. The Subscription can be accessed by adding a callback to receive it. In addition, Deferred.subscription is set to refer to the Subscription. This is a simpler and quicker way to get the Subscription
soco.events_twisted, Subscription.callback can be set to refer to a function that will be called each time a
soco.events_base.Eventis received by the Subscription. The callback will be passed the Event as the only parameter. This is likely to be the most convenient way to receive Events. If Subscription.callback is not set, or is not callable, Events will be put on the Subscription’s event queue, in the same way as for the events module.
Please note that all network calls in soco (other than those in events_twisted) are made using the requests library, which blocks. In an application based on twisted, it may be desirable to make these network calls asynchronously, so they do not block. Two solutions to consider are (a) to use threads when calling other potentially blocking soco methods or (b) to use a subprocess to handle calls to soco. Twisted provides the deferToThread method for deferring potentially blocking methods to a thread. If a subprocess is to be used, there will need to be a protocol for communication between the subprocess and the main application. For a DIY solution, twisted’s NetstringReceiver may be a useful starting point.