Python package

Use the Python package when you want an imibare dataset as a DataFrame. We keep the interface small: load() reads data and catalog() tells you what data exists.

Install and import

Install the base package for pandas support. Add an extra only when you need Polars or private Iceberg history access.

import imibare as imi

Load data

Call imi.load() with a 4-segment dataset ID. It returns the latest published data through the public API unless you explicitly request a historical version.

def load(
    dataset_id: str,
    start: int | str | None = None,
    end: int | str | None = None,
    engine: Literal["pandas", "polars"] = "pandas",
    version: str | None = None,
    force_download: bool = False,
) -> pd.DataFrame | pl.DataFrame

Choose the arguments

start and end accept an integer year, an ISO date string, or None. Both bounds are inclusive, so start=2020, end=2023 keeps the complete 2020 through 2023 period.

Get the result

load() returns a pandas DataFrame by default and a Polars DataFrame when engine="polars". Its columns match the dataset record from catalog() and GET /v1/datasets/{id}, with dates parsed as datetime columns.

Use the public path unless you have a reason not to. A version request reads our Iceberg catalog directly and needs the [iceberg] extra plus credentials that we do not issue publicly.

Handle errors and warnings

Examples

import imibare as imi

# Latest complete dataset
cpi = imi.load("rw.nisr.cpi.monthly")

# Kenya uses the same interface
kenya_cpi = imi.load("ke.knbs.cpi.monthly")

# Inclusive year or exact-date bounds
recent_cpi = imi.load("rw.nisr.cpi.monthly", start=2020, end=2023)
usd_2024 = imi.load("rw.bnr.fx.daily", start="2024-01-01", end="2024-12-31")

# A Polars DataFrame
polars_cpi = imi.load("rw.nisr.cpi.monthly", engine="polars")

# The newest file, without using the cache
fresh_cpi = imi.load("rw.nisr.cpi.monthly", force_download=True)

Browse the catalog

Call imi.catalog() when you need IDs or want to inspect coverage before loading. The catalog ships with the package, so it works offline and represents the data known when your installed package version was released.

def catalog(
    country: str | list[str] | None = None,
    topic: str | None = None,
    frequency: str | None = None,
) -> list[DatasetMeta]

Filter the records

The metadata topic is not always the third part of the ID. For example, rw.nisr.cpi.monthly has the metadata topic prices, so use a topic you have seen in a catalog record rather than guessing from the ID.

# All bundled records
all_datasets = imi.catalog()

# Country and frequency filters
kenya = imi.catalog(country="KE")
monthly = imi.catalog(country="KE", frequency="monthly")

# Consumer price and inflation datasets in both countries
prices = imi.catalog(topic="prices")

for dataset in imi.catalog(country="RW"):
    print(dataset.id, dataset.name)

catalog() returns an empty list when nothing matches. Upgrade the package to see datasets that were added after your installed release.

Read dataset metadata

Each DatasetMeta is a record from the bundled catalog. It describes the publisher, coverage, schema, formats, and reuse information, but leaves the live last_updated and version empty because those values can change after the package ships.

@dataclass
class DatasetMeta:
    id: str
    country: str
    country_name: str
    name: str
    institution: str
    institution_slug: str
    topic: str
    frequency: str
    coverage_start: str
    coverage_end: str
    pipeline: Literal["automated", "curated", "stale"]
    source_url: str
    source_format: str
    formats: list[str]
    license: str
    license_basis: str
    columns: list[ColumnSpec]
    last_updated: str = ""
    version: str = ""
    notes: str | None = None
    license_url: str | None = None

Use the API record when you need the live version, update date, or version history. The license field records what the publisher states; it is not a license granted by imibare.

@dataclass
class ColumnSpec:
    name: str
    type: str
    description: str
    unit: str | None

Check the installed version

imibare.__version__

The value is a string, such as "0.3.0". It tells you which bundled catalog and package behavior you have installed.

Configure the package

You normally need no configuration. Set these variables only when you use a different API host or private Iceberg history access.

Understand the cache

We keep the latest file for each dataset at this path, next to a latest.etag file that records the API version we received. The cache makes repeated analysis quicker while still checking for changes on a predictable schedule.

~/.imibare/cache/{country}/{institution}/{topic}/{frequency}/latest.parquet

Delete ~/.imibare/cache/ if you need to clear every cached dataset. Removing the directory is safe, but the next call for each dataset will need to download it again.