relay-metis 0.1.0__tar.gz

relay_metis-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Ruff format
+        run: uv run ruff format --check --diff .
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Tests
+        run: uv run pytest tests/ -v
+
+      - name: Build sanity check
+        run: uv build

relay_metis-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,43 @@
+# Publishes relay-metis to PyPI via trusted publishing (OIDC) — no stored token.
+#
+# One-off setup on PyPI before the first release: add a "pending trusted
+# publisher" for project `relay-metis` with owner `relaytech-co`, repository
+# `metis-python-client`, workflow `publish.yaml`, environment `pypi`. The
+# first successful publish claims the project name atomically.
+#
+# Releasing = bump `version` in pyproject.toml, merge, then create a GitHub
+# Release (tag `v<version>`); this workflow does the rest.
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Check tag matches package version
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "Release tag ${GITHUB_REF_NAME} does not match pyproject version v${version}" >&2
+            exit 1
+          fi
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

relay_metis-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.pytest_cache/
+dist/
+.cursor/

relay_metis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Relay Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

relay_metis-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: relay-metis
+Version: 0.1.0
+Summary: Lightweight Python client for Metis, Relay's Cube-backed metrics layer.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# metis
+
+Lightweight Python client for Metis, Relay's Cube-backed metrics layer. Queries a Metis
+view and returns a typed, annotated pandas DataFrame — the metrics you see in dashboards,
+in a notebook, computed the same way.
+
+## Setup
+
+```bash
+export METIS_API_URL="https://<deployment>.cubecloudapp.dev"   # /cubejs-api/v1 optional
+export METIS_API_KEY="<pre-minted Cube API token>"
+```
+
+Both can also be passed explicitly: `MetisClient(url=..., api_key=...)` (constructor
+arguments win over the environment).
+
+## Usage
+
+```python
+from datetime import date
+from metis import MetisClient
+
+client = MetisClient()
+
+df = client.query(
+    "orders",
+    measures=["order_count", "revenue_sum"],
+    dimensions=["status"],
+    time_dimension="created_at",
+    granularity="day",
+    date_range=(date(2026, 8, 1), date(2026, 8, 31)),
+    filters={"is_priority": True},
+    order={"created_at": "asc"},
+)
+```
+
+Member names are unprefixed and scoped to the view; result columns come back
+prefix-stripped. Discovery:
+
+```python
+client.meta()  # one row per view/member: kind, type, title, description
+```
+
+Unknown views/members fail before the query is sent, with did-you-mean suggestions.
+
+### Filters
+
+The mapping form is sugar for equals/in (`None` means "is not set"):
+
+```python
+filters = {"status": ["shipped", "delivered"], "is_priority": True}
+```
+
+Anything richer takes raw Cube filter dicts (member names still unprefixed):
+
+```python
+filters = [{"member": "revenue_sum", "operator": "gt", "values": ["1000"]}]
+```
+
+### Dtypes
+
+Model-driven, never inferred from whichever values a result happens to contain:
+
+| Member | dtype |
+| --- | --- |
+| count / count_distinct measures | `Int64` (nullable) |
+| all other numeric measures | `float64` |
+| numeric dimensions, integer-typed at source | `Int64` (nullable) |
+| numeric dimensions, decimal-typed at source | `float64` |
+| booleans | `boolean` (nullable) |
+| time members | `datetime64` |
+
+Numeric dimensions are classified from the raw serialisation: integer columns always
+arrive as bare digit strings and classify correctly. Known caveat: a decimal-typed
+dimension (FLOAT64 or NUMERIC) whose result values are all whole also arrives as bare
+digits and reads as `Int64` until a decimal value appears. Override any column
+per-call: `dtypes={"weight_grams": "float64"}`.
+
+Query provenance (payload, Cube annotation, request time) is attached under
+`df.attrs["metis"]`.
+
+### Escape hatch
+
+```python
+client.load(
+    {"query": {...}, "cache": "must-revalidate"}
+)  # raw Cube REST payload -> raw dict
+```
+
+## Behaviour notes
+
+- Cache mode is hard-coded to `must-revalidate`: serves cached data while current,
+  never stale data.
+- Long-running queries are polled (Cube "Continue wait") within a wall-clock budget of
+  120s by default — raise `total_wait_budget_seconds` for heavy queries.
+- Transient errors retry up to 3 times with backoff; auth failures and query errors
+  fail immediately and loudly.

relay_metis-0.1.0/README.md

@@ -0,0 +1,97 @@
+# metis
+
+Lightweight Python client for Metis, Relay's Cube-backed metrics layer. Queries a Metis
+view and returns a typed, annotated pandas DataFrame — the metrics you see in dashboards,
+in a notebook, computed the same way.
+
+## Setup
+
+```bash
+export METIS_API_URL="https://<deployment>.cubecloudapp.dev"   # /cubejs-api/v1 optional
+export METIS_API_KEY="<pre-minted Cube API token>"
+```
+
+Both can also be passed explicitly: `MetisClient(url=..., api_key=...)` (constructor
+arguments win over the environment).
+
+## Usage
+
+```python
+from datetime import date
+from metis import MetisClient
+
+client = MetisClient()
+
+df = client.query(
+    "orders",
+    measures=["order_count", "revenue_sum"],
+    dimensions=["status"],
+    time_dimension="created_at",
+    granularity="day",
+    date_range=(date(2026, 8, 1), date(2026, 8, 31)),
+    filters={"is_priority": True},
+    order={"created_at": "asc"},
+)
+```
+
+Member names are unprefixed and scoped to the view; result columns come back
+prefix-stripped. Discovery:
+
+```python
+client.meta()  # one row per view/member: kind, type, title, description
+```
+
+Unknown views/members fail before the query is sent, with did-you-mean suggestions.
+
+### Filters
+
+The mapping form is sugar for equals/in (`None` means "is not set"):
+
+```python
+filters = {"status": ["shipped", "delivered"], "is_priority": True}
+```
+
+Anything richer takes raw Cube filter dicts (member names still unprefixed):
+
+```python
+filters = [{"member": "revenue_sum", "operator": "gt", "values": ["1000"]}]
+```
+
+### Dtypes
+
+Model-driven, never inferred from whichever values a result happens to contain:
+
+| Member | dtype |
+| --- | --- |
+| count / count_distinct measures | `Int64` (nullable) |
+| all other numeric measures | `float64` |
+| numeric dimensions, integer-typed at source | `Int64` (nullable) |
+| numeric dimensions, decimal-typed at source | `float64` |
+| booleans | `boolean` (nullable) |
+| time members | `datetime64` |
+
+Numeric dimensions are classified from the raw serialisation: integer columns always
+arrive as bare digit strings and classify correctly. Known caveat: a decimal-typed
+dimension (FLOAT64 or NUMERIC) whose result values are all whole also arrives as bare
+digits and reads as `Int64` until a decimal value appears. Override any column
+per-call: `dtypes={"weight_grams": "float64"}`.
+
+Query provenance (payload, Cube annotation, request time) is attached under
+`df.attrs["metis"]`.
+
+### Escape hatch
+
+```python
+client.load(
+    {"query": {...}, "cache": "must-revalidate"}
+)  # raw Cube REST payload -> raw dict
+```
+
+## Behaviour notes
+
+- Cache mode is hard-coded to `must-revalidate`: serves cached data while current,
+  never stale data.
+- Long-running queries are polled (Cube "Continue wait") within a wall-clock budget of
+  120s by default — raise `total_wait_budget_seconds` for heavy queries.
+- Transient errors retry up to 3 times with backoff; auth failures and query errors
+  fail immediately and loudly.

relay_metis-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "relay-metis"
+version = "0.1.0"
+description = "Lightweight Python client for Metis, Relay's Cube-backed metrics layer."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "pandas>=2.0",
+    "requests>=2.31",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metis"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.16.6",
+]
+
+[tool.ruff]
+target-version = "py311"
+src = ["src", "tests"]

relay_metis-0.1.0/src/metis/__init__.py

@@ -0,0 +1,5 @@
+from metis.client import MetisClient as MetisClient
+from metis.client import MetisConfigError as MetisConfigError
+from metis.client import MetisError as MetisError
+from metis.client import MetisQueryError as MetisQueryError
+from metis.client import MetisTimeoutError as MetisTimeoutError