Metadata-Version: 2.4
Name: imibare
Version: 0.1.0
Summary: Programmatic access to Rwandan government statistical data
Project-URL: Homepage, https://imibare.org
Project-URL: Documentation, https://imibare.org/docs
Author-email: imibare <hello@imibare.org>
License-Expression: MIT
License-File: LICENSE
Keywords: africa,economics,government-data,open-data,rwanda,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: boto3>=1.34
Requires-Dist: httpx>=0.27
Requires-Dist: pandas>=2.2
Requires-Dist: pyarrow>=15.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: polars>=1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: iceberg
Requires-Dist: pyiceberg[pyarrow]<0.12,>=0.11.1; extra == 'iceberg'
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == 'polars'
Description-Content-Type: text/markdown

# imibare

Programmatic access to Rwandan government statistical data.

`imibare` gives you clean, typed, versioned access to official statistics
published by Rwandan government institutions (NISR, BNR, MINECOFIN, RSSB, RRA,
and more) as pandas or polars DataFrames. No scraping, no PDF wrangling.

## Install

```bash
pip install imibare
```

Optional extras:

```bash
pip install imibare[polars]    # return polars DataFrames
pip install imibare[iceberg]   # snapshot time travel via load(version=...)
```

## Quick start

```python
import imibare as imi

# Browse the catalog (works offline)
for d in imi.catalog(country="RW")[:5]:
    print(d.id, "-", d.name)

# Load a dataset as a pandas DataFrame
df = imi.load("rw.nisr.cpi.monthly")

# Filter by date range
recent = imi.load("rw.nisr.cpi.monthly", start="2023-01-01")

# Return a polars DataFrame (requires the [polars] extra)
fx = imi.load("rw.bnr.fx.daily", engine="polars")
```

## Catalog

`catalog()` returns dataset metadata you can filter by country, topic, or
frequency:

```python
imi.catalog()                             # every dataset
imi.catalog(country="RW", topic="prices")
imi.catalog(frequency="daily")
```

Each entry carries its id, producing institution, coverage window, columns,
source URL, and license.

## Dataset IDs

Every dataset has a stable, country-prefixed id of four segments:

```
{country}.{institution}.{topic}.{frequency}
rw.nisr.cpi.monthly
```

Ids are permanent; a breaking schema change ships under a new suffix
(for example `rw.nisr.cpi.monthly.v2`).

## Versioned data (time travel)

With the `[iceberg]` extra you can load a dataset as it stood on a given date:

```python
imi.load("rw.nisr.cpi.monthly", version="2025-06-01")
```

## Data access

`catalog()` works offline from metadata bundled in the package. `load()` fetches
Parquet data from imibare's object store; see the
[documentation](https://imibare.org/docs) for access configuration.

## Links

- Website: https://imibare.org
- Documentation: https://imibare.org/docs

## License

Code is released under the MIT License. Data retrieved through this package
remains under the license of each source institution; see each dataset's
metadata for details.
