jump2-client 0.2.0

Jump 2.0 Python client — standalone, pip-installable, works in JupyterHub or locally.

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 jump2-client
# or, from source:
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://jump2.example.org", api_key="jump2_live_…")

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"])

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.