Metadata-Version: 2.5
Name: imibare
Version: 0.3.0
Summary: Programmatic access to official African government statistical data. Coverage today is Rwanda and Kenya.
Project-URL: Homepage, https://imibare.org
Project-URL: Documentation, https://imibare.org/docs
Project-URL: Bug Tracker, https://github.com/imibare/imibare-issues/issues
Project-URL: Changelog, https://imibare.org/changelog
Author-email: imibare <hello@imibare.org>
License-Expression: MIT
License-File: LICENSE
Keywords: africa,economics,government-data,kenya,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: 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 official government statistical data.

`imibare` gives you clean, typed, versioned access to official statistics
straight from the institutions that publish them, as pandas or polars
DataFrames. No scraping, no PDF wrangling.

Coverage today is Rwanda and Kenya: NISR, BNR, MINECOFIN, RSSB, RRA, RURA, RDB
and NAEB in Rwanda, KNBS and CBK in Kenya. Every dataset ID is country-prefixed
(`rw.nisr.cpi.monthly`, `ke.knbs.cpi.monthly`), so further countries slot in
without breaking changes.

## 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")

# Kenya works the same way
ke_cpi = imi.load("ke.knbs.cpi.monthly")

# 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="KE")                 # Kenya only
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

Both `catalog()` and `load()` work with no setup. `catalog()` reads metadata
bundled in the package; `load()` fetches the latest data from the public imibare
API. The versioned `load(version=...)` path additionally requires the `[iceberg]`
extra and R2 catalog credentials.

`load()` caches each download under `~/.imibare/cache/`. A cached file is used
for up to an hour, then checked against the API, and downloaded again only if
the data has changed. Pass `force_download=True` to skip the cache.

## 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.
