Skip to content

Python SDK

The Python SDK at packages/py/skynet-sdk/ provides the shared schemas the rest of the Skynet Python stack uses — public-api, sky-node-gateway, SkyNode, services, and tools all import from it.

Status

The SDK is consumed in-tree by every Python project in the repo through uv editable installs (declared in the root pyproject.toml). It is not currently published to PyPI; external consumers install from a local checkout.

If you need a PyPI release, flag it. The package is structured for external publication but hasn't been pushed because in-tree consumers iterate too fast.

What's in it

The top-level skynet_sdk module (packages/py/skynet-sdk/skynet_sdk/) exposes four sub-packages:

schemas/ — shared Pydantic models

The heart of the SDK. Mirrors the database models from skynet_db where they need to round-trip over the wire, plus polymorphic discriminator helpers, plus message envelopes for WebSocket protocol.

Highlights:

  • The Device, Instrument, ObservationRequest, ObservationTask, Target, TargetPosition, Path, BrightnessModel, SpectralComponent, and TemporalComponent polymorphic families with their discriminators.
  • Filter, FilterWheelPosition, Observatory, Telescope, Site, OperationalConstraint, IPCamera — the core hub records SkyNode caches locally.
  • ws_protocol — the entire WebSocket message envelope (subscribe, publish, command, command result, snapshot families, direct request/response). Both public-api and the SDK consumers import these for typed WS handling.
  • device_snapshot, instrument_snapshot, telescope_snapshot — the snapshot shapes published over WS.

enums.py — shared enumerations

Single source of truth for cross-process enums:

  • DeviceType — the polymorphic discriminator for Device (mount, camera, filter_wheel, focuser, enclosure, …).
  • InstrumentTaskExecutionState, ExecutionPhase — task-executor state machine.
  • SkynetStorageBucket — MinIO bucket vocabulary.
  • ResourceType — generic resource discriminator used in events, notifications, and access grants.
  • StreamName, CommandStreamName, WsMessageKind — WebSocket protocol tokens.
  • TelescopeControlAuthority — remote / manual for SkyNode binding.

ephem/ — ephemeris and visibility

A small astronomy library, not part of the wire protocol but bundled because both the hub and SkyNode need it:

  • target_position.py — converts hub target records into time-tagged sky coordinates.
  • visibility.py — observability windows given a target, site, and time range.
  • provider.py — pluggable ephemeris provider interface (used by SkyNode's mount drivers).

radio/ — radio-observation helpers

  • path_generation.py — daisy / raster / on-off / track path generation given the request's configuration. Used by the radio task executors.

Installing in-tree

For any other Python project in the repo, add it as a dependency in the project's pyproject.toml:

dependencies = [
    "skynet-sdk",
]

[tool.uv.sources]
skynet-sdk = { workspace = true }

The root pyproject.toml sets up the workspace.

Using the schemas

from skynet_sdk.schemas import Observatory, Telescope, Device, ObservationRequest
from skynet_sdk.enums import DeviceType, TelescopeControlAuthority

# Polymorphic resources round-trip with their discriminator
device_json = {"deviceType": "camera", "id": 42, ...}
device = Device.model_validate(device_json)
# `device` is now typed as a Camera concrete class

For HTTP client behaviour against the public API — request bodies, auth, paginated responses — most Python integrations use httpx plus these schemas rather than a separate generated client. We may ship one in the future; for now the typed schemas plus a hand-rolled client is the common pattern.

Coordinate math

For coordinate transforms, prefer astropy.coordinates directly — the SDK doesn't wrap it. The TypeScript SDK has its own coordinate math because astropy isn't an option in the browser; on the Python side, use the upstream.

Building / publishing

# From the repo root
uv pip install -e packages/py/skynet-sdk

Will install the SDK editable into the active environment. For non-editable build:

uv build packages/py/skynet-sdk

writes a sdist + wheel to dist/.

Schema regeneration

The hand-authored schema files don't currently regenerate from the DB models the way the TS SDK regenerates from the OpenAPI spec — they're maintained as the authoritative protocol surface. When the DB model changes a corresponding SDK schema may need an update; the docs lint doesn't catch this yet but it's a planned check.