Metadata-Version: 2.4
Name: dqrdb
Version: 0.2.0
Summary: Maintain a database of IGWN Data Quality Reports
Author-email: Joseph Areeda <joseph.areeda@ligo.org>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://git.ligo.org/dqr-builder/dqrdb
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astropy
Requires-Dist: basedb
Requires-Dist: dqr-configuration
Requires-Dist: gwpy
Provides-Extra: test
Requires-Dist: pytest>=2.8.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

# dqrdb

[![PyPI version](https://img.shields.io/pypi/v/dqrdb.svg)](https://pypi.org/project/dqrdb/)
[![License: GPL v3](https://img.shields.io/badge/License-GPL_v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Docs](https://img.shields.io/badge/docs-dqr--builder.docs.ligo.org-blue.svg)](https://dqr-builder.docs.ligo.org/dqrdb/)

`dqrdb` maintains a MariaDB/MySQL database that tracks every Data Quality
Report (DQR) produced by the IGWN DQR pipeline — which events have been
processed, where the report files live, and what site and revision produced
them.

## Overview

When the DQR task manager completes a report, `dqrdb` records it:

```
GraceDB alert → dqralert → DQR task manager → dqr-process-upload → dqrdb
```

The database can also be populated in bulk from an existing directory tree
using `dqr-scandir`.

## Installation

```bash
pip install dqrdb
```

## Quick Start

### 1. Configure the database connection

Create a `dqrdb.ini` file:

```ini
[DATABASE]
host     = localhost
user     = dqr-dev
password = <your-password>
database = dqr
```

### 2. Populate the database from an existing directory tree

```bash
dqr-scandir -v \
    --base-url https://ldas-jobs.ligo.caltech.edu/~dqr \
    --project online \
    /home/dqr/public_html/o4dqr/online/events/
```

### 3. Query the database from Python

```python
from dqrdb.utils import get_events

results = get_events('S230529ad', project='online')
for r in results:
    print(r['site'], r['version'], r['url'])
```

### 4. Add a result programmatically

```python
from pathlib import Path
from dqrdb.utils import add_result

added = add_result(
    path=Path('/home/dqr/public_html/o4dqr/online/events/202305/S230529ad_LHO_01'),
    url='https://ldas-jobs.ligo.caltech.edu/~dqr/online/events/202305/S230529ad_LHO_01/',
    gid='S230529ad',
    project='online',
    site='LHO',
    rev=1,
)
print('New record inserted:', added)
```

## Command-Line Reference

| Command | Description |
|---|---|
| `dqr-scandir` | Walk a directory tree and record all DQR results |
| `dqr-process-upload` | Accept a remote DQR upload and register it in the database |

## Documentation

Full documentation — including configuration reference, CLI options, and
API docs — is available at:

**<https://dqr-builder.docs.ligo.org/dqrdb/>**

## License

`dqrdb` is distributed under the [GNU General Public License v3 or later](LICENSE).
