llama.listen.gcn package

Tools for receiving, parsing, and archiving GCN Notices. When run as a script, starts a GCN VOEvent listener process that listens for GCN triggers and runs all_llama_handlers on those triggers. When run at the command line, starts a GCN listener that reacts to incoming GCN triggers.

class llama.listen.gcn.LlamaHandlers

Bases: llama.listen.gcn.LlamaHandlersTuple

A gcn handler (see pygcn documentation) that runs all gcn handlers specified in LlamaHandlers.included on the given payload (the VOEvent XML string) and root (the lxml VOEvent object for the payload). Add handlers either manually or with the llama_handler decorator. All handlers are run in succession, so it’s up to you to make sure they don’t interfere with each other. Set up as a callable class so that parameters for handlers can be stored in intances (e.g. output directories).

Parameters

  • rundir (str, optional) – Path to the run directory (i.e. where new LLAMA triggers are saved by the GCN handler). Defaults to DEFAULT_RUN_DIR. This directory is created on instantiation if it does not already exist.

  • gcn_archive (str, optional) – Path to the GCN Notice archive directory (i.e. where ALL new GCN Notices are archived). Defaults to GCN_ARCHIVE. This directory is created on instantiation if it does not already exist.

  • included (array-like, optional) – A tuple of handlers to call when this instance is called; these functions must take payload and root as their only arguments. Defaults to a list of all methods and callable properties of LlamaHandlers whose names start with “handle”, but this can be overridden. Note that you can include other valid GCN handlers that are not LlamaHandlers methods if you choose (see the pygcn documentation for details on valid GCN handlers).

handle_archive(payload, root)

Save a GCN Notice VOEvent to the archive specified by this LlamaHandlers instance. Applies to all GCN Notices including ones processed by the pipeline. Will not overwrite existing VOEvent files (since VOEvent filenames are based on IVORNs, which are supposed to be unique). If the filename is already in use, the xml will be logged at the info level (useful for production to catch unexpected behavior).

property handle_lvc_initial_or_update

Get a handle_lvc_gcn function for GCN Initial or Update notices that saves to self.rundir and adds an Advok marker.

property handle_lvc_preliminary

Get a handle_lvc_gcn function for GCN Preliminary notices that saves to self.rundir.

handle_lvc_retraction(payload, root)

Mark all auto-generated events associated with this graceid as vetoed and save the retraction.

property included

Get a list of GCN handlers to include in this overall handler. If this was not specified when LlamaHandlers was instantiated, return all GCN handlers defined in LlamaHandlers whose names start with “handle”.

class llama.listen.gcn.LlamaHandlersTuple(rundir, gcn_archive, manually_included)

Bases: tuple

property gcn_archive

Alias for field number 1

property manually_included

Alias for field number 2

property rundir

Alias for field number 0

llama.listen.gcn.get_handle_lvc_gcn(filehandler, notice_types, rundir='/root/.local/share/llama/current_run/')

Get a handle_lvc_gcn function that outputs triggers to directories in rundir using the specified filehandler.

llama.listen.gcn.get_subdir(archive_dir, receipt_time)

Get the subdirectory where a VOEvent would be archived. Since VOEvents are archived in subdirectories (based on date) of the main archive_directory, this path depends on the receipt_time of the VOEvent.

Parameters

  • archive_dir (str) – The root directory for all GCN Notices.

  • receipt_time (datetime.datetime) – The time of receipt of the GCN Notice.

llama.listen.gcn.run_on_voevent_file(files='*.xml', handler=LlamaHandlers(rundir='/root/.local/share/llama/current_run', gcn_archive='/root/.local/share/llama/gcn/archive', manually_included=None))

Run a handler on VOEvent XML files (as if they had just been received via GCN). By default, runs all LLAMA handlers (marked with @llama_handler decorator) on the given VOEvent.

Parameters

  • files (str or list, optional) – A list of filenames to operate on or else a string that can be interpreted as a UNIX-like glob pattern for matching files as handled by fnmatch or glob (DEFAULT: “*.xml”, matching XML files in the current directory). Note that this means you can usually just provide the exact filename (as long as it can’t be interpreted as a UNIX glob pattern).

  • handler (function, optional) – The GCN Handler, of the same sort used by gcn.listen (DEFAULT: all_llama_handlers).

Raises

XMLSyntaxError – If the files provided are not valid VOEvents, raises an exception once it gets to that VOEvent file.