panoptes-utils 0.2.55

Astronomical utilities for PANOPTES

PANOPTES Utilities

Utility functions for use within the Project PANOPTES ecosystem and for general astronomical processing.

This library defines a number of modules that contain useful functions as well as a few services.

Install

To install type:

pip install panoptes-utils

Full options for install:

pip install "panoptes-utils[config,docs,images,telemetry]"

See the full documentation at: https://panoptes-utils.readthedocs.io

Dependencies

There are a few system dependencies depending on what functionality you will be using.

In particular, the plate solving requires astrometry.net and the appropriate index files.

Use the following on a debian-based system (e.g. Ubuntu) to easily install all dependencies:

apt-get update && apt-get install --no-install-recommends --yes \
  libffi-dev libssl-dev \
  astrometry.net astrometry-data-tycho2 \
  dcraw exiftool libcfitsio-dev libcfitsio-bin \
  libfreetype6-dev libpng-dev libjpeg-dev libffi-dev

Command Line

The panoptes-utils command line tool is available for use with subcommands corresponding to the modules in this library. Currently, the only implemented subcommand is image, which includes commands for converting cr2 files into jpg and/or fits files as well as for plate-solving fits images.

The panoptes-utils image watch <path> command will watch the given path for new files and convert them to jpg and/or fits files as they are added.

The telemetry server is also available under the main CLI as panoptes-utils telemetry.

See panoptes-utils --help, panoptes-utils image --help, and panoptes-utils telemetry --help for details.

Config Server

There is a simple key-value configuration server available as part of the module.

After installing with the config option as above, type:

panoptes-config-server run --config-file <path-to-file.yaml>

Environment Variables

The config server and client use the following environment variables:

Variable	Description	Default
PANOPTES_CONFIG_HOST	The host address for the config server.	localhost
PANOPTES_CONFIG_PORT	The port number for the config server.	6563
PANOPTES_CONFIG_FILE	The YAML configuration file to load (used by CLI).
PANOPTES_DEBUG	Enables verbose logging if set.	False

Telemetry Server

After installing with the telemetry option as above, start the server:

panoptes-utils telemetry run

The public telemetry model is intentionally simple: there is one telemetry feed, and start_run() optionally activates a run context. When a run is active, subsequent events are automatically associated with that run and stamped with meta["run_id"].

Example local workflow with Python:

from panoptes.utils.telemetry import TelemetryClient

client = TelemetryClient()

print(client.ready())

# Before start_run(), events are recorded without any active run context.
client.post_event("weather", {"sky": "clear", "wind_mps": 2.1}, meta={"source": "demo"})

# start_run() activates the run context for subsequent events.
client.start_run(run_id="001")
event = client.post_event("status", {"state": "running"})
print(event["meta"]["run_id"])
client.stop_run()

# Or let the server create the next run automatically.
next_run = client.start_run()
print(next_run["run_id"], next_run["run_dir"])

print(client.current()["current"])

client.stop_run()
client.shutdown()

For server internals, HTTP API examples, and environment variables, see the Telemetry Server documentation.

Development with UV

This project uses UV for fast Python package and environment management with modern PEP 735 dependency groups.

Prerequisites:

• Python 3.12+
• UV: https://docs.astral.sh/uv/ (install via curl -LsSf https://astral.sh/uv/install.sh | sh or pipx install uv).

Basic workflow:

• Create and sync a dev environment with all dependencies:

  # Install all optional extras and dev dependencies (recommended for development)
  uv sync --all-extras --group dev
  
  # Or install only base dependencies
  uv sync
  
  # Activate the virtual environment
  source .venv/bin/activate
  # or run commands without activating using `uv run ...`
  

• Install specific dependency groups as needed:

  # Install testing dependencies
  uv sync --group testing
  
  # Install linting tools
  uv sync --group lint
  
  # Install all dev dependencies (includes testing + lint)
  uv sync --group dev
  

• Install specific optional extras as needed (choose any):

  # Examples: config, images, docs, examples
  uv sync --extra config --extra images --extra docs
  
  # Or install all extras
  uv sync --all-extras
  

• Run tests:

  # All tests with coverage, using pytest options from pyproject.toml
  uv run pytest
  
  # Single test file
  uv run pytest tests/test_utils.py
  

• Lint / style checks:

  # Lint with Ruff
  uv run ruff check .
  
  # Auto-fix linting issues
  uv run ruff check --fix .
  
  # Format code with Ruff
  uv run ruff format .
  
  # Check formatting without making changes
  uv run ruff format --check .
  

• Build the package (wheel and sdist):

  uv build
  

• Run the CLI locally (Typer app):

  uv run panoptes-utils --help
  

• Versioning: Version is derived from git tags via setuptools-scm. To produce a new version, create and push a tag (e.g., v0.1.0).

[Testing]

To test the software, prefer running via UV so the right environment and options are used:

uv run pytest

By default all tests will be run. If you want to run one specific test, give the specific filename as an argument to pytest:

uv run pytest tests/test_mount.py