Metadata-Version: 2.4
Name: buildingdata
Version: 0.1.1
Summary: Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-cloud-storage>=2.0
Requires-Dist: polars>=0.20
Requires-Dist: geopandas>=0.14
Requires-Dist: pyarrow>=14.0
Requires-Dist: tqdm>=4.0
Requires-Dist: requests>=2.28
Requires-Dist: platformdirs>=3.0
Provides-Extra: era5
Requires-Dist: cdsapi>=0.6; extra == "era5"
Requires-Dist: xarray>=2023.0; extra == "era5"
Requires-Dist: pvlib>=0.10; extra == "era5"
Requires-Dist: netcdf4>=1.6; extra == "era5"
Requires-Dist: zarr>=2.18; extra == "era5"
Provides-Extra: pipeline
Requires-Dist: snakemake>=8.0; extra == "pipeline"
Requires-Dist: openpyxl>=3.0; extra == "pipeline"
Requires-Dist: py7zr>=0.20; extra == "pipeline"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-autoapi>=3.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
Dynamic: license-file

# buildingdata

[![PyPI](https://img.shields.io/pypi/v/buildingdata.svg)](https://pypi.org/project/buildingdata/)
[![Python](https://img.shields.io/pypi/pyversions/buildingdata.svg)](https://pypi.org/project/buildingdata/)

**Data-management layer for [`buildingmodel`](https://gitlab.com/energytransition).**
`buildingdata` delivers clean, ready-to-use building, demographic and weather
datasets for French building energy inference, and caches everything locally so
repeated calls don't re-download.

```bash
pip install buildingdata
```

## Quick start

```python
import buildingdata as bd

# One-time configuration (bucket, cache dir, credentials).
# The public bucket works anonymously, so this is optional.
bd.configure()

# Reference datasets (downloaded once from Google Cloud Storage, then cached)
census    = bd.get_census()        # INSEE census            -> polars DataFrame
districts = bd.get_districts()     # IRIS district geometry  -> geopandas GeoDataFrame
diagnosis = bd.get_diagnosis()     # ADEME energy diagnoses  -> polars DataFrame
gas       = bd.get_gas_network()   # GRDF gas network routes -> geopandas GeoDataFrame

# On-demand datasets (fetched live from public APIs)
buildings = bd.get_bdtopo("751010101")           # per-IRIS building geometry (IGN WFS)
epw       = bd.get_era5_climate(48.85, 2.35, 2020)  # ERA5 weather -> synthetic EPW
```

You can also configure from the command line:

```bash
buildingdata configure --bucket my-bucket --cache-dir ~/.cache/buildingdata
```

## What it provides

| Function | Source | Returns |
| --- | --- | --- |
| `get_census()` | INSEE census (GCS) | polars `DataFrame` |
| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` |
| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` |
| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` |
| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) | geopandas `GeoDataFrame` |
| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) | path to EPW file |

Reference datasets are pulled from a public Google Cloud Storage bucket and
cached locally with generation-based freshness checks. French geospatial data
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
- **cache directory** — where downloaded data is stored locally
- **credentials** — path to a GCS service-account JSON (omit for anonymous access
  to the public bucket)

## Installation extras

```bash
pip install "buildingdata[era5]"   # ERA5 weather (cdsapi, xarray, pvlib, ...)
pip install "buildingdata[docs]"   # build the Sphinx documentation
```

Requires **Python ≥ 3.10**.

## License

Released under the [MIT License](LICENSE).
