eolas-data 1.3.22__tar.gz → 1.4.0__tar.gz

{eolas_data-1.3.22 → eolas_data-1.4.0}/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to `eolas-data` are recorded here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 1.4.0
+
+### Added
+
+- **`Client.preview(name)`** — up to 10 sample rows via the unauthenticated
+  `/preview` endpoint. No API key required, no rate-limit cost, geometry hidden.
+  `eolas datasets preview` now uses it instead of burning an authenticated,
+  rate-limited `/data` call (DRIFT-5).
+- **`dimensions=` filter on `get()`** and `eolas get --dimensions` — a
+  case-insensitive substring filter on dimension columns, applied server-side on
+  the live `/data` path (the filter was live in prod but exposed by no client;
+  DRIFT-4).
+
 ## 1.3.22
 
 Network-hardening + correctness release, addressing findings from the

{eolas_data-1.3.22 → eolas_data-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eolas-data
-Version: 1.3.22
+Version: 1.4.0
 Summary: Python client for the eolas.fyi statistical data API (NZ + OECD; Australia on roadmap)
 Project-URL: Homepage, https://eolas.fyi
 Project-URL: Documentation, https://docs.eolas.fyi/

{eolas_data-1.3.22 → eolas_data-1.4.0}/eolas_data/__init__.py

@@ -26,7 +26,7 @@ from .exceptions import (
 try:
     __version__ = _pkg_version("eolas-data")
 except PackageNotFoundError:  # pragma: no cover - uninstalled source checkout
-    __version__ = "1.3.22"
+    __version__ = "1.4.0"
 
 __all__ = [
     "Client",

{eolas_data-1.3.22 → eolas_data-1.4.0}/eolas_data/cli.py

@@ -320,14 +320,18 @@ def datasets_info(
 def datasets_preview(
     name: str,
     limit: int = typer.Option(
-        10, "--limit", "-n", min=1, max=1000, help="Rows to preview."
+        10, "--limit", "-n", min=1, max=10, help="Rows to preview (max 10)."
     ),
     json_out: bool = typer.Option(False, "--json"),
     api_key: Optional[str] = typer.Option(None, "--api-key"),
 ) -> None:
-    """Preview the most recent N rows of a dataset."""
+    """Preview up to 10 sample rows of a dataset.
+
+    Uses the unauthenticated ``/preview`` endpoint: no rate-limit cost and no
+    live-data query. For real data use ``eolas get``.
+    """
     try:
-        df = _client(api_key).get(name, limit=limit)
+        df = _client(api_key).preview(name, limit=limit)
     except EolasError as e:
         _bail(str(e), _exit_for(e))
 
@@ -368,6 +372,11 @@ def get_cmd(
     out: Optional[Path] = typer.Option(
         None, "--out", "-o", help="Write to file. Default: stdout."
     ),
+    dimensions: Optional[str] = typer.Option(
+        None,
+        "--dimensions",
+        help="Case-insensitive substring filter on dimension columns, e.g. 'auckland'.",
+    ),
     api_key: Optional[str] = typer.Option(None, "--api-key"),
 ) -> None:
     """Fetch a dataset and write rows to stdout or a file.
@@ -377,6 +386,7 @@ def get_cmd(
         eolas get nz_cpi --format csv > cpi.csv
         eolas get nz_cpi --start 2020-01-01 --format json | jq '.[].value'
         eolas get sa2_2023 --format parquet --out sa2.parquet
+        eolas get building_consents --dimensions auckland --format csv
     """
     fmt = fmt.lower()
     if fmt not in ("csv", "json", "parquet"):
@@ -388,7 +398,9 @@ def get_cmd(
         )
 
     try:
-        df = _client(api_key).get(name, start=start, end=end, limit=limit)
+        df = _client(api_key).get(
+            name, start=start, end=end, limit=limit, dimensions=dimensions
+        )
     except EolasError as e:
         _bail(str(e), _exit_for(e))
 

{eolas_data-1.3.22 → eolas_data-1.4.0}/eolas_data/client.py

@@ -2262,6 +2262,36 @@ class Client:
     # Core data fetch
     # ------------------------------------------------------------------
 
+    def preview(
+        self,
+        name: Union[str, "DatasetName"],
+        *,
+        limit: int = 10,
+    ) -> pd.DataFrame:
+        """Return up to 10 sample rows via the unauthenticated ``/preview`` endpoint.
+
+        A cheap browser-style peek: **no API key required**, it does **not** count
+        against your rate limit, and geometry/WKT columns are hidden server-side
+        (so it stays fast even on large geospatial tables). The server caps the
+        response at 10 rows regardless of ``limit``. For real data use :meth:`get`,
+        :meth:`download`, or :meth:`download_bulk`.
+
+        Args:
+            name: Dataset identifier, e.g. ``"nz_cpi"``.
+            limit: Client-side cap on the returned rows (``<= 10``; the server
+                never returns more than 10).
+
+        Returns:
+            A pandas ``DataFrame`` of the preview rows.
+        """
+        resp = self._raw_get(f"/v1/datasets/{name}/preview")
+        body = resp.json()
+        rows = body.get("rows", []) if isinstance(body, dict) else body
+        df = pd.DataFrame(rows)
+        if limit and len(df) > limit:
+            df = df.head(limit)
+        return df
+
     def get(
         self,
         name: Union[str, "DatasetName"],
@@ -2276,6 +2306,7 @@ class Client:
         envelope: bool = False,
         force: bool = False,
         progress: ProgressControl = None,
+        dimensions: Optional[str] = None,
     ) -> Dataset:
         """Fetch dataset rows as a pandas (or polars / geopandas) DataFrame.
 
@@ -2321,6 +2352,10 @@ class Client:
             progress: Control bulk download/read progress when auto-routed to
                     :meth:`get_local`. ``None`` auto-detects TTY; ignored on the
                     live API path.
+            dimensions: Case-insensitive substring filter on the dataset's
+                    dimension columns (e.g. ``"auckland"``). Applied server-side
+                    on the live ``/data`` path; passing it forces the live path
+                    (the bulk cache has no per-request dimension filter).
 
         Returns:
             A :class:`Dataset` (pandas DataFrame subclass), a polars DataFrame
@@ -2379,6 +2414,7 @@ class Client:
             and format == "json"
             and not envelope
             and not as_arrow
+            and not dimensions  # bulk cache has no per-request dimension filter
         ):
             # Narrow the swallow to the ROUTING DECISION only (metadata lookup +
             # predicates). A failure there legitimately falls through to the live
@@ -2427,6 +2463,8 @@ class Client:
             params["start"] = start
         if end:
             params["end"] = end
+        if dimensions:
+            params["dimensions"] = dimensions
 
         fetch_limit, user_limit = resolve_fetch_limit(limit)
         # Positive limits on large/geo datasets must be sent to the API — the

{eolas_data-1.3.22 → eolas_data-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "eolas-data"
-version = "1.3.22"
+version = "1.4.0"
 description = "Python client for the eolas.fyi statistical data API (NZ + OECD; Australia on roadmap)"
 readme = "README.md"
 license = { text = "MIT" }

eolas_data-1.4.0/tests/test_preview_dimensions.py

@@ -0,0 +1,82 @@
+"""Tests for Client.preview() (DRIFT-5) and get(dimensions=) (DRIFT-4)."""
+
+from __future__ import annotations
+
+import pytest
+import responses as resp_lib
+
+from eolas_data import Client
+
+BASE = "https://api.eolas.fyi"
+
+
+@pytest.fixture()
+def client():
+    return Client("eolas_testkey123", base_url=BASE)
+
+
+# ---- DRIFT-5: preview ------------------------------------------------------
+
+
+@resp_lib.activate
+def test_preview_hits_unauthenticated_endpoint(client):
+    rows = [{"date": "2024-01-01", "value": i} for i in range(10)]
+    resp_lib.add(
+        resp_lib.GET,
+        f"{BASE}/v1/datasets/nz_cpi/preview",
+        json={"rows": rows, "hidden_columns": ["geometry_wkt"]},
+    )
+    df = client.preview("nz_cpi")
+    assert len(df) == 10
+    assert list(df.columns) == ["date", "value"]
+    # It must use /preview, never the rate-limited /data path.
+    urls = [c.request.url for c in resp_lib.calls]
+    assert any(u.endswith("/nz_cpi/preview") for u in urls)
+    assert not any(u.endswith("/data") or "/data?" in u for u in urls)
+
+
+@resp_lib.activate
+def test_preview_caps_at_limit(client):
+    rows = [{"value": i} for i in range(10)]
+    resp_lib.add(
+        resp_lib.GET,
+        f"{BASE}/v1/datasets/nz_cpi/preview",
+        json={"rows": rows, "hidden_columns": []},
+    )
+    assert len(client.preview("nz_cpi", limit=3)) == 3
+
+
+# ---- DRIFT-4: dimensions filter --------------------------------------------
+
+
+@resp_lib.activate
+def test_get_passes_dimensions_param(client):
+    resp_lib.add(
+        resp_lib.GET,
+        f"{BASE}/v1/datasets/building_consents/data",
+        json={"data": [{"region": "Auckland", "value": 1}]},
+    )
+    client.get("building_consents", dimensions="auckland")
+    data_reqs = [
+        c
+        for c in resp_lib.calls
+        if c.request.url.endswith("/data") or "/data?" in c.request.url
+    ]
+    assert data_reqs, "expected a /data request"
+    assert any("dimensions=auckland" in c.request.url for c in data_reqs)
+
+
+@resp_lib.activate
+def test_dimensions_forces_live_path_no_bulk_route(client):
+    # With dimensions set, get() must NOT auto-route to the bulk cache (which has
+    # no per-request dimension filter). A /data hit proves the live path ran.
+    resp_lib.add(
+        resp_lib.GET,
+        f"{BASE}/v1/datasets/nz_addresses/data",
+        json={"data": [{"suburb": "Ponsonby"}]},
+    )
+    client.get("nz_addresses", dimensions="ponsonby")
+    assert any(
+        c.request.url.endswith("/data") or "/data?" in c.request.url
+        for c in resp_lib.calls
+    )