Python Client

Omnicat ships a lightweight synchronous Python client that wraps the /api/v2 HTTP endpoints. Install omnicat as a Python package and import the client directly — no separate SDK required.

Installation

pip install omnicat
# or, if working from source:
uv sync

Quick start

from omnicat import Omnicat

client = Omnicat(address="http://localhost:8000")

# List all unique coordinate values across every MARS dimension
axes = client.axes()
# {'class': ['d1'], 'stream': ['oper', 'wave'], 'type': ['an', 'fc'], ...}

# Retrieve the full catalogue as arena JSON
qube = client.qube()

# Pass a plain dict to filter — no reserved-word workarounds needed
axes = client.axes({"class": "d1", "stream": "oper"})
subset = client.qube({"class": "d1", "stream": "oper"})

Constructor

Omnicat(
    address="http://localhost:8000",
    *,
    timeout=30.0,
    **httpx_kwargs,
)

Parameter	Type	Default	Description
address	str	"http://localhost:8000"	Root URL of the Omnicat server. Trailing slashes are stripped automatically.
timeout	float	30.0	Per-request timeout in seconds.
**httpx_kwargs			Any extra keyword arguments forwarded to httpx.Client.

Methods

axes(filters=None) → dict[str, list[str]]

Returns the unique coordinate values for every MARS dimension across the catalogue, optionally filtered to a sub-selection.

# Full catalogue axes
client.axes()
# {'class': ['d1'], 'stream': ['oper', 'wave'], ...}

# Filtered — plain dict, no reserved-word workarounds
client.axes({"class": "d1", "stream": ["oper", "wave"]})

Endpoint: GET /api/v2/axes/

---

qube(filters=None) → dict

Returns the Qube (or a filtered sub-Qube) as arena JSON.

# Full qube
client.qube()

# Filtered to a single class and stream
client.qube({"class": "d1", "stream": "oper"})

Endpoint: GET /api/v2/

---

select(filters=None) → dict

Explicitly selects a sub-Qube and returns it as arena JSON. Semantically equivalent to qube() but uses the dedicated /api/v2/select/ endpoint.

client.select({"class": "d1", "type": "an"})

Endpoint: GET /api/v2/select/

---

Filter arguments

All three methods accept an optional dict of MARS key=value constraints:

• Any key name — including Python reserved words like class, with no workarounds needed.
• Multi-value — pass a list for OR semantics: {"stream": ["oper", "wave"]} maps to ?stream=oper,wave.
• No filters — omit the argument (or pass None) to query the full catalogue.

Context manager

The client can be used as a context manager to ensure the underlying connection pool is closed when done:

with Omnicat(address="http://localhost:8000") as client:
    axes = client.axes()