pycountry

pycountry wraps the Debian pkg-isocodes database to give Python programs immediate access to the ISO 3166 country and subdivision standards, ISO 639-3 language codes, ISO 4217 currencies, and ISO 15924 scripts. Every entry is exposed as an attribute-rich object (alpha_2, alpha_3, numeric, name, official_name) that can be looked up exactly or found through fuzzy, accent-insensitive search.

Because the underlying data is a straight wrapper around the ISO standard rather than a hand-maintained fork, pycountry deliberately avoids accepting ad hoc data changes — updates flow from the upstream Debian iso-codes project, which keeps the library trustworthy for compliance-sensitive uses like address forms, currency selectors, and locale pickers. Gettext-based translation catalogs ship alongside the data so country and language names can be localized without extra dependencies.

What You Get

• Iterable databases for countries, historic countries, subdivisions, languages, currencies, and scripts
• Exact lookups by any standard code (alpha_2, alpha_3, numeric) plus a case-insensitive lookup() helper
• Fuzzy, unicode-normalizing search (search_fuzzy) for matching loosely-typed user input to the correct entry
• Gettext translation catalogs for localizing country, language, and currency names
• Runtime add_entry/remove_entry methods for injecting non-ISO values (e.g. Kosovo) without forking the library

Common Use Cases

• Populating country/currency/language dropdowns in web forms with authoritative ISO data
• Normalizing free-text country or language input from users or third-party APIs into ISO codes
• Validating that a currency or country code supplied by an external system is a real ISO value
• Displaying localized country and subdivision names in multi-language applications

Under The Hood

Architecture - pycountry is a thin, static-data wrapper: at import time it loads JSON databases bundled under src/pycountry/databases/ (sourced verbatim from Debian’s iso-codes package) into in-memory ExistingCountries/Languages/Currencies/Scripts collections defined in db.py, each supporting iteration, exact key lookup, and unicode-normalized fuzzy search; there is no network I/O or external service dependency, so the entire runtime surface is a data-loading and lookup layer. Tech Stack - pure Python 3.10+ with a Poetry-based build (pyproject.toml), zero runtime dependencies beyond the standard library, and gettext .mo translation catalogs under src/pycountry/locales/ for localized name lookups. Code Quality - the src/pycountry/tests/ directory holds a straightforward pytest suite exercising lookups, fuzzy search, and custom entry add/remove; the codebase is small (under 300 lines in __init__.py) and ships py.typed for type-checker support, though the project’s explicit no-data-changes policy limits the surface that needs testing. API Design - the API favors simplicity and predictability: every database is iterable, .get() and .lookup() provide two lookup styles, and objects behave like read-only records with dict() casting, making the library easy to pick up with almost no boilerplate.