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

{eolas_data-1.3.5 → 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.5 → eolas_data-1.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eolas-data
-Version: 1.3.5
+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/

{eolas_data-1.3.5 → 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.5 → eolas_data-1.3.13}/eolas_data/client.py

@@ -266,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",
@@ -486,6 +516,7 @@ class Client:
         format: str = "parquet",
         freshness: str = "auto",
         progress: ProgressControl = None,
+        force: bool = False,
     ) -> SyncResult:
         """Incrementally sync a bulk dataset file — only re-download when the snapshot changes.
 
@@ -518,6 +549,8 @@ class Client:
                 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``,
@@ -565,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")
 
@@ -601,7 +636,8 @@ 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()
         ):
@@ -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"
@@ -1842,6 +1886,7 @@ class Client:
         as_arrow: bool = False,
         meta: bool = True,
         progress: ProgressControl = None,
+        force: bool = False,
     ) -> "pd.DataFrame":
         """Download (or serve from cache) a whole dataset as a local DataFrame.
 
@@ -1886,6 +1931,8 @@ class Client:
                 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 +
@@ -1908,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:
@@ -1946,7 +1994,10 @@ 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
@@ -1988,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:
@@ -2011,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.
 
@@ -2096,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.5 → 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.5 → 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.5 → eolas_data-1.3.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "eolas-data"
-version = "1.3.5"
+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.5 → 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.5 → 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
 # ---------------------------------------------------------------------------

{eolas_data-1.3.5 → 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.5 → 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