.. _python-library:

Python Library
====================================================================================================

The DQR supports a small Python library containing utility functions needed to manage follow-up.
The library is divided into several small modules, each with a very focused purpose.
We describe each in turn below.

condor
----------------------------------------------------------------------------------------------------

The DQR submits follow-up tasks to Condor for completion, and therefore must be able to schedule Condor jobs.
This is done via a DAG and SUB files tailored for each candidate.
Routines for constructing these files are contained herein.

.. automodule:: dqr.condor
    :members:

create
----------------------------------------------------------------------------------------------------

The DQR uses this module to construct the JSON configuration file and DAG depending on the user specification.
Annotations to GraceDb uploading `dqr.html`, `dqr.js`, and `dqr.json` are made here and the DAG is submitted from within this module.
This will usually be triggered in response to `lvalert` messages.

.. automodule:: dqr.create
  :members:


gracedb
----------------------------------------------------------------------------------------------------

The DQR provides a simple function that unifies the instantiation of GraceDB REST API classes and FakeDb classes.
By delegating to :func:`dqr.gracedb.init`, the choice of which is appropriate is abstracted away from the client and relies only on the `url` (either a server name or a local path).

.. automodule:: dqr.gracedb
    :members:

interact
----------------------------------------------------------------------------------------------------

This module formats interaction requests and uploads them to GraceDb.
It primarily supports `dqr-interact`.

.. automodule:: dqr.interact
    :members:

json
----------------------------------------------------------------------------------------------------

The DQR relies heavily on standardized JSON file formats (see :ref:`technical-design`).
As such, `dqr.json` provides convenient functions that respect the file format requirements.

.. automodule:: dqr.json
    :members:

logging
----------------------------------------------------------------------------------------------------

This module standardizes how local logging is performed and formatted.

.. automodule:: dqr.logging
    :members:

utils
----------------------------------------------------------------------------------------------------

This module supports some common utilities that may be useful for many tasks.
In addition to `dqr.utils.utils`, this is also where separate tasks should implement their supporting libraries (e.g., `dqr.utils.omegascan`). 

Along with Python source code, all configuration files for individual tasks should live in `dqr.utils` as `package_data` and will be installed alongside the source code.
In this way, logic within `dqr.condor` can automatically discover configurations for each scheduled task and build the DAG appropriately.

Below, we only spell out the utilities implemented within `dqr.utils.utils`, leaving the specifications of each task for elsewhere.

utils.utils
____________________________________________________________________________________________________

.. automodule:: dqr.utils.utils
    :members: