Skip to main content

AEONlib

A suite of modules to enable TDA/MMA observations

code

issues

Purpose

An increasing amount of observatories and instruments related to time-domain astronomy are coming online with programmatic abilities from the start. While most of these APIs are unique, AEONLib attempts to unify and abstract as much as possible. Thus AEONLib can be thought of as a suite of client libraries with shared structure and code. The goal is to make writing observing programs for multiple facilities as easy and intuitive as possible.

AEONLib is not a "write once, observe everywhere" meta-language. Every observing facility provides unique opportunities to do science and it is not the goal of AEONLib to paper over differences in order to achieve homogeneity.

For concrete examples, see the iPython notebooks in the examples/ directory. The tests/ are also illustrative.

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:

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

Environmental variables take precedence over .env files. See the pydantic-settings documentation for more details.

Testing

This project uses pytest to run tests:

pytest

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

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:

pytest -m "not side_effect"

CI does not run tests marked as online.

Viewing logs during tests

Aeonlib turns on the Pytest Live Logging 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:

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

Linting

All code is formatted via ruff.

Code Generation

Las Cumbres Observatory instrument classes are generated via the generator.py script. This script takes as input the OCS instruments api 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:

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:

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

Or directly from stdin using a pipe:

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:

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 for instructions on setting these values.

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

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 for instructions on setting these values.

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 for instructions on setting these values.

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:

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

Configuration Values

See configuration for instructions on setting these values.

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

LT (Liverpool Telescope)

Dependency Group

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

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

Configuration Values

See configuration for instructions on setting these values.

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

SAAO (South African Astronomical Observatory)

Configuration Values

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

SALT (Southern African Large Telescope)

Dependency Group

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

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

Configuration values

See configuration for instructions on setting these values.

salt_username: str = ""
salt_password = ""

The username and password are those you would use for the SALT Web Manager.

Gemini

Dependency Group

The use the Gemini facility, you must install the gemini group:

pip install aeonlib[gemini]
uv sync --extra gemini
poetry install --with gemini

Configuration Values

  gemini_token: str = ""
  gemini_environment: Literal["production", "development"] = "production"
  gemini_debug: bool = False

The GPP client selects an environment automatically depending on which package version is installed. We override that here so the environment can be configured, otherwise it would be necessary to install a different package to test/deploy.

gpp-client documentation

GPP Client direct access

This module installs gpp-client, which is already a fully-features client for gemini. Thus AEONLib acts as a thin wrapper with some convenience functions. The gpp client can be accessed directly via facility.client

Canada France Hawaii Telescope (CFHT)

Configuration values

cfht_api_root: str = "https://api-stage.cfht.hawaii.edu/"
cfht_access_token: str = ""

Kealahou Phase 1 & 2 tool - staging

Metadata

Release files for aeonlib 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aeonlib 0.3.2
File Size Uploaded Provenance Actions
aeonlib-0.3.2.tar.gz 346.1 kB With provenance Details for aeonlib-0.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aeonlib 0.3.2
File Interpreter ABI Platform Actions
aeonlib-0.3.2-py3-none-any.whl Python 3 none any Details for aeonlib-0.3.2-py3-none-any.whl

Total release size: 473.8 kB

Release files / aeonlib-0.3.2.tar.gz

Download URL aeonlib-0.3.2.tar.gz
Size 346.1 kB
Tags Source
SHA-256 checksum
How to use checksums
37390bc0a57535517940b74a49bdff52a428450fbcac96362c91920e2445c27e
BLAKE2b-256 checksum
How to use checksums
142b3edda7aa6cb5f35494c7fc7f63afa09f0a5d3aa10e9981b85e2c86bc3567
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / aeonlib-0.3.2-py3-none-any.whl

Download URL aeonlib-0.3.2-py3-none-any.whl
Size 127.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e3360fe2db91b23b1552f95d7e597d3428fe5247d33fc5476b449310ba3f191e
BLAKE2b-256 checksum
How to use checksums
1a13bd05428d0b4a3ccdf6ba4ba85e186b8a0d7c622c3ffd72a66eec4c8e755d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for aeonlib 0.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aeonlib-0.3.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page