sleek-lvalert Documentation

sleek-lvalert is a client for the LIGO/Virgo LVAlert pubsub infrastructure that is powered by slixmpp. It requires Python 3.5 or later.

Quick Start

Install with pip:

pip install sleek-lvalert

Put your username and password in your netrc file in ~/.netrc:

echo 'machine lvalert-test.cgca.uwm.edu login albert.einstein password gravity' >> ~/.netrc
chmod 0600 ~/.netrc

Subscribe to some nodes:

lvalert subscribe cbc_gstlal cbc_pycbc cbc_mbtaonline

Listen for LVAlert messages:

lvalert listen

Command Line Interface

usage: lvalert [-h] [-l {critical,error,warning,info,debug}] [-n NETRC]
               [-r RESOURCE] [-s SERVER] [-u USERNAME]
               {listen,subscriptions,nodes,subscribe,unsubscribe} ...

Positional Arguments

action

Possible choices: listen, subscriptions, nodes, subscribe, unsubscribe

sub-command help

Named Arguments

-l, --log

Possible choices: critical, error, warning, info, debug

Log level

Default: “error”

-n, --netrc

netrc file (default: read from NETRC environment variable or ~/.netrc)

-r, --resource

XMPP resource (default: random)

-s, --server

LVAlert server hostname

Default: “lvalert.cgca.uwm.edu”

-u, --username

User name (default: look up in netrc file)

Sub-commands:

listen

Listen for LVAlert messages and print them to stdout.

lvalert listen [-h]

subscriptions

List your subscriptions

lvalert subscriptions [-h]

nodes

List available pubsub nodes

lvalert nodes [-h]

subscribe

Subscribe to one or more nodes

lvalert subscribe [-h] node [node ...]

Positional Arguments

node

a pubsub node (e.g. cbc_gstlal)

unsubscribe

Unsubscribe from one or more nodes

lvalert unsubscribe [-h] node [node ...]

Positional Arguments

node

a pubsub node (e.g. cbc_gstlal)

API Reference

class sleek_lvalert.LVAlertClient(username=None, password=None, resource=None, netrc=None, interactive=False, server='lvalert.cgca.uwm.edu')

Bases: slixmpp.clientxmpp.ClientXMPP

An XMPP client configured for LVAlert.

Parameters

• username (str, optional) – The XMPP username, or None to look up from the netrc file.

• password (str, optional) – The XMPP password, or None to look up from the netrc file.

• resource (str, optional) – The XMPP resource ID, or None to generate a random one.

• netrc (str, optional) – The netrc file. The default is to consult the NETRC environment variable or use the default path of ~/.netrc.

• interactive (bool, optional) – If True, then fall back to asking for the password on the command line if necessary.

• server (str, optional) – The LVAlert server hostname.

Example

Usage of the LVAlertClient class typically has three phases:

1. Create a client instance. Pass any desired connection options (server, username, password) to the constructor.

2. Configure a pubsub listener by calling the listen() method and one or more event handlers by calling the add_event_handler() method.

3. Start the client run loop by calling the start() method. The client run loop continues processing until it is interrupted by a KeyboardInterrupt or a call to the stop() method either from one of the event handlers or from another thread.

The simplest use case is a client that runs a callback for each LVAlert message that is received:

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 (get_nodes(), get_subscriptions(), subscribe(), or unsubscribe()), you will add them to a callback for the session_start event. Since these four methods are coroutines, the callback should be defined using the async/await syntax:

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 add_event_handler(). This is most useful if you want to perform some action once, then immediately disconnect and stop:

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()

Members

get_nodes()	Get a list of all available pubsub nodes.
get_subscriptions()	Get a list of your subscriptions.
listen(callback)	Set a callback to be executed for each pubsub item received.
start()	Run the client until stop() is called.
stop()	Stop the client.
subscribe(*nodes)	Subscribe to one or more pubsub nodes.
unsubscribe(*nodes)	Unsubscribe from one or more pubsub nodes.

async get_nodes()

Get a list of all available pubsub nodes.

Returns

A list of strings naming the available pubsub nodes

Return type

list

async get_subscriptions()

Get a list of your subscriptions.

Returns

A list of strings naming the subscribed pubsub nodes

Return type

list

listen(callback)

Set a callback to be executed for each pubsub item received.

Parameters

callback (callable) – A function of two arguments: the node and the alert payload.

start()

Run the client until stop() is called.

Establish a connection, process all events, and run all event handlers, until stop() is called or the current thread is interrupted (e.g., by a KeyboardInterrupt).

If the connection is ever dropped, it is re-established automatically.

Once processing stops, the connection is closed cleanly before this method returns.

stop()

Stop the client.

If the client has been started by calling start(), then start() will return and the connection will be closed.

Notes

This method is thread safe, so you can use it to stop the client from another thread. For example:

from threading import Thread
from time import sleep

client = LVAlertClient()

def wait_then_stop():
    sleep(5)
    client.stop()
Thread(target=wait_then_stop).start()

client.start()

async subscribe(*nodes)

Subscribe to one or more pubsub nodes.

Parameters

*args (list) – A list of strings naming the pubsub nodes to which to subscribe

async unsubscribe(*nodes)

Unsubscribe from one or more pubsub nodes.

Parameters

*args (list) – A list of strings naming the pubsub nodes from which to unsubscribe