buildingdata 0.2.0__tar.gz → 0.2.2__tar.gz

{buildingdata-0.2.0 → buildingdata-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildingdata
-Version: 0.2.0
+Version: 0.2.2
 Summary: Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -88,13 +88,32 @@ uses CRS **EPSG:2154 (Lambert-93)**.
 
 ## Configuration
 
-Settings are resolved from (in order) explicit arguments, environment variables,
-and `~/.config/buildingdata/config.ini`:
+Settings are resolved in the following precedence order:
+1. Explicit function arguments / CLI options
+2. Environment variables (`BUILDINGDATA_BUCKET`, `BUILDINGDATA_CACHE_DIR`, `GOOGLE_APPLICATION_CREDENTIALS`)
+3. Global configuration file (`~/.config/buildingdata/config.ini`)
+4. Dynamic defaults
 
-- **bucket** — GCS bucket holding the reference datasets
+Configurable settings:
+- **bucket** — GCS bucket holding reference datasets (default: `building-inference-data`)
 - **cache directory** — where downloaded data is stored locally
-- **credentials** — path to a GCS service-account JSON (omit for anonymous access
-  to the public bucket)
+- **credentials** — path to a GCS service-account JSON (omit for anonymous access to the public bucket)
+
+### Cache Behavior & Multi-Project Sharing
+
+- **Default (Unconfigured)**: The cache directory is namespaced per installation (`~/.local/share/buildingdata/cache/<install-id>` on Linux/macOS). Each virtualenv or package installation receives its own unique cache subfolder to prevent collisions between environments.
+- **Sharing Across Projects**: To share a single cache directory across multiple repositories, virtualenvs, or Snakemake pipelines, set the `BUILDINGDATA_CACHE_DIR` environment variable or write a global configuration file:
+
+```bash
+# Via CLI (writes ~/.config/buildingdata/config.ini):
+buildingdata configure --cache-dir /path/to/shared/cache
+
+# Or via environment variable:
+export BUILDINGDATA_CACHE_DIR="/path/to/shared/cache"
+```
+
+Because `~/.config/buildingdata/config.ini` is stored in your home directory, configuring it once applies globally to all projects and virtual environments for your user account.
+
 
 ## Installation extras
 

{buildingdata-0.2.0 → buildingdata-0.2.2}/README.md

@@ -55,13 +55,32 @@ uses CRS **EPSG:2154 (Lambert-93)**.
 
 ## Configuration
 
-Settings are resolved from (in order) explicit arguments, environment variables,
-and `~/.config/buildingdata/config.ini`:
-
-- **bucket** — GCS bucket holding the reference datasets
+Settings are resolved in the following precedence order:
+1. Explicit function arguments / CLI options
+2. Environment variables (`BUILDINGDATA_BUCKET`, `BUILDINGDATA_CACHE_DIR`, `GOOGLE_APPLICATION_CREDENTIALS`)
+3. Global configuration file (`~/.config/buildingdata/config.ini`)
+4. Dynamic defaults
+
+Configurable settings:
+- **bucket** — GCS bucket holding reference datasets (default: `building-inference-data`)
 - **cache directory** — where downloaded data is stored locally
-- **credentials** — path to a GCS service-account JSON (omit for anonymous access
-  to the public bucket)
+- **credentials** — path to a GCS service-account JSON (omit for anonymous access to the public bucket)
+
+### Cache Behavior & Multi-Project Sharing
+
+- **Default (Unconfigured)**: The cache directory is namespaced per installation (`~/.local/share/buildingdata/cache/<install-id>` on Linux/macOS). Each virtualenv or package installation receives its own unique cache subfolder to prevent collisions between environments.
+- **Sharing Across Projects**: To share a single cache directory across multiple repositories, virtualenvs, or Snakemake pipelines, set the `BUILDINGDATA_CACHE_DIR` environment variable or write a global configuration file:
+
+```bash
+# Via CLI (writes ~/.config/buildingdata/config.ini):
+buildingdata configure --cache-dir /path/to/shared/cache
+
+# Or via environment variable:
+export BUILDINGDATA_CACHE_DIR="/path/to/shared/cache"
+```
+
+Because `~/.config/buildingdata/config.ini` is stored in your home directory, configuring it once applies globally to all projects and virtual environments for your user account.
+
 
 ## Installation extras
 

{buildingdata-0.2.0 → buildingdata-0.2.2}/buildingdata/cache.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
+import fcntl
 import json
+import os
+import time
+import uuid
+from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -7,6 +12,46 @@ from .config import get_cache_dir
 from .exceptions import CacheError
 
 
+@contextmanager
+def file_lock(lock_path, timeout=600):
+    """Context manager for acquiring an inter-process file lock.
+
+    Args:
+        lock_path (pathlib.Path or str): Path to the lock file.
+        timeout (int or float): Maximum seconds to wait for lock acquisition.
+            Defaults to 600 seconds.
+
+    Raises:
+        CacheError: If lock acquisition times out.
+    """
+    lock_path = Path(lock_path)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o666)
+    start_time = time.monotonic()
+    acquired = False
+    try:
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                acquired = True
+                break
+            except (BlockingIOError, OSError):
+                if time.monotonic() - start_time >= timeout:
+                    raise CacheError(f"Timed out waiting for lock on {lock_path}") from None
+                time.sleep(0.1)
+        yield
+    finally:
+        if acquired:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            except OSError:
+                pass
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+
 def cache_path(name):
     """Return the local Path where a named artifact should be cached.
 
@@ -59,7 +104,7 @@ def needs_refresh(name, blob):
 
 
 def write_sidecar(name, blob):
-    """Write a .meta.json sidecar after a successful download.
+    """Write a .meta.json sidecar after a successful download atomically.
 
     Args:
         name (str): logical artifact name.
@@ -71,10 +116,15 @@ def write_sidecar(name, blob):
         "generation": blob.generation,
         "downloaded_at": datetime.now(timezone.utc).isoformat(),
     }
+    pid_suffix = f".tmp.{os.getpid()}_{uuid.uuid4().hex[:6]}"
+    tmp_sidecar = sidecar.with_name(sidecar.name + pid_suffix)
     try:
-        with open(sidecar, "w") as f:
+        with open(tmp_sidecar, "w") as f:
             json.dump(meta, f, indent=2)
+        tmp_sidecar.replace(sidecar)
     except OSError as e:
+        if tmp_sidecar.exists():
+            tmp_sidecar.unlink(missing_ok=True)
         raise CacheError(f"Failed to write cache sidecar {sidecar}: {e}") from e
 
 
@@ -90,3 +140,4 @@ def ensure_subdir(subdir):
     path = get_cache_dir() / subdir
     path.mkdir(parents=True, exist_ok=True)
     return path
+

buildingdata-0.2.2/buildingdata/exceptions.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+
+
+class BuildingDataError(Exception):
+    """Base exception for buildingdata errors."""
+
+
+class CacheError(BuildingDataError):
+    """Raised when a cache read or write operation fails."""
+
+
+class RemoteNotAvailableError(BuildingDataError):
+    """Raised when a remote endpoint returns a non-success status."""
+
+
+class ConfigurationError(BuildingDataError):
+    """Raised when required configuration (credentials, API key) is missing."""
+
+
+class SchemaValidationError(BuildingDataError):
+    """Raised when a fetched dataset violates its expected schema/unit contract.
+
+    Signals that the upstream file's columns, dtypes or value ranges no longer
+    match what this package documents and what its consumers rely on -- e.g. a
+    portal revised its schema, a join-key format changed, or a column switched
+    units (kWh vs MWh, fraction vs percent). Failing fast here is deliberate:
+    a clear error on a revised upstream file beats a silent NaN or a
+    wrong-scale value propagating into a simulation.
+    """

buildingdata-0.2.2/buildingdata/gcs.py

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+from pathlib import Path
+
+from tqdm import tqdm
+
+from .config import get_bucket, get_credentials_file
+
+
+def get_client():
+    """Return a google.cloud.storage.Client.
+
+    Uses the credentials file from config if one is set. Otherwise returns
+    an anonymous client, which can read public buckets without any
+    authentication or Google Cloud project.
+
+    Returns:
+        google.cloud.storage.Client: storage client.
+    """
+    from google.cloud import storage
+
+    creds_file = get_credentials_file()
+    if creds_file is not None:
+        return storage.Client.from_service_account_json(str(creds_file))
+    return storage.Client.create_anonymous_client()
+
+
+def get_blob(name):
+    """Return the Blob object for a given name, or None if not found.
+
+    Args:
+        name (str): blob name inside the configured bucket.
+
+    Returns:
+        google.cloud.storage.Blob or None.
+    """
+    client = get_client()
+    bucket = client.bucket(get_bucket())
+    blob = bucket.blob(name)
+    blob.reload()
+    return blob if blob.exists() else None
+
+
+def download_blob(name, dest_path, show_progress=True):
+    """Download a blob from the configured bucket to dest_path.
+
+    Args:
+        name (str): blob name inside the bucket, e.g. "census_latest.parquet".
+        dest_path (pathlib.Path): local destination file path.
+        show_progress (bool): display a tqdm progress bar. Defaults to True.
+    """
+    import os
+    import uuid
+
+    from google.cloud import storage
+
+    dest_path = Path(dest_path)
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+    client = get_client()
+    bucket = client.bucket(get_bucket())
+    blob = bucket.blob(name)
+    blob.reload()
+
+    total = blob.size or 0
+    pid_suffix = f".tmp.{os.getpid()}_{uuid.uuid4().hex[:6]}"
+    tmp_path = dest_path.with_name(dest_path.name + pid_suffix)
+
+    try:
+        with open(tmp_path, "wb") as f:
+            if show_progress:
+                with tqdm(
+                    total=total,
+                    unit="B",
+                    unit_scale=True,
+                    desc=name,
+                    leave=True,
+                ) as bar:
+                    def _callback(chunk):
+                        bar.update(len(chunk))
+
+                    blob.download_to_file(f, checksum="md5", raw_download=True)
+                    bar.update(total - bar.n)
+            else:
+                blob.download_to_file(f)
+
+        tmp_path.replace(dest_path)
+    finally:
+        if tmp_path.exists():
+            tmp_path.unlink(missing_ok=True)
+
+    return blob
+
+
+def ensure_blob_cached(blob_name, refresh=False, get_blob_fn=None, download_blob_fn=None):
+    """Ensure a named GCS blob is downloaded and up-to-date locally, synchronized across processes.
+
+    Args:
+        blob_name (str): name of the blob in GCS, e.g. "census_latest.parquet".
+        refresh (bool): force re-download even if cached locally. Defaults to False.
+        get_blob_fn (callable, optional): function to retrieve Blob. Defaults to get_blob.
+        download_blob_fn (callable, optional): function to download Blob. Defaults to download_blob.
+
+    Returns:
+        pathlib.Path: absolute path to the cached file.
+
+    Raises:
+        RemoteNotAvailableError: if the blob does not exist in GCS.
+    """
+    from .cache import cache_path, file_lock, is_cached, needs_refresh, write_sidecar
+    from .exceptions import RemoteNotAvailableError
+
+    if get_blob_fn is None:
+        get_blob_fn = get_blob
+    if download_blob_fn is None:
+        download_blob_fn = download_blob
+
+    dest = cache_path(blob_name)
+    lock_file = dest.with_name(dest.name + ".lock")
+
+    with file_lock(lock_file):
+        if not is_cached(blob_name) or refresh:
+            blob = get_blob_fn(blob_name)
+            if blob is None:
+                raise RemoteNotAvailableError(f"Blob {blob_name!r} not found in GCS bucket.")
+            if not is_cached(blob_name) or needs_refresh(blob_name, blob):
+                download_blob_fn(blob_name, dest)
+                write_sidecar(blob_name, blob)
+
+    return dest
+
+
+

buildingdata-0.2.2/buildingdata/reference/census.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+import polars as pl
+
+from ..exceptions import RemoteNotAvailableError
+from ..gcs import download_blob, ensure_blob_cached, get_blob
+from ..validation import require_columns
+
+
+
+_BLOB_NAME = "census_latest.parquet"
+
+# Columns the processed INSEE census must expose. ``district``/``city_group``
+# are the join keys ``building_eload`` uses to attach census records to IRIS
+# districts; the dwelling-attribute columns feed ``buildingmodel``'s inference
+# (occupancy/heating/cooking/construction) and the ``ipondl`` weight is the
+# census sampling weight every aggregate is summed over. Missing any of these
+# means the wrong file or a revised INSEE schema.
+_REQUIRED_COLUMNS = (
+    "district",
+    "city_group",
+    "ipondl",
+    "occupancy_type",
+    "occupant_status",
+    "occupant_count",
+    "living_area_class",
+    "heating_system",
+    "residential_type",
+    "construction_year_class",
+    "main_cooking_energy",
+    "secondary_cooking_energy",
+)
+
+
+def get_census(city_group_list=None, refresh=False):
+    """Return the processed INSEE census DataFrame, optionally pre-filtered.
+
+    Downloads census_latest.parquet from GCS to the local cache on first call
+    (or when refresh=True). Filtering by city_group_list uses Polars lazy scan
+    so only the needed rows are loaded into memory.
+
+    Args:
+        city_group_list (list of str, optional): EPCI codes to filter on. If
+            None, the full national census is returned. Defaults to None.
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        polars.DataFrame: census records with columns occupancy_type,
+            occupant_status, living_area_class, occupant_count, heating_system,
+            residential_type, construction_year_class, district, city,
+            city_group, department, region, main_cooking_energy,
+            secondary_cooking_energy, ipondl. ``district``/``city_group`` are
+            string INSEE codes (IRIS / EPCI); ``ipondl`` is the INSEE sampling
+            weight every aggregate is summed over.
+
+    Raises:
+        RemoteNotAvailableError: if the blob is not found in the GCS bucket.
+        SchemaValidationError: if the fetched frame is missing a required
+            join-key or dwelling-attribute column (see ``_REQUIRED_COLUMNS``).
+    """
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
+
+
+    lf = pl.scan_parquet(dest)
+
+    require_columns(lf.collect_schema(), _REQUIRED_COLUMNS, "INSEE census")
+    if city_group_list is not None:
+        lf = lf.filter(pl.col("city_group").is_in(city_group_list))
+    return lf.collect()

{buildingdata-0.2.0 → buildingdata-0.2.2}/buildingdata/reference/diagnosis.py

@@ -1,15 +1,28 @@
 # -*- coding: utf-8 -*-
 import polars as pl
 
-from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
-from ..exceptions import RemoteNotAvailableError
-from ..gcs import download_blob, get_blob
+from ..gcs import download_blob, ensure_blob_cached, get_blob
+from ..validation import require_columns
+
 
 _BLOB_NAME = "energy_performance_diagnosis_latest.parquet"
 
+
 # Heating/DHW energies excluded from inference (no meaningful DPE data for coal)
 _EXCLUDED_ENERGIES = ["Charbon"]
 
+# Columns this accessor operates on directly (coal filter + dtype casts). If any
+# is absent the raw polars error is opaque; validating up front names the DPE
+# schema drift explicitly. ``heating_system`` + ``region`` are the join keys
+# ``buildingmodel``'s energy-system inference keys on; ``backup_heating_energy``
+# / ``dhw_energy`` carry the fuel labels the coal filter reads.
+_REQUIRED_COLUMNS = (
+    "heating_system",
+    "region",
+    "backup_heating_energy",
+    "dhw_energy",
+)
+
 
 def get_diagnosis(refresh=False):
     """Return the cleaned DPE energy performance diagnosis DataFrame.
@@ -26,19 +39,22 @@ def get_diagnosis(refresh=False):
         polars.DataFrame: DPE records with columns heating_system (Categorical),
             region (Int64), backup_heating_energy, dhw_energy, and all U-value
             and efficiency columns used by inference/building_attributes.py.
+
+    Raises:
+        RemoteNotAvailableError: if the blob is not found in the GCS bucket.
+        SchemaValidationError: if the fetched frame is missing one of the
+            columns this accessor operates on (see ``_REQUIRED_COLUMNS``).
     """
-    dest = cache_path(_BLOB_NAME)
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
 
-    if not is_cached(_BLOB_NAME) or refresh:
-        blob = get_blob(_BLOB_NAME)
-        if blob is None:
-            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
-        if not is_cached(_BLOB_NAME) or needs_refresh(_BLOB_NAME, blob):
-            download_blob(_BLOB_NAME, dest)
-            write_sidecar(_BLOB_NAME, blob)
 
     df = pl.read_parquet(dest)
 
+
+    require_columns(df, _REQUIRED_COLUMNS, "DPE/EPC diagnosis")
+
     # Remove records with coal heating/DHW — no useful inference data
     df = df.filter(
         ~pl.col("backup_heating_energy").is_in(_EXCLUDED_ENERGIES)

{buildingdata-0.2.0 → buildingdata-0.2.2}/buildingdata/reference/districts.py

@@ -1,9 +1,7 @@
 # -*- coding: utf-8 -*-
 import geopandas as gpd
 
-from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
-from ..exceptions import RemoteNotAvailableError
-from ..gcs import download_blob, get_blob
+from ..gcs import download_blob, ensure_blob_cached, get_blob
 
 _BLOB_NAME = "districts_latest.parquet"
 
@@ -25,17 +23,13 @@ def get_districts(bbox=None, refresh=False):
             district, city, city_name, city_group, department, region,
             has_network_city_level, has_network_grdf_data, geometry.
     """
-    dest = cache_path(_BLOB_NAME)
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
 
-    if not is_cached(_BLOB_NAME) or refresh:
-        blob = get_blob(_BLOB_NAME)
-        if blob is None:
-            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
-        if not is_cached(_BLOB_NAME) or needs_refresh(_BLOB_NAME, blob):
-            download_blob(_BLOB_NAME, dest)
-            write_sidecar(_BLOB_NAME, blob)
 
     kwargs = {}
     if bbox is not None:
         kwargs["bbox"] = bbox
     return gpd.read_parquet(dest, **kwargs)
+

{buildingdata-0.2.0 → buildingdata-0.2.2}/buildingdata/reference/elmas.py

@@ -1,9 +1,7 @@
 # -*- coding: utf-8 -*-
 import polars as pl
 
-from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
-from ..exceptions import RemoteNotAvailableError
-from ..gcs import download_blob, get_blob
+from ..gcs import download_blob, ensure_blob_cached, get_blob
 
 # The ELMAS non-residential dataset (Chiche/Duquesne et al., Sci. Data 2023,
 # 10.1038/s41597-023-02542-z) ships as several tables. Each is cached as its
@@ -56,14 +54,10 @@ def get_elmas(table="time_series", refresh=False):
         )
 
     blob_name = _BLOB_NAMES[table]
-    dest = cache_path(blob_name)
+    dest = ensure_blob_cached(
+        blob_name, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
 
-    if not is_cached(blob_name) or refresh:
-        blob = get_blob(blob_name)
-        if blob is None:
-            raise RemoteNotAvailableError(f"Blob {blob_name!r} not found in GCS bucket.")
-        if not is_cached(blob_name) or needs_refresh(blob_name, blob):
-            download_blob(blob_name, dest)
-            write_sidecar(blob_name, blob)
 
     return pl.read_parquet(dest)
+

{buildingdata-0.2.0 → buildingdata-0.2.2}/buildingdata/reference/enedis.py

@@ -1,9 +1,7 @@
 # -*- coding: utf-8 -*-
 import polars as pl
 
-from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
-from ..exceptions import RemoteNotAvailableError
-from ..gcs import download_blob, get_blob
+from ..gcs import download_blob, ensure_blob_cached, get_blob
 
 # Enedis "conso-inf36" (<= 36 kVA) measured aggregated consumption / average
 # load curves, used by building_eload.core.validation as measured ground truth.
@@ -14,17 +12,14 @@ _REGIONAL_BLOB_NAME = "enedis_regional_conso_inf36_latest.parquet"
 
 
 def _fetch(blob_name, refresh):
-    dest = cache_path(blob_name)
-    if not is_cached(blob_name) or refresh:
-        blob = get_blob(blob_name)
-        if blob is None:
-            raise RemoteNotAvailableError(f"Blob {blob_name!r} not found in GCS bucket.")
-        if not is_cached(blob_name) or needs_refresh(blob_name, blob):
-            download_blob(blob_name, dest)
-            write_sidecar(blob_name, blob)
+    dest = ensure_blob_cached(
+        blob_name, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
     return pl.read_parquet(dest)
 
 
+
+
 def get_enedis_national(refresh=False):
     """Return Enedis national ``conso-inf36`` measured consumption (polars).
 

{buildingdata-0.2.0 → buildingdata-0.2.2}/buildingdata/reference/gas_network.py

@@ -1,9 +1,7 @@
 # -*- coding: utf-8 -*-
 import geopandas as gpd
 
-from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
-from ..exceptions import RemoteNotAvailableError
-from ..gcs import download_blob, get_blob
+from ..gcs import download_blob, ensure_blob_cached, get_blob
 
 _BLOB_NAME = "gas_network_route_latest.gpkg"
 
@@ -24,17 +22,13 @@ def get_gas_network(bbox=None, refresh=False):
     Returns:
         geopandas.GeoDataFrame: gas pipeline routes in EPSG:2154.
     """
-    dest = cache_path(_BLOB_NAME)
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
 
-    if not is_cached(_BLOB_NAME) or refresh:
-        blob = get_blob(_BLOB_NAME)
-        if blob is None:
-            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
-        if not is_cached(_BLOB_NAME) or needs_refresh(_BLOB_NAME, blob):
-            download_blob(_BLOB_NAME, dest)
-            write_sidecar(_BLOB_NAME, blob)
 
     kwargs = {}
     if bbox is not None:
         kwargs["bbox"] = bbox
     return gpd.read_file(dest, **kwargs)
+

{buildingdata-0.2.0 → buildingdata-0.2.2}/buildingdata/reference/occupant_diaries.py

@@ -1,9 +1,7 @@
 # -*- coding: utf-8 -*-
 import polars as pl
 
-from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
-from ..exceptions import RemoteNotAvailableError
-from ..gcs import download_blob, get_blob
+from ..gcs import download_blob, ensure_blob_cached, get_blob
 
 _BLOB_NAME = "occupant_diaries_latest.parquet"
 
@@ -35,14 +33,9 @@ def get_occupant_diaries(refresh=False):
     Raises:
         RemoteNotAvailableError: if the blob is not found in the GCS bucket.
     """
-    dest = cache_path(_BLOB_NAME)
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
+    return pl.read_parquet(dest)
 
-    if not is_cached(_BLOB_NAME) or refresh:
-        blob = get_blob(_BLOB_NAME)
-        if blob is None:
-            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
-        if not is_cached(_BLOB_NAME) or needs_refresh(_BLOB_NAME, blob):
-            download_blob(_BLOB_NAME, dest)
-            write_sidecar(_BLOB_NAME, blob)
 
-    return pl.read_parquet(dest)

{buildingdata-0.2.0 → buildingdata-0.2.2}/buildingdata/reference/ore.py

@@ -1,9 +1,7 @@
 # -*- coding: utf-8 -*-
 import polars as pl
 
-from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
-from ..exceptions import RemoteNotAvailableError
-from ..gcs import download_blob, get_blob
+from ..gcs import download_blob, ensure_blob_cached, get_blob
 
 _BLOB_NAME = "ore_annual_consumption_latest.parquet"
 
@@ -38,14 +36,9 @@ def get_ore(refresh=False):
     Raises:
         RemoteNotAvailableError: if the blob is not found in the GCS bucket.
     """
-    dest = cache_path(_BLOB_NAME)
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
+    return pl.read_parquet(dest)
 
-    if not is_cached(_BLOB_NAME) or refresh:
-        blob = get_blob(_BLOB_NAME)
-        if blob is None:
-            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
-        if not is_cached(_BLOB_NAME) or needs_refresh(_BLOB_NAME, blob):
-            download_blob(_BLOB_NAME, dest)
-            write_sidecar(_BLOB_NAME, blob)
 
-    return pl.read_parquet(dest)