Metadata-Version: 2.4
Name: aeonlib
Version: 0.2.0
Summary: A suite of modules to enable TDA/MMA observations
Author-email: Austin Riba <ariba@lco.global>
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: astropy>=6.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.9.1
Requires-Dist: pydantic>=2.11.1
Provides-Extra: eso
Requires-Dist: p2api>=1.0.10; extra == 'eso'
Provides-Extra: lt
Requires-Dist: lxml-stubs>=0.5.1; extra == 'lt'
Requires-Dist: lxml>=5.4.0; extra == 'lt'
Requires-Dist: suds>=1.2.0; extra == 'lt'
Provides-Extra: salt
Requires-Dist: beautifulsoup4>=4.14.3; extra == 'salt'
Requires-Dist: jinja2>=3.1.6; extra == 'salt'
Requires-Dist: lxml>=6.0.1; extra == 'salt'
Requires-Dist: pyastrosalt>=0.2.2; extra == 'salt'
Description-Content-Type: text/markdown

# AEONlib

A suite of modules to enable TDA/MMA observations

[code](https://github.com/AEONplus/AEONlib)

[issues](https://github.com/AEONplus/AEONlib/issues)

# Configuration

Many of the facilities and services accessed by AEONlib require specific configuration such
as api keys, urls, etc. All configuration can be supplied by either supplying a .env file or
setting environmental variables in the execution environment.

Example .env file:

```
AEON_LCO_API_ROOT="https://observe.lco.global/api"
AEON_LCO_TOKEN="my-api-token"
```

Or set environmental variables via the shell:

```bash
export AEON_LCO_API_ROOT="https://observe.lco.global/api"
export AEON_LCO_TOKEN="my-api-token"
```

All configuration keys are prefixed with AEON_ to prevent conflicts. See the documentation for
each service to see which configuration keys are available, or check
[conf.py](src/aeonlib/conf.py)

Environmental variables take precedence over .env files. See the
[pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) documentation
for more details.

# Testing

This project uses [pytest](https://docs.pytest.org/) to run tests:

```bash
pytest
```

Some tests are marked as `online`. These tests make real http requests in order
to test interfaces with various services. To run them:

```bash
pytest -m online
```

A subset of `online` tests are marked as `side_effect`. These are tests that change data on remote
systems. For example, a test might be testing creating new observation requests, or updating the
status of one. You might want to disable these:

```bash
pytest -m "not side_effect"
```

CI does not run tests marked as online.

## Viewing logs during tests

Aeonlib turns on the Pytest
[Live Logging](https://docs.pytest.org/en/stable/how-to/logging.html#live-logs) feature.
By default any logging calls with a level above `WARNING` will be displayed to the console
during the test run. It may be helpful to display debug logging, especially if debugging remote
facilities or services:

```bash
pytest -m online --log-cli-level=debug
```

# Linting

All code is formatted via [ruff](https://astral.sh/ruff).

# Code Generation

Las Cumbres Observatory [instrument classes](src/aeonlib/ocs/lco/instruments.py)
are generated via the [generator.py](codegen/lco/generator.py) script. This script
takes as input the [OCS instruments api](https://observe.lco.global/api/instruments/)
in order to produce definitions of all instruments currently available on the network.

To update the definitions, first make sure you have installed the `codegen` dependency
group:

```bash
uv sync --group codegen  # or poetry install --with codegen
```

This ensures regular users of the library do not need to install these dependencies.

The `generate.py` script takes as input JSON as produced by the instruments endpoint:

```bash
codegen/lco/generator.py {facility} instruments.json
```

Or directly from stdin using a pipe:

```bash
curl https://observe.lco.global/api/instruments/ | codegen/lco/generator.py {facility}
```

If the output looks satisfactory, you can redirect the output to overwrite the
LCO instruments definition file:

```bash
curl https://observe.lco.global/api/instruments/ | codegen/lco/generator.py {facility} > src/aeonlib/ocs/lco/instruments.py
```

# Supported Facilities

This list is a work in progress.

## Las Cumbres Observatory (LCO)

### Dependency group

Las Cumbres Observatory requires no additional dependency groups to be installed.

### Configuration Values

See [configuration](#configuration) for instructions on setting these values.

```python
lco_token: str = ""
lco_api_root: str = "https://observe.lco.global/api/"
```

### Helpful links

* [LCO Observation Portal](https://observe.lco.global/)
* [LCO Developer Documentation](https://developers.lco.global/)
* [OCS API Documentation](https://observatorycontrolsystem.github.io/api/observation_portal/)

## SOAR

SOAR is functionally the same as LCO, but has its own set of instruments and can be configured separately.

### Dependency group

SOAR requires no additional dependency groups to be installed.

### Configuration Values

See [configuration](#configuration) for instructions on setting these values.

```python
soar_token: str = ""
soar_api_root: str = "https://observe.lco.global/api/"
```

Note: the soar API token will default to the same value as lco_token, if it is set.

## BLANCO

BLANCO is functionally the same as LCO, but has its own set of instruments and can be configured separately.

### Dependency group

BLANCO requires no additional dependency groups to be installed.

### Configuration Values

See [configuration](#configuration) for instructions on setting these values.

```python
blanco_token: str = ""
blanco_api_root: str = "https://observe.lco.global/api/"
```

Note: the blanco API token will default to the same value as lco_token, if it is set.

## ESO (European Southern Observatory)

Full documentation: TODO

### Dependency Group

To use the ESO facility, you must install the `eso` group:

```bash
pip install aeonlib[eso]
uv sync --extra eso
poetry install --with eso
```

### Configuration Values

See [configuration](#configuration) for instructions on setting these values.

```python
eso_environment: str = "demo"
eso_username: str = ""
eso_password: str = ""
```

### Helpul links

* [ESO Phase 2 API](https://www.eso.org/sci/observing/phase2/p2intro/Phase2API.html)
* [ESO Phase 2 Demo Application](https://www.eso.org/p2demo/home)

## LT (Liverpool Telescope)

### Dependency Group

To use the LT facility, you must install the `lt` group:

```bash
pip install aeonlib[lt]
uv sync --extra lt
poetry install --with lt
```

### Configuration Values

See [configuration](#configuration) for instructions on setting these values.

```python
lt_username: str = ""
lt_password: str = ""
lt_host: str = ""
lt_port: str = ""
```

### Helpful links

* [LT Phase 2 Information](https://telescope.livjm.ac.uk/PropInst/Phase2/)

## SAAO (South African Astronomical Observatory)

### Configuration Values

```python
    saao_token: str = ""
saao_api_root: str = "https://ocsio.saao.ac.za/api/"
```

### Helpful links

* [SAAO Observatory Control System](https://ocsio.saao.ac.za/create)

## SALT (Southern African Large Telescope)

### Dependency Group

To use the SALT facility, you must install the `salt` group:

```bash
pip install aeonlib[salt]
uv sync --extra salt
poetry install --with salt
```

### Configuration values

See [configuration](#configuration) for instructions on setting these values.

```python
salt_username: str = ""
salt_password = ""
```

The username and password are those you would use for the [SALT Web Manager](https://www.salt.ac.za/wm/).
