API

This section provides information about the igwn_alert.client class, which is the method for accessing the API.

class igwn_alert.client.client(username=None, password=None, auth=None, authfile=None, noauth=False, group='gracedb', consumer_group=None, server='kafka://kafka.scimma.org/', port=9092, batch_size=1, batch_timeout=datetime.timedelta(microseconds=200000), retry_on_fatal=False, listen_retries=3, retry_wait=0.1)

A hop-scotch client configured for igwn_alerts from GraceDB

Parameters:

• username (str (optional)) – The SCIMMA username, or None to look up with hop auth or netrc

• password (str (optional)) – The SCIMMA password, or None to look up with hop auth or netrc

• auth (Auth (optional)) – A hop.auth.Auth object.

• authfile (str (optional)) – Path to hop auth.toml

• noauth (bool (optional)) – Set to True for unauthenticated session

• group (str (optional)) – GraceDB group (e.g., gracedb, gracedb-playground)

• consumer_group (str (optional)) – The consumer group ID to use for consuming messages. This can be used across sessions to avoid missed messages as well as allowing load-balancing of messages across multiple consumers assigned to the same consumer group. If not set, one will be randomly generated.

• server (str (optional)) – The server host (i.e., kafka://…..)

• port (int (optional)) – The server port

• batch_size (int (optional)) – The number of messages to request per batch. Higher values may be more efficient, but may add latency

• batch_timeout (timedelta (optional)) – How long the client waits to gather a full batch of messages. Higher values may be more efficient, but may add latency

• retry_on_fatal (bool (optional)) – Listening client should reconnect on fatal KafkaExceptions Default: false

• listen_retries (int (optional)) – Number of times to retry on fatal KafkaException Default: 3

• retry_wait (float (optional)) – Time to wait before retrying on fatal KafkaException Default: 0.1

Example

Here is an example for listing topics:

alert_client = client(group='gracedb-test')
topics = alert_client.get_topics()

Here is an example for running a listener.

def process_alert(topic, payload):
    if topic == 'cbc_gstlal':
        alert = json.loads(payload)
        ...

client = IGWNAlertClient(group='gracedb-test')
topics = ['superevent', 'cbc_gstlal']
client.listen(process_alert, topics)

connect(topics)

Takes in a topic or list of topics. Create writable stream objects for each of the topics in the list.

Must have publish rights on topic.

Parameters:

topic (str, or list of str) – Topic or list of topics to publish to

delete()

Delete a pubsub topic

disconnect(topics=None)

Close all the current stream, or optionally close a single or list of topics

Parameters:

topic (str, or list of str (optional)) – Topic or list of topics to disconnect from. If None, then disconnect from all topics.

flush_by_topic(topic)

Flush the stream session for a specific topic after the session has been connected with client.connect()

Parameters:

topic (str) – Topic name to publish to

get_subscriptions()

Get a list of your subscriptions.

get_topics(group=None)

Get a list of all available pubsub topics.

Parameters:

group (str (optional)) – Group prefix (e.g., “gracedb”, “gracedb-playground”) to show topics for. If None, list topics for the current group.

listen(callback=None, topic=None)

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

Parameters:

• callback (callable (optional)) – A function of two arguments: the topic and the alert payload. When set to None, print out alert payload.

• topic (str, or list of str (optional)) – Topic or list of topics to listen to. When set to None, then listen to all topics connected to user’s credential.

publish(topic, msg=None)

Send an alert without pre-establishing a session.

Parameters:

• topic (str, or list of str (optional)) – Topic or list of topics to publish to.

• msg (str) – A message to publish to a topic

publish_to_topic(topic, msg)

Publish to a specific topic after a session has been connected with client.connect()

Parameters:

• topic (str) – Topic name to publish to

• msg (str) – A message to publish to a topic

subscribe(*topics)

Subscribe to one or more pubsub topics.

unsubscribe(*topics)

Unsubscribe from one or more pubsub topics.