Commit a6564a97 authored by Leo Pound Singer's avatar Leo Pound Singer

Add more code examples

parent d8982618
Pipeline #110226 passed with stages
in 1 minute and 26 seconds
......@@ -91,33 +91,69 @@ class LVAlertClient(slixmpp.ClientXMPP):
Example
-------
Here is an example for performing administrative actions.
Usage of the :class:`LVAlertClient` class typically has three phases:
.. code-block:: python
1. Create a client instance. Pass any desired connection options (server,
username, password) to the constructor.
client = LVAlertClient()
2. Configure a pubsub listener by calling the :meth:`listen` method and
one or more event handlers by calling the
:meth:`~slixmpp.xmlstream.xmlstream.XMLStream.add_event_handler`
method.
async def callback(*args):
await client.subscribe('cbc_gstlal', 'cbc_pycbc')
client.stop()
# Run callback as soon as the client is connected.
client.add_event_handler('session_start', callback, disposable=True)
# Start processing (stops when callback reaches client.stop())
client.start()
3. Start the client run loop by calling the :meth:`start` method. The
client run loop continues processing until it is interrupted by a
:exc:`KeyboardInterrupt` or a call to the :meth:`stop` method either
from one of the event handlers or from another thread.
Here is an example for running a listener.
The simplest use case is a client that runs a callback for each LVAlert
message that is received:
.. code-block:: python
def process_alert(node, payload):
if node == 'cbc_gstlal':
alert = json.loads(payload)
...
print(alert)
client = LVAlertClient()
client.listen(process_alert)
client.start() # Runs until interrupted with Ctrl-C
Typically, if you want to call one of the administrative methods
(:meth:`get_nodes`, :meth:`get_subscriptions`, :meth:`subscribe`, or
:meth:`unsubscribe`), you will add them to a callback for the
``session_start`` event. Since these four methods are :term:`coroutines
<coroutine>`, the callback should be defined using the ``async``/``await``
syntax:
.. code-block:: python
client = LVAlertClient()
async def callback(*args):
subscriptions = await client.get_subscriptions()
print('Subscribed to:', subscriptions)
client.add_event_handler('session_start', callback)
client.start() # Runs until interrupted with Ctrl-C
To register a *single-shot* callback, pass ``disposable=True`` to
:meth:`~slixmpp.xmlstream.xmlstream.XMLStream.add_event_handler`. This is
most useful if you want to perform some action once, then immediately
disconnect and stop:
.. code-block:: python
client = LVAlertClient()
async def callback(*args):
await client.subscribe('cbc_gstlal', 'cbc_pycbc')
client.stop()
client.add_event_handler('session_start', callback, disposable=True)
client.start() # Stops after callback reaches client.stop()
"""
def __init__(self, username=None, password=None, resource=None, netrc=None,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment