Metadata-Version: 2.4
Name: epicsarchiver-retrieval-client
Version: 1.0.0
Summary: A python library for retrieving data from the EPICS Archiver Appliance.
Project-URL: Source, https://github.com/archiver-appliance/epicsarchiver-retrieval-client
Author: Benjamin Bertrand
Author-email: Sky Brewer <sky.brewer@ess.eu>
License-File: LICENSE
Keywords: archiver,epics,retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: protobuf<8,>=7
Requires-Dist: pytz>=2024.1
Requires-Dist: typing-extensions>=4.12
Provides-Extra: all
Requires-Dist: aiohttp>=3; extra == 'all'
Requires-Dist: click>=8; extra == 'all'
Requires-Dist: polars>=1; extra == 'all'
Requires-Dist: requests>=2; extra == 'all'
Requires-Dist: rich>=13; extra == 'all'
Provides-Extra: async
Requires-Dist: aiohttp>=3; extra == 'async'
Provides-Extra: cli
Requires-Dist: click>=8; extra == 'cli'
Requires-Dist: rich>=13; extra == 'cli'
Provides-Extra: polars
Requires-Dist: polars>=1; extra == 'polars'
Provides-Extra: sync
Requires-Dist: requests>=2; extra == 'sync'
Description-Content-Type: text/markdown

# Python EPICS Archiver Appliance library

Python package to interact with the [EPICS Archiver Appliance](https://epicsarchiver.readthedocs.io/en/latest/).

- [Documentation](https://epicsarchiver-retrieval-client.readthedocs.io/en/latest/)
- [Repository](https://github.com/archiver-appliance/epicsarchiverap)

## Installation

The epicsarchiver-retrieval-client can be installed using:

```console
pip install epicsarchiver-retrieval-client
```

The core package has minimal dependencies (protobuf + pytz) and is sufficient for parsing `.pb` files
and working with `ArchiveEvent` objects directly. Heavy dependencies are opt-in via extras:

| Extra | Installs | Use when |
|-------|----------|----------|
| `[polars]` | polars | you want `get_data()` to return a `DataFrame` |
| `[sync]` | requests | you want the synchronous `ArchiverRetrieval` client |
| `[async]` | aiohttp | you want the async `AsyncArchiverRetrieval` client |
| `[cli]` | click, rich | you want the `epicsarchiver` command-line tool |
| `[all]` | everything above | full functionality |

```console
# Everything (recommended for most users)
pip install "epicsarchiver-retrieval-client[all]"

# Core only — parse local .pb files, no HTTP clients or DataFrames
pip install epicsarchiver-retrieval-client[all]

# Sync retrieval with DataFrame output
pip install "epicsarchiver-retrieval-client[polars,sync]"
```

## Quick start

The package also installs a command line tool. Used to fetch data from the archiver and display in the terminal.

```console
$ arch-retrieval get --help
Usage: arch-retrieval get [OPTIONS] PVS...

  Print out data from an archiver cluster.

  ARGUMENT pvs What pvs to get data of.

  Example usage:

  .. code-block:: console

      arch-retrieval --hostname archiver-01.example.com get PV_NAME1 PV_NAME2

Options:
  --debug                         Turn on debug logging
  -s, --start [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S|%Y-%m-%dT%H:%M:%S.%f|%Y-%m-%d %H:%M:%S.%f]
                                  Start time of query [default: 30 seconds
                                  ago]
  -e, --end [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S|%Y-%m-%dT%H:%M:%S.%f|%Y-%m-%d %H:%M:%S.%f]
                                  End time of query, [default: now]
  -p, --processor-name [FIRSTSAMPLE|LASTSAMPLE|FIRSTFILL|LASTFILL|MEAN|MIN|MAX|COUNT|NCOUNT|NTH|MEDIAN|STD|JITTER|IGNOREFLYERS|FLYERS|VARIANCE|POPVARIANCE|KURTOSIS|SKEWNESS|LINEAR|LOESS|OPTIMIZED|OPTIMLASTSAMPLE|CAPLOTBINNING|DEADBAND|ERRORBAR]
                                  PreProcessor to use

                                  Docs at https://epicsarchiver.readthedocs.io/en/latest/user/userguide.html#processing-of-data
  -b, --bin_size INTEGER          Bin size (mostly in seconds) for
                                  preprocessor.
  --help                          Show this message and exit.
```

Note you can also specify a hostname for the archiver either with an environment variable:

```console
export EPICSARCHIVER_HOSTNAME=archiver-01.example.com
````

To fetch data using the Python library (requires `[polars,sync]`):

```python
from epicsarchiver import ArchiverAppliance
from epicsarchiver.retrieval.archiver_retrieval import ArchiverRetrieval

# High-level: returns a polars DataFrame
retrieval = ArchiverRetrieval("archiver-01.example.com")
df = retrieval.get_data("my:pv", start="2018-07-04 13:00", end="2018-07-04 14:00")
# DataFrame columns: date (ns UTC), val, severity, status, field_values, headers

# Low-level: returns ArchiveEventsData (no polars required)
metadata, events = retrieval.get_events(
    "my:pv",
    start=datetime(2018, 7, 4, 13, 0, tzinfo=UTC),
    end=datetime(2018, 7, 4, 14, 0, tzinfo=UTC),
)
```

To search for PV names:

```python
# Without time range — returns all matching PVs
pv_list = retrieval.search("(?i)^my-system:.*:temperature$")

# With time range — only PVs that recorded data in the given window
pv_list = retrieval.search(
    "(?i)^my-system:.*:temperature$",
    start=datetime(2026, 1, 1, tzinfo=UTC),
    end=datetime(2026, 1, 2, tzinfo=UTC),
)
```

## Development

The package is built and packaged with [Hatch](https://hatch.pypa.io/latest/).

```console
pip install hatch
```

Run all checks and code coverage:

```console
hatch run all
```

Run tests:

```console
hatch test
```

Run formatting and check:

```console
hatch fmt
```

Run local docs:

```console
hatch run dev:docs-live
```

Regenerate protobuf python api:

```console
hatch run dev:protoc-gen
```

## License

Distributed under the terms of the [MIT license][license]

<!-- sphinx-include-end -->

[license]: LICENSE
