Data

The ISO tables¶

A snapshot of the iso-codes tables is compiled into the binary, so there is no network access, no cache directory, and no first-call latency spike. pc.iso_version() reports the upstream release in use, and pc.table_sizes() how many records each table holds.

To supply your own tables at startup, point POLARS_COUNTRY_DATA at a directory holding iso3166-1.json, iso3166-2.json, iso3166-3.json and iso4217.json:

export POLARS_COUNTRY_DATA=/path/to/iso-codes

It is read once, on first use, so set it before the first lookup.

Refreshing without a restart¶

The standard changes — countries are added, subdivisions renamed, codes withdrawn. A long-lived process would otherwise be stuck with whatever tables it read when it resolved its first country, so two functions replace them in place:

# Download the current tables and load them into this process.
pc.refresh_iso_data()

# ...and keep a copy, so the next run need not go back to the network.
pc.refresh_iso_data(save_to="iso-codes/")

# Or load ones you already have.
pc.load_iso_data("iso-codes/")

Both take effect for every lookup that starts after they return. A query already in flight keeps the tables it began with, so no single column is ever resolved against two different snapshots.

refresh_iso_data is the only function here that touches the network, and only when you call it — importing the package still does nothing. Point it at an internal mirror with pc.refresh_iso_data(url=...) if outbound access is restricted.

A missing file, an unparseable table, or one too small to be a complete copy raises ValueError and leaves the working tables untouched. That last check earns its keep: a truncated download or an HTML error page is still valid something, and without a floor on the record count the only symptom would be countries quietly going missing.