Usage
Usage¶
Three families of expressions, all taking a string column.
Countries — ISO 3166-1¶
"USA" | ||
|---|---|---|
pc.extract | struct of every field | one pass, all fields |
pc.match | {"US", "alpha_3", null, false} | how it resolved — see below |
pc.alpha_2 | US | |
pc.alpha_3 | USA | |
pc.numeric | 840 | Utf8, zero-padded |
pc.name | United States | the standard's short name |
pc.official_name | United States of America | null where none differs |
pc.common_name | null | e.g. Bolivia for BO |
pc.flag | 🇺🇸 | also accepted as input |
The input may be any indexed field: alpha-2, alpha-3, numeric, name, official name, common name, or the flag emoji. Matching is case-insensitive.
Subdivisions — ISO 3166-2¶
"California", country "US" | |
|---|---|
pc.subdivision | struct of every field |
pc.subdivision_code | US-CA |
pc.subdivision_name | California |
pc.subdivision_type | State |
pc.subdivision_country | US |
pc.subdivision_parent_code | null |
The value may be a full code ("US-CA"), a bare code with a country ("CA"), or a name ("California").
Pass country whenever you have it. Subdivision names are not unique across the standard — "Central" names a region in a dozen countries — so an unscoped name resolves to whichever record ISO lists first.
The argument follows the usual Polars convention: a bare string names a column, so a fixed country needs pl.lit(...). Either form accepts anything the country lookup does — "US", "USA", "840", "United States":
df.with_columns(
pc.subdivision_code("state", country=pl.col("country")), # per row
pc.subdivision_code("state", country=pl.lit("US")), # fixed
)
A country that does not itself resolve yields null rather than falling back to a global search, so a bad scope cannot quietly return another country's state.
Currencies — ISO 4217¶
pc.currency, pc.currency_alpha_3, pc.currency_numeric, pc.currency_name. Input may be the code, the number, or the name. Exact only — pycountry gives search_fuzzy to countries and subdivisions, not to currencies, so there is no reference to match a fuzzy currency search against.
Nulls¶
Every expression returns null when nothing matched, and null for null input. Blank and whitespace-only input is null too — see fuzzy matching for why that is a deliberate divergence from pycountry.
Null is also a real answer, not only a failure: most countries have no official_name and almost none have a common_name, so pl.coalesce(pc.common_name(c), pc.name(c)) is the usual way to get a display name.
Expression namespace¶
Importing the package registers a .country namespace:
df.with_columns(pl.col("country").country.alpha_2())
df.filter(pl.col("country").country.alpha_3() == "DEU")
Scalars¶
For code that isn't holding a DataFrame — the same Rust core, no Polars round-trip. Each returns a dict, or None:
pc.lookup_country("USA")
# {'alpha_2': 'US', 'alpha_3': 'USA', ..., 'matched_on': 'alpha_3', 'score': None}
pc.lookup_country("Texas", fuzzy=True)["alpha_2"] # 'US'
pc.lookup_subdivision("California", country="US") # {'code': 'US-CA', ...}
pc.lookup_currency("840") # {'alpha_3': 'USD', ...}
pc.search_countries("guinea", limit=3) # ranked, with scores