jump2-client

Standalone Python client for the Jump 2.0 astronomical data portal.

Works in JupyterHub (zero-config — credentials injected at spawn) or locally with an API key.

Install

pip install -U --extra-index-url https://cannon.caltech.edu/client/simple/ jump2-client
# unreleased features (needs GitHub repo access):
pip install "git+https://github.com/California-Planet-Search/jump2.git#subdirectory=client"
# or, from a checkout:
cd client && uv sync

Requirements: Python ≥ 3.11, requests, sqlglot ≥ 25.0.

Quick start

from jump2_client import Client

# In JupyterHub — no setup needed:
c = Client()
c.status()    # connectivity + ACL check
c.discover()  # browse the API endpoint catalogue
c.docs        # print cheat-sheet

# Locally:
c = Client(base_url="https://cannon.caltech.edu", api_key="jump2_live_…")

Passwordless command line

pip install jump2-client jump2-cli
jump2 scripts login                        # asks for your password, once
jump2 scripts upload tonight.txt -i hires  # and never again

login mints an API key scoped to the one token the command needs and stores it at mode 0600 in ~/.config/jump2/credentials.toml; every later Client() finds it with no environment set. Order of precedence stays argument → environment → file, so JupyterHub's injected key always wins.

Data access

# Raw SQL → DataFrame (RLS enforced server-side):
df = c.data.query("SELECT url_slug, vmag FROM core_star ORDER BY vmag LIMIT 20")

# Fluent query builder:
df = (c.data.table("core_star")
        .select("url_slug", "vmag", "ra", "dec")
        .where(vmag__lt=8)
        .order_by("vmag")
        .limit(25)
        .df())

# Stars and observations:
for star in c.data.stars():
    print(star["url_slug"])

Observing scripts

# Upload a starlist (needs the manage_scripts token). An existing name for the
# instrument is overwritten in place; the result says which happened.
c.scripts.upload("script_j344_n2.txt", instrument="hires")
c.scripts.print_list(instrument="hires")

Error handling

from jump2_client import AuthError, ValidationError, NotFoundError

try:
    df = c.data.query("SELECT * FROM bad_table")
except ValidationError as e:
    print(e.detail)  # server message
    print(e.hint)    # remediation hint

Full documentation

See docs/CLIENT.md in the jump2 repository for the complete reference: authentication modes, URL prefix convention, QueryBuilder operators, admin API, error model, and key regeneration flow.