Isodrome Python SDK and CLI

isodrome is the official Python package for Isodrome, and installs the iso command line.

Install

pipx install isodrome        # or: uv tool install isodrome, or pip install isodrome

Getting started

iso login                                    # signs in with your browser and saves a key
iso feed create weather                      # events are timed when they arrive
iso feed push weather --data '{"temperature": 18.5, "city": "Dublin"}'
iso feed query weather --since 1h
iso feed tail weather                        # the last 10 events, then new ones live

Events are JSON objects. A feed times each event when it arrives, unless created with --time-field FIELD to use a time carried in the events (needed for late data and meaningful as-of queries), and with --key FIELD keeps the newest event per key for iso feed latest. iso feed push reads --data, --file (JSON Lines, a JSON array, or one object) or standard input, and prints every rejected event and why. Pushing the same file twice is recognised and not written twice (within the server's 15-minute window).

Commands

iso <command> --help describes each one.

Feeds from other organizations

A feed is named FEED (in the namespace in use), NAMESPACE/FEED, or ORGANIZATION/NAMESPACE/FEED. The last form reaches another organization's public feeds, such as Isodrome's open data, which any signed-in user can read but only their publisher can change:

iso feed list                                              # yours, then public ones from others
iso feed show isodrome/public/met_eireann_point_forecast   # with its source, licence and attribution
iso feed latest isodrome/public/met_eireann_point_forecast -c location -c temperature.value
iso namespace use isodrome/public                          # then refer to its feeds by name alone

When a feed's source asks for credit, iso prints the attribution (on stderr) with the data.

Configuration and profiles

iso keeps its settings in ~/.config/isodrome/config.toml (mode 0600, as it holds API keys). Each profile has an endpoint, a key and a namespace; iso login signs in to the cloud (https://stg.api.isodrome.ai for now). A local server has no browser sign-in, so give it its key:

iso --profile local login --endpoint http://localhost:7470 --api-key iso_...
iso profile use local          # or pass --profile local per command

ISODROME_PROFILE, ISODROME_ENDPOINT and ISODROME_API_KEY override the configuration.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest                                       # unit tests, against an in-process fake server

The API client in src/isodrome/v1 is generated from proto/isodrome/v1/isodrome.proto, a copy of the server's. After the server's API changes, with isodrome-server checked out next to this repository (or ISODROME_SERVER=path):

scripts/sync_proto.sh             # copy the proto and regenerate
scripts/sync_proto.sh --check     # what CI runs: fails if either is out of date

End-to-end tests run the CLI against a real server:

docker compose -f tests/e2e/docker-compose.yml up -d --wait   # ISODROME_SERVER_IMAGE=… for another image
export ISODROME_E2E_OTHER_KEY=$(docker compose -f tests/e2e/docker-compose.yml exec -T isodrome-server \
  isodrome-server create-organization other | awk '/admin key:/ {print $3}')   # for the public-feed test
ISODROME_E2E_ENDPOINT=http://localhost:7470 pytest -m e2e tests/e2e

Releases: publishing a GitHub release builds the package and uploads it to PyPI.