eolas-data 1.3.4__tar.gz → 1.3.13__tar.gz

{eolas_data-1.3.4 → eolas_data-1.3.13}/.github/workflows/smoke.yml

@@ -15,8 +15,8 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install package + dev deps
-        run: pip install -e ".[dev]"
+      - name: Install package + dev/geo deps (as users would)
+        run: pip install ".[dev,geo]"
 
       - name: Live smoke tests
         env:

{eolas_data-1.3.4 → eolas_data-1.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eolas-data
-Version: 1.3.4
+Version: 1.3.13
 Summary: Python client for the eolas.fyi statistical data API (NZ, Australia, OECD)
 Project-URL: Homepage, https://eolas.fyi
 Project-URL: Documentation, https://docs.eolas.fyi/
@@ -231,7 +231,7 @@ r    = client.sync_bulk("nz_cpi", path="nz_cpi.parquet")
 path = client.download_bulk("treasury_fiscal_spending", path="t.parquet")
 ```
 
-**Progress bars:** `download_bulk`, `sync_bulk`, and `get_local` all show a `tqdm` progress bar automatically in interactive terminals and VSCode notebooks, so 1+ GB files are never silent. Pass `progress=False` to suppress in scripts, or set `EOLAS_NO_PROGRESS=1` in the environment for a CI-wide escape hatch. The `--no-progress` flag does the same from the CLI.
+**Progress bars:** `get_local()` shows two phases in interactive sessions — a **download** byte bar while fetching from CDN, then a **read** spinner while Parquet/GeoParquet is loaded (often the slow part on multi-million-row geo datasets). Control with `progress=True` (both), `False` (neither), `"download"`, or `"read"`. Set `EOLAS_NO_PROGRESS=1` to suppress both in batch scripts. Cached files skip the download bar and print an informative message instead.
 
 CLI mirror: `eolas download <name>` for one-shot, `eolas sync <name> [--watch hourly]` for an incremental check. Full docs: [docs.eolas.fyi/bulk-downloads/](https://docs.eolas.fyi/bulk-downloads/).
 

{eolas_data-1.3.4 → eolas_data-1.3.13}/README.md

@@ -183,7 +183,7 @@ r    = client.sync_bulk("nz_cpi", path="nz_cpi.parquet")
 path = client.download_bulk("treasury_fiscal_spending", path="t.parquet")
 ```
 
-**Progress bars:** `download_bulk`, `sync_bulk`, and `get_local` all show a `tqdm` progress bar automatically in interactive terminals and VSCode notebooks, so 1+ GB files are never silent. Pass `progress=False` to suppress in scripts, or set `EOLAS_NO_PROGRESS=1` in the environment for a CI-wide escape hatch. The `--no-progress` flag does the same from the CLI.
+**Progress bars:** `get_local()` shows two phases in interactive sessions — a **download** byte bar while fetching from CDN, then a **read** spinner while Parquet/GeoParquet is loaded (often the slow part on multi-million-row geo datasets). Control with `progress=True` (both), `False` (neither), `"download"`, or `"read"`. Set `EOLAS_NO_PROGRESS=1` to suppress both in batch scripts. Cached files skip the download bar and print an informative message instead.
 
 CLI mirror: `eolas download <name>` for one-shot, `eolas sync <name> [--watch hourly]` for an incremental check. Full docs: [docs.eolas.fyi/bulk-downloads/](https://docs.eolas.fyi/bulk-downloads/).
 

{eolas_data-1.3.4 → eolas_data-1.3.13}/eolas_data/__init__.py

@@ -15,7 +15,7 @@ from .exceptions import (
     WatermarkExpired,
 )
 
-__version__ = "1.3.3"
+__version__ = "1.3.13"
 
 __all__ = [
     "Client",

{eolas_data-1.3.4 → eolas_data-1.3.13}/eolas_data/client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import contextlib
 import datetime
 import json
 import logging
@@ -7,7 +8,10 @@ import os
 import pathlib
 import sys
 from dataclasses import dataclass
-from typing import Optional, Union
+from typing import Literal, Optional, Union
+
+ProgressControl = Union[bool, str, None]
+ProgressPhase = Literal["download", "read"]
 
 import pandas as pd
 import requests
@@ -262,6 +266,36 @@ class Client:
             self._meta_cache[key] = self.info(name)
         return self._meta_cache[key]
 
+    def _apply_force(self, name: Union[str, "DatasetName"], force: bool) -> None:
+        if force:
+            self._meta_cache.pop(str(name), None)
+
+    def cache_clear(
+        self,
+        name: Optional[Union[str, "DatasetName"]] = None,
+        *,
+        cache_dir: Optional[Union[str, "pathlib.Path"]] = None,
+        format: Optional[str] = None,
+        files: bool = True,
+        meta: bool = True,
+    ) -> dict:
+        """Clear client-side cache (library files and/or session metadata).
+
+        See :func:`eolas_data.library.cache_clear` for details. Pass
+        ``force=True`` to :meth:`get_local` / :meth:`sync_bulk` to clear
+        metadata and re-download in one step.
+        """
+        from .library import cache_clear as _cache_clear
+
+        return _cache_clear(
+            None if name is None else str(name),
+            cache_dir=cache_dir,
+            format=format,
+            files=files,
+            meta=meta,
+            meta_cache=self._meta_cache if meta else None,
+        )
+
     def _attach_dataset_meta(
         self,
         result: "pd.DataFrame",
@@ -362,7 +396,7 @@ class Client:
         freshness: str = "auto",
         format: str = "parquet",
         path: Optional[Union[str, "pathlib.Path"]] = None,
-        progress: Optional[bool] = None,
+        progress: ProgressControl = None,
     ) -> "Union[pathlib.Path, bytes]":
         """Download a complete dataset as a single binary file.
 
@@ -387,14 +421,10 @@ class Client:
                 bytes. Pass a ``str`` or ``pathlib.Path`` to write to disk and
                 return the resolved path. Parent directories are created if
                 needed.
-            progress: Control the download progress bar.
-                ``None`` (default) auto-detects: bar shown when
-                ``sys.stdout.isatty()`` is True (interactive terminal or
-                notebook), hidden when piped or in CI.
-                ``True`` forces the bar on regardless (useful in log-tailing
-                scenarios).  ``False`` forces it off.  When ``path`` is
-                ``None`` (bytes mode) progress is always disabled — there is
-                no file path to label.
+            progress: Control the download progress bar (``"download"`` phase).
+                See :meth:`get_local` for the full selector vocabulary
+                (``"read"`` applies only to :meth:`get_local`). When ``path``
+                is ``None`` (bytes mode) progress is always disabled.
 
         Returns:
             ``pathlib.Path`` when ``path`` is set (the resolved, written path).
@@ -467,13 +497,13 @@ class Client:
         out = pathlib.Path(path).expanduser().resolve()
         out.parent.mkdir(parents=True, exist_ok=True)
 
-        show = self._resolve_show_progress(progress)
+        show = self._resolve_show_progress(progress, "download")
         resp = self._raw_bulk_get(bulk_path, params=params, stream=True)
         total = int(resp.headers.get("Content-Length", 0)) or None
         self._stream_to_file_with_progress(
             resp, out,
             total_bytes=total,
-            label=out.name,
+            label=f"Downloading {out.name}",
             show_progress=show,
         )
         return out
@@ -485,7 +515,8 @@ class Client:
         path: Union[str, "pathlib.Path"],
         format: str = "parquet",
         freshness: str = "auto",
-        progress: Optional[bool] = None,
+        progress: ProgressControl = None,
+        force: bool = False,
     ) -> SyncResult:
         """Incrementally sync a bulk dataset file — only re-download when the snapshot changes.
 
@@ -514,11 +545,12 @@ class Client:
                 ``"geoparquet"``.
             freshness: ``"auto"`` (default), ``"monthly"``, or ``"current"``.
                 Passed verbatim to the bulk endpoint.
-            progress: Control the download progress bar.
-                ``None`` (default) auto-detects via ``sys.stdout.isatty()``.
-                ``True`` forces the bar on; ``False`` forces it off.
-                When ``status="unchanged"`` no data is transferred so no bar
-                is shown regardless of this setting.
+            progress: Control the download progress bar (``"download"`` phase).
+                See :meth:`get_local` for the full selector vocabulary.
+                When ``status="unchanged"`` no download bar is shown; an
+                informative cached-file message is printed instead.
+            force: When ``True``, skip the sidecar unchanged fast path and
+                re-download even when the local snapshot id matches the server.
 
         Returns:
             A :class:`SyncResult` dataclass with ``status``,
@@ -566,6 +598,8 @@ class Client:
                 f"Unknown freshness {freshness!r}. Expected 'auto', 'monthly', or 'current'."
             )
 
+        self._apply_force(name, force)
+
         out = pathlib.Path(path).expanduser().resolve()
         sidecar = pathlib.Path(str(out) + ".eolas-meta.json")
 
@@ -602,10 +636,12 @@ class Client:
 
         # No-op fast path: snapshot hasn't changed AND file exists on disk.
         if (
-            prev is not None
+            not force
+            and prev is not None
             and prev.get("snapshot_id") == current_sid
             and out.exists()
         ):
+            print(f"Using cached {out.name} (up to date).", file=sys.stderr)
             return SyncResult(
                 status="unchanged",
                 previous_snapshot_id=prev.get("snapshot_id"),
@@ -617,14 +653,14 @@ class Client:
         # Download (atomic replace).
         out.parent.mkdir(parents=True, exist_ok=True)
         tmp = out.with_suffix(out.suffix + f".eolas-tmp-{os.urandom(4).hex()}")
-        show = self._resolve_show_progress(progress)
+        show = self._resolve_show_progress(progress, "download")
         try:
             resp = self._raw_bulk_get(bulk_path, params=params, stream=True)
             total = int(resp.headers.get("Content-Length", 0)) or None
             bytes_dl = self._stream_to_file_with_progress(
                 resp, tmp,
                 total_bytes=total,
-                label=out.name,
+                label=f"Downloading {out.name}",
                 show_progress=show,
             )
             if bytes_dl == 0:
@@ -677,6 +713,7 @@ class Client:
         *,
         format: str = "parquet",
         progress: Optional[bool] = None,
+        force: bool = False,
     ) -> SyncResult:
         """Incrementally sync a changelog-tier dataset via the /changes feed.
 
@@ -710,6 +747,7 @@ class Client:
                 changelog sync; other formats raise ``ValueError``.
             progress: Forwarded to :meth:`sync_bulk` for the baseline download
                 progress bar (``None`` auto-detects TTY).
+            force: When ``True``, re-baseline from a full bulk snapshot.
 
         Returns:
             A :class:`SyncResult` with ``sync_mode='changelog'``,
@@ -748,6 +786,7 @@ class Client:
 
         out = pathlib.Path(path).expanduser().resolve()
         sidecar_path = pathlib.Path(str(out) + ".eolas-meta.json")
+        self._apply_force(name, force)
 
         # Read sidecar.
         sidecar: Optional[dict] = None
@@ -758,7 +797,7 @@ class Client:
                 sidecar = None
 
         # Determine if we need a cold-start baseline.
-        needs_baseline = (
+        needs_baseline = force or (
             sidecar is None
             or sidecar.get("sync_mode") != "changelog"
             or sidecar.get("watermark_seq") is None
@@ -782,6 +821,7 @@ class Client:
                 format=fmt,
                 freshness="current",
                 progress=progress,
+                force=force,
             )
             baseline_snapshot_id = bulk_result.current_snapshot_id
 
@@ -844,6 +884,7 @@ class Client:
                 format=fmt,
                 freshness="current",
                 progress=progress,
+                force=force,
             )
             baseline_snapshot_id = bulk_result.current_snapshot_id
             high_seq = self._fetch_changes_seq_high(changes_url, since_seq=2**62)
@@ -948,6 +989,7 @@ class Client:
         format: str = "parquet",
         freshness: str = "auto",
         progress: Optional[bool] = None,
+        force: bool = False,
     ) -> SyncResult:
         """Unified sync dispatcher — keeps a local file current automatically.
 
@@ -973,6 +1015,7 @@ class Client:
             freshness: ``"auto"`` (default), ``"monthly"``, or ``"current"``. Only
                 used for the snapshot path (passed to :meth:`sync_bulk`).
             progress: Control the download progress bar.
+            force: Bypass local unchanged cache and re-sync from the server.
 
         Returns:
             A :class:`SyncResult`. The ``sync_mode`` field is ``"snapshot"`` or
@@ -996,7 +1039,7 @@ class Client:
         tier = meta.get("cdc_serving_tier", "snapshot") or "snapshot"
 
         if tier == "changelog":
-            return self.sync_changes(name, path, format=format, progress=progress)
+            return self.sync_changes(name, path, format=format, progress=progress, force=force)
         else:
             result = self.sync_bulk(
                 name,
@@ -1004,6 +1047,7 @@ class Client:
                 format=format,
                 freshness=freshness,
                 progress=progress,
+                force=force,
             )
             # Tag the result with sync_mode so callers don't need to inspect tier.
             result.sync_mode = "snapshot"
@@ -1159,28 +1203,73 @@ class Client:
     # ------------------------------------------------------------------
 
     @staticmethod
-    def _resolve_show_progress(progress: Optional[bool]) -> bool:
-        """Resolve the tri-state ``progress`` kwarg to a concrete bool.
-
-        Priority (highest first):
-        1. Explicit ``progress=True/False`` kwarg from the caller.
-        2. ``EOLAS_NO_PROGRESS=1`` environment variable — always suppresses.
-        3. Jupyter / IPython kernel detection — Jupyter wraps stdout in an
-           ``OutStream``, so ``sys.stdout.isatty()`` returns False even when
-           the user is clearly in an interactive notebook session. If
-           ``ipykernel`` is loaded (the standard signal used by tqdm itself),
-           we're in a notebook → show the bar; ``tqdm.auto`` then renders it
-           as an ipywidget (or text bar as fallback).
-        4. ``sys.stdout.isatty()`` auto-detection for plain terminals.
-        """
-        if progress is not None:
-            return bool(progress)
+    def _progress_auto_detect() -> bool:
+        """Whether progress feedback should show when ``progress`` is None."""
         if os.getenv("EOLAS_NO_PROGRESS", "").strip() in ("1", "true", "yes"):
             return False
         if "ipykernel" in sys.modules:
             return True
         return sys.stdout.isatty()
 
+    @staticmethod
+    def _resolve_progress_phases(progress: ProgressControl) -> dict[str, bool]:
+        """Map ``progress`` to download/read phase flags.
+
+        Accepts ``None``, ``True``/``False``, or ``"both"``, ``"download"``,
+        ``"read"``, ``"none"`` (and ``"all"`` as alias for ``"both"``).
+        """
+        if progress is False:
+            return {"download": False, "read": False}
+        if progress is True:
+            return {"download": True, "read": True}
+        if isinstance(progress, str):
+            key = progress.strip().lower()
+            table = {
+                "both": (True, True),
+                "all": (True, True),
+                "download": (True, False),
+                "read": (False, True),
+                "none": (False, False),
+            }
+            if key not in table:
+                raise ValueError(
+                    "progress must be True, False, None, or one of "
+                    "'both', 'download', 'read', 'none'."
+                )
+            d, r = table[key]
+            return {"download": d, "read": r}
+        auto = Client._progress_auto_detect()
+        return {"download": auto, "read": auto}
+
+    @staticmethod
+    def _resolve_show_progress(
+        progress: ProgressControl,
+        phase: ProgressPhase = "download",
+    ) -> bool:
+        """Resolve ``progress`` for one bulk phase (download or read)."""
+        return Client._resolve_progress_phases(progress)[phase]
+
+    @staticmethod
+    @contextlib.contextmanager
+    def _with_read_progress(label: str, show: bool):
+        """Indeterminate spinner while materialising a cached bulk file."""
+        if not show:
+            yield
+            return
+        import tqdm.auto
+
+        bar = tqdm.auto.tqdm(
+            total=1,
+            desc=f"Loading {label} from disk",
+            leave=False,
+            bar_format="{desc}…",
+        )
+        try:
+            yield
+        finally:
+            bar.update(1)
+            bar.close()
+
     @staticmethod
     def _stream_to_file_with_progress(
         resp: "requests.Response",
@@ -1796,7 +1885,8 @@ class Client:
         as_geo: Optional[bool] = None,
         as_arrow: bool = False,
         meta: bool = True,
-        progress: Optional[bool] = None,
+        progress: ProgressControl = None,
+        force: bool = False,
     ) -> "pd.DataFrame":
         """Download (or serve from cache) a whole dataset as a local DataFrame.
 
@@ -1833,7 +1923,16 @@ class Client:
             meta: When ``True`` (default), attach table/column metadata from
                 :meth:`info` (session-cached). Pass ``False`` to skip the extra
                 round-trip.
-            progress: Forwarded to :meth:`sync_bulk` (``None`` auto-detects TTY).
+            progress: Control progress for two phases: **download** (streaming
+                byte bar via :meth:`sync_bulk`) and **read** (spinner while
+                Parquet/GeoParquet is loaded into a DataFrame). ``None``
+                (default) enables both in interactive sessions. ``True``/``False``
+                force both on/off. Use ``"download"``, ``"read"``, ``"both"``,
+                or ``"none"`` for one phase only. Suppressed by
+                ``EOLAS_NO_PROGRESS=1``. Cached snapshots skip the download bar
+                and print an informative message instead.
+            force: Re-download the library file even when the sidecar says the
+                snapshot is current. See :meth:`cache_clear`.
 
         Returns:
             ``pd.DataFrame`` (tabular) or ``geopandas.GeoDataFrame`` (geo +
@@ -1856,6 +1955,7 @@ class Client:
             )
         # Resolve as_geo: None → True (auto) unless as_arrow overrides.
         resolved_as_geo = as_geo if as_geo is not None else (not as_arrow)
+        self._apply_force(name, force)
 
         # ---- resolve cache_dir -----------------------------------------------
         if cache_dir is not None:
@@ -1894,26 +1994,36 @@ class Client:
         file_path = cache_path / f"{name}{ext}"
 
         # ---- sync (download if needed, HEAD check if cached) -----------------
-        self.sync_bulk(name, path=file_path, format=fmt, freshness=freshness, progress=progress)
+        self.sync_bulk(
+            name, path=file_path, format=fmt, freshness=freshness,
+            progress=progress, force=force,
+        )
+
+        show_read = self._resolve_show_progress(progress, "read")
+        read_label = file_path.name
 
         # ---- read the local file into a DataFrame ----------------------------
         if as_arrow:
             import pyarrow.parquet as _pq
-            if fmt == "csv_gz":
-                import pyarrow as _pa
-                return _pa.Table.from_pandas(pd.read_csv(file_path), preserve_index=False)
-            return _pq.read_table(file_path)
+            with self._with_read_progress(read_label, show_read):
+                if fmt == "csv_gz":
+                    import pyarrow as _pa
+                    return _pa.Table.from_pandas(
+                        pd.read_csv(file_path), preserve_index=False,
+                    )
+                return _pq.read_table(file_path)
 
         def _read_bulk_file(path: pathlib.Path, bulk_fmt: str):
-            if bulk_fmt == "csv_gz":
-                return pd.read_csv(path)
-            if bulk_fmt == "geoparquet" and resolved_as_geo:
-                try:
-                    import geopandas as gpd
-                    return gpd.read_parquet(path)
-                except ImportError:
-                    pass
-            return pd.read_parquet(path)
+            with self._with_read_progress(read_label, show_read):
+                if bulk_fmt == "csv_gz":
+                    return pd.read_csv(path)
+                if bulk_fmt == "geoparquet" and resolved_as_geo:
+                    try:
+                        import geopandas as gpd
+                        return gpd.read_parquet(path)
+                    except ImportError:
+                        pass
+                return pd.read_parquet(path)
 
         try:
             result = _read_bulk_file(file_path, fmt)
@@ -1929,7 +2039,7 @@ class Client:
                 csv_path = cache_path / f"{name}{self._BULK_EXTENSIONS['csv_gz']}"
                 self.sync_bulk(
                     name, path=csv_path, format="csv_gz",
-                    freshness=freshness, progress=progress,
+                    freshness=freshness, progress=progress, force=force,
                 )
                 result = _read_bulk_file(csv_path, "csv_gz")
             else:
@@ -1952,6 +2062,7 @@ class Client:
         as_arrow: bool = False,
         meta: bool = True,
         envelope: bool = False,
+        force: bool = False,
     ) -> Dataset:
         """Fetch dataset rows as a pandas (or polars / geopandas) DataFrame.
 
@@ -2037,7 +2148,7 @@ class Client:
                 info_meta = self._info_cached(name)
                 if self._bulk_export_allowed(info_meta) and self._live_pull_blocked(info_meta):
                     result = self.get_local(
-                        name, as_geo=as_geo, as_arrow=False, meta=meta,
+                        name, as_geo=as_geo, as_arrow=False, meta=meta, force=force,
                     )
                     if engine == "polars":
                         try:

{eolas_data-1.3.4 → eolas_data-1.3.13}/eolas_data/library.py

@@ -39,6 +39,13 @@ _CONFIG_FILE = _CONFIG_DIR / "config.json"
 # Fallback cache directory (Step 5)
 _FALLBACK_DIR = pathlib.Path.home() / ".cache" / "eolas"
 
+# Bulk file extensions (mirrors Client._BULK_EXTENSIONS).
+_BULK_EXTENSIONS = {
+    "parquet":    ".parquet",
+    "csv_gz":     ".csv.gz",
+    "geoparquet": ".geo.parquet",
+}
+
 
 # ---------------------------------------------------------------------------
 # Public API
@@ -94,6 +101,92 @@ def library_clear() -> None:
     _remove_config_key("library_dir")
 
 
+def cache_clear(
+    name: Optional[str] = None,
+    *,
+    cache_dir: Optional[str | pathlib.Path] = None,
+    format: Optional[str] = None,
+    files: bool = True,
+    meta: bool = True,
+    meta_cache: Optional[dict] = None,
+) -> dict:
+    """Clear client-side cache for a dataset (or the whole library).
+
+    eolas-data caches at two client-only levels:
+
+    * **On-disk bulk files** in the library directory (Parquet/GeoParquet +
+      ``.eolas-meta.json`` sidecars) — cleared when ``files=True``.
+    * **Session metadata** (``Client._meta_cache`` / ``info()`` per dataset) —
+      cleared when ``meta=True`` and ``meta_cache`` is the client's dict.
+
+    Does not contact the API. Use :meth:`Client.get_local` with ``force=True``
+    to clear and re-download in one step.
+
+    Args:
+        name: Dataset identifier. ``None`` sweeps the whole library (``files``)
+            and/or all session metadata entries (``meta``).
+        cache_dir: Library directory. ``None`` uses :func:`resolve_library_dir`.
+        format: ``"parquet"``, ``"csv_gz"``, or ``"geoparquet"``. ``None``
+            deletes all bulk variants for ``name`` (ignored when ``name`` is
+            ``None``).
+        files: Delete on-disk bulk data files and sidecars.
+        meta: Drop session-cached ``info()`` entries from ``meta_cache``.
+        meta_cache: The client's ``_meta_cache`` dict (required for ``meta``).
+
+    Returns:
+        ``{"files": [deleted paths], "meta_cleared": int}``
+    """
+    deleted: list[str] = []
+    meta_n = 0
+
+    if meta and meta_cache is not None:
+        if name is None:
+            meta_n = len(meta_cache)
+            meta_cache.clear()
+        else:
+            key = str(name)
+            if key in meta_cache:
+                del meta_cache[key]
+                meta_n = 1
+
+    if files:
+        root = (
+            pathlib.Path(cache_dir).expanduser().resolve()
+            if cache_dir is not None
+            else resolve_library_dir(interactive=False)
+        )
+        if name is None:
+            if root.is_dir():
+                for p in root.iterdir():
+                    if p.suffix in {".parquet", ".gz"} or p.name.endswith(".geo.parquet"):
+                        p.unlink(missing_ok=True)
+                        deleted.append(str(p))
+                    elif p.name.endswith(".eolas-meta.json"):
+                        p.unlink(missing_ok=True)
+                        deleted.append(str(p))
+        elif format is None:
+            for ext in _BULK_EXTENSIONS.values():
+                p = root / f"{name}{ext}"
+                for candidate in (p, pathlib.Path(str(p) + ".eolas-meta.json")):
+                    if candidate.exists():
+                        candidate.unlink()
+                        deleted.append(str(candidate))
+        else:
+            fmt = format.lower()
+            if fmt not in _BULK_EXTENSIONS:
+                raise ValueError(
+                    f"Unknown format {format!r}. Expected one of: "
+                    + ", ".join(_BULK_EXTENSIONS)
+                )
+            p = root / f"{name}{_BULK_EXTENSIONS[fmt]}"
+            for candidate in (p, pathlib.Path(str(p) + ".eolas-meta.json")):
+                if candidate.exists():
+                    candidate.unlink()
+                    deleted.append(str(candidate))
+
+    return {"files": deleted, "meta_cleared": meta_n}
+
+
 def library_status() -> dict:
     """Return a dict describing how the library directory is currently resolved.
 

{eolas_data-1.3.4 → eolas_data-1.3.13}/eolas_data/meta.py

@@ -68,6 +68,40 @@ def split_meta(info: dict) -> tuple[dict, Optional[pd.DataFrame]]:
     return table, columns
 
 
+def _column_meta_records(
+    column_meta: Optional[pd.DataFrame | list[dict[str, Any]]],
+) -> Optional[list[dict[str, Any]]]:
+    if column_meta is None:
+        return None
+    if isinstance(column_meta, pd.DataFrame):
+        if column_meta.empty:
+            return None
+        return column_meta.to_dict("records")
+    if isinstance(column_meta, list):
+        return column_meta or None
+    return None
+
+
+def _column_meta_dataframe(
+    column_meta: Optional[pd.DataFrame | list[dict[str, Any]]],
+) -> Optional[pd.DataFrame]:
+    if column_meta is None:
+        return None
+    if isinstance(column_meta, pd.DataFrame):
+        return column_meta if not column_meta.empty else None
+    if isinstance(column_meta, list) and column_meta:
+        return pd.DataFrame(column_meta)
+    return None
+
+
+def _is_geodataframe(df: pd.DataFrame) -> bool:
+    try:
+        import geopandas as gpd
+    except ImportError:
+        return False
+    return isinstance(df, gpd.GeoDataFrame)
+
+
 def attach_meta(
     df: pd.DataFrame,
     *,
@@ -77,16 +111,32 @@ def attach_meta(
     column_meta: Optional[pd.DataFrame] = None,
 ) -> pd.DataFrame:
     """Attach eolas metadata attrs to a DataFrame / Dataset / GeoDataFrame."""
-    payload = {
+    col_records = _column_meta_records(column_meta)
+    col_df = _column_meta_dataframe(column_meta)
+    # attrs must be JSON-serialisable — never store a DataFrame there (breaks
+    # pandas repr/head on GeoDataFrames when attrs are compared with ==).
+    attrs_payload = {
         "eolas_name": name,
         "eolas_source": source,
         "eolas_meta": table_meta or {},
-        "eolas_columns": column_meta,
+        "eolas_columns": col_records,
     }
     attrs = getattr(df, "attrs", None)
     if isinstance(attrs, dict):
-        attrs.update(payload)
-    for key, val in payload.items():
+        attrs.update(attrs_payload)
+
+    if _is_geodataframe(df):
+        # GeoDataFrame: attrs only — setattr triggers geopandas/pandas warnings
+        # and can break tabular repr.
+        return df
+
+    object_payload = {
+        "eolas_name": name,
+        "eolas_source": source,
+        "eolas_meta": table_meta or {},
+        "eolas_columns": col_df,
+    }
+    for key, val in object_payload.items():
         try:
             setattr(df, key, val)
         except (AttributeError, TypeError):
@@ -108,7 +158,11 @@ def meta_subtitle(table_meta: Optional[dict]) -> str:
     return " · ".join(parts)
 
 
-def column_label(column_meta: Optional[pd.DataFrame], column: str) -> Optional[str]:
+def column_label(
+    column_meta: Optional[pd.DataFrame | list[dict[str, Any]]],
+    column: str,
+) -> Optional[str]:
+    column_meta = _column_meta_dataframe(column_meta)
     if column_meta is None or column_meta.empty or "name" not in column_meta.columns:
         return None
     rows = column_meta.loc[column_meta["name"] == column, "description"]

{eolas_data-1.3.4 → eolas_data-1.3.13}/pyproject.toml

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

{eolas_data-1.3.4 → eolas_data-1.3.13}/tests/test_meta.py

@@ -62,6 +62,32 @@ def test_meta_false_skips_info_fetch(client):
     assert df.eolas_columns is None
 
 
+def test_attach_meta_geodataframe_head_does_not_break_repr():
+    gpd = pytest.importorskip("geopandas")
+    from shapely.geometry import Point
+
+    from eolas_data.meta import attach_meta
+
+    gdf = gpd.GeoDataFrame(
+        {"id": [1]},
+        geometry=[Point(0, 0)],
+        crs="EPSG:4326",
+    )
+    cols = pd.DataFrame([
+        {"name": "id", "type": "int", "description": "Identifier"},
+    ])
+    attach_meta(
+        gdf,
+        name="nz_addresses",
+        source="LINZ",
+        table_meta={"title": "NZ Addresses"},
+        column_meta=cols,
+    )
+    gdf.head()  # must not raise (pandas attrs must not hold DataFrames)
+    assert gdf.attrs["eolas_name"] == "nz_addresses"
+    assert gdf.attrs["eolas_columns"][0]["name"] == "id"
+
+
 @resp_lib.activate
 def test_info_cached_on_second_get(client):
     resp_lib.add(resp_lib.GET, f"{BASE}/v1/datasets/nz_cpi/data", json={"data": RECORDS})

{eolas_data-1.3.4 → eolas_data-1.3.13}/tests/test_progress.py

@@ -203,6 +203,44 @@ def test_progress_kwarg_forces_hide(client, tmp_path):
     assert all(disabled_values), "tqdm must be disabled when progress=False"
 
 
+# ---------------------------------------------------------------------------
+# test_download_bulk_missing_content_length
+# ---------------------------------------------------------------------------
+
+@resp_lib.activate
+def test_download_bulk_missing_content_length(client, tmp_path):
+    """CDN may omit Content-Length — download must succeed with indeterminate bar."""
+    resp_lib.add(resp_lib.GET, f"{BASE}/v1/datasets/nz_cpi",
+                 json=BULK_DATASET_META, status=200)
+    resp_lib.add(resp_lib.GET, f"{BASE}/v1/bulk/statsnz/nz_cpi",
+                 body=FAKE_PARQUET,
+                 content_type="application/octet-stream",
+                 status=200)
+    # Deliberately no Content-Length header.
+
+    dest = tmp_path / "nz_cpi.parquet"
+    totals_seen = []
+
+    class FakeTqdm:
+        def __init__(self, **kwargs):
+            totals_seen.append(kwargs.get("total"))
+        def __enter__(self):
+            return self
+        def __exit__(self, *a):
+            pass
+        def update(self, n):
+            pass
+
+    with patch("sys.stdout") as mock_stdout, \
+         patch("tqdm.auto.tqdm", FakeTqdm):
+        mock_stdout.isatty.return_value = True
+        out = client.download_bulk("nz_cpi", path=dest, progress=True)
+
+    assert out == dest
+    assert dest.read_bytes() == FAKE_PARQUET
+    assert totals_seen == [None]
+
+
 # ---------------------------------------------------------------------------
 # test_sync_bulk_unchanged_no_bar
 # ---------------------------------------------------------------------------
@@ -421,6 +459,25 @@ def test_eolas_no_progress_env_suppresses_bar(client, tmp_path, monkeypatch):
     assert all(disabled_values), "EOLAS_NO_PROGRESS=1 must disable tqdm even when isatty=True"
 
 
+def test_progress_phase_selectors():
+    from eolas_data.client import Client
+
+    phases = Client._resolve_progress_phases("download")
+    assert phases == {"download": True, "read": False}
+
+    phases = Client._resolve_progress_phases("read")
+    assert phases == {"download": False, "read": True}
+
+    phases = Client._resolve_progress_phases("both")
+    assert phases == {"download": True, "read": True}
+
+    phases = Client._resolve_progress_phases("none")
+    assert phases == {"download": False, "read": False}
+
+    assert Client._resolve_show_progress("read", "read") is True
+    assert Client._resolve_show_progress("download", "read") is False
+
+
 def test_progress_resolver_detects_jupyter():
     """Jupyter wraps stdout so isatty() is False, but the user IS interactive
     and tqdm.auto can render a widget. Resolver must return True when

{eolas_data-1.3.4 → eolas_data-1.3.13}/tests/test_smoke_live.py

@@ -1,5 +1,7 @@
 """Live API smoke tests — run against api.eolas.fyi with a real key.
 
+Mirrors eolas-r/tests/smoke-live.R and eolas/docs/client-contract.md.
+
 Skipped in the default unit CI job (``pytest -m 'not integration'``).
 Enable locally or in the weekly smoke workflow::
 
@@ -8,6 +10,7 @@ Enable locally or in the weekly smoke workflow::
 from __future__ import annotations
 
 import os
+from pathlib import Path
 
 import pandas as pd
 import pytest
@@ -19,8 +22,17 @@ pytestmark = pytest.mark.integration
 _SKIP = not os.environ.get("EOLAS_API_KEY")
 
 
-@pytest.fixture(scope="module")
-def live_client():
+@pytest.fixture()
+def smoke_library(tmp_path, monkeypatch):
+    """Isolated on-disk library — same idea as EOLAS_LIBRARY in R smoke."""
+    lib = tmp_path / "eolas-smoke-lib"
+    lib.mkdir()
+    monkeypatch.setenv("EOLAS_LIBRARY", str(lib))
+    return lib
+
+
+@pytest.fixture()
+def live_client(smoke_library):
     if _SKIP:
         pytest.skip("EOLAS_API_KEY not set — live smoke tests skipped")
     return Client()
@@ -53,4 +65,21 @@ def test_get_nz_cpi_slice(live_client):
 def test_info_nz_cpi(live_client):
     meta = live_client.info("nz_cpi")
     assert meta["name"] == "nz_cpi"
-    assert "source" in meta
+    assert "source" in meta
+
+
+def test_client_exports_cache_clear(live_client):
+    assert hasattr(live_client, "cache_clear")
+    assert callable(live_client.cache_clear)
+
+
+def test_linz_nz_addresses_bulk_route_and_head(live_client, smoke_library):
+    """User path: client.linz() — not get_local(). head() must not crash."""
+    gdf = live_client.linz("nz_addresses", progress=False)
+    assert len(gdf) > 100_000
+    # GeoDataFrame or Dataset — repr/head must work (pandas attrs regression)
+    gdf.head()
+    # Bulk file landed in isolated library
+    assert any(smoke_library.iterdir())
+    geo_files = list(smoke_library.glob("nz_addresses*.geo.parquet"))
+    assert geo_files, f"expected bulk geo file under {smoke_library}"

{eolas_data-1.3.4 → eolas_data-1.3.13}/tests/test_sync_bulk.py

@@ -438,3 +438,62 @@ def test_cli_sync_unknown_freshness_exits_usage():
 def test_cli_sync_invalid_watch_exits_usage():
     result = runner.invoke(app, ["sync", "nz_cpi", "--watch", "forever", "--api-key", "k"])
     assert result.exit_code == cli_module.EXIT_USAGE
+
+
+# ---------------------------------------------------------------------------
+# cache_clear / force
+# ---------------------------------------------------------------------------
+
+@resp_lib.activate
+def test_sync_bulk_force_redownloads_when_unchanged(client, tmp_path):
+    """force=True skips the sidecar unchanged fast path."""
+    dest = tmp_path / "nz_cpi.parquet"
+    dest.write_bytes(FAKE_PARQUET)
+    _write_sidecar(dest, SNAPSHOT_V1)
+
+    resp_lib.add(resp_lib.GET, f"{BASE}/v1/datasets/nz_cpi",
+                 json=BULK_DATASET_META, status=200)
+    resp_lib.add(resp_lib.HEAD, f"{BASE}/v1/bulk/statsnz/nz_cpi",
+                 body=b"", status=200,
+                 headers={"X-Snapshot-Version": SNAPSHOT_V1})
+    resp_lib.add(resp_lib.GET, f"{BASE}/v1/bulk/statsnz/nz_cpi",
+                 body=FAKE_PARQUET_V2,
+                 content_type="application/octet-stream",
+                 status=200)
+
+    result = client.sync_bulk("nz_cpi", path=dest, force=True)
+
+    assert result.status == "updated"
+    assert dest.read_bytes() == FAKE_PARQUET_V2
+
+
+def test_cache_clear_removes_files_and_session_meta(client, tmp_path, monkeypatch):
+    """cache_clear deletes on-disk bulk files and drops session info cache."""
+    monkeypatch.setenv("EOLAS_LIBRARY", str(tmp_path))
+
+    dest = tmp_path / "nz_parcels.geo.parquet"
+    dest.write_bytes(FAKE_PARQUET)
+    _write_sidecar(dest, SNAPSHOT_V1)
+
+    client._meta_cache["nz_parcels"] = {"name": "nz_parcels"}
+
+    cleared = client.cache_clear("nz_parcels")
+
+    assert not dest.exists()
+    assert not pathlib.Path(str(dest) + ".eolas-meta.json").exists()
+    assert "nz_parcels" not in client._meta_cache
+    assert len(cleared["files"]) >= 2
+    assert cleared["meta_cleared"] == 1
+
+
+def test_cache_clear_meta_only(client):
+    """files=False clears session metadata without deleting library files."""
+    client._meta_cache["nz_cpi"] = {"name": "nz_cpi"}
+    client._meta_cache["nz_parcels"] = {"name": "nz_parcels"}
+
+    cleared = client.cache_clear("nz_cpi", files=False)
+
+    assert "nz_cpi" not in client._meta_cache
+    assert "nz_parcels" in client._meta_cache
+    assert cleared["files"] == []
+    assert cleared["meta_cleared"] == 1