Metadata-Version: 2.4
Name: jump2-client
Version: 0.1.0
Summary: Jump 2.0 Python client — standalone, pip-installable, works in JupyterHub or locally.
Project-URL: Repository, https://github.com/California-Planet-Search/jump2
Project-URL: Documentation, https://github.com/California-Planet-Search/jump2/blob/main/docs/CLIENT.md
Author: California Planet Search
License: MIT
License-File: LICENSE
Keywords: api-client,astronomy,jump2,jupyter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.11
Requires-Dist: pandas>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlglot>=25.0.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pandas-stubs; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# jump2-client

Standalone Python client for the [Jump 2.0](https://github.com/keck-community/jump2) astronomical data portal.

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

## Install

```bash
pip install jump2-client
# or, from source:
cd client && uv sync
```

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

## Quick start

```python
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

```python
# 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

```python
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`](../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.
