The HDX Python Country Library provides utilities to map between country and region codes and names and to match administrative level names from different sources. It also provides utilities for foreign exchange enabling obtaining current and historic FX rates for different currencies.
It provides country mappings including ISO 2 and ISO 3 letter codes (ISO 3166) and regions using live official data from the UN OCHA feed with fallbacks to an internal static file if there is any problem with retrieving data from the url. (Also it is possible to force the use of the internal static files.)
It can exact match English, French, Spanish, Russian, Chinese and Arabic. There is a fuzzy matching for English look up that can handle abbreviations in country names like Dem. for Democratic and Rep. for Republic.
Mapping administration level names from a source to a given base set is also handled including phonetic fuzzy name matching.
It also provides foreign exchange rates and conversion from amounts in local currency to USD and vice-versa. The conversion relies on Yahoo Finance, falling back on currency-api for current rates, and Yahoo Finance falling back on IMF data via IATI (with interpolation) for historic daily rates.
For more information, please read the documentation.
This library is part of the Humanitarian Data Exchange (HDX) project. If you have humanitarian related data, please upload your datasets to HDX.
Development
Environment
Development is currently done using Python 3.13. The environment can be created with:
uv sync
This creates a .venv folder with the versions specified in the project's uv.lock file.
Pre-commit
pre-commit will be installed when syncing uv. It is run every time you make a git commit if you call it like this:
pre-commit install
With pre-commit, all code is formatted according to ruff guidelines.
To check if your changes pass pre-commit without committing, run:
pre-commit run --all-files
Packages
uv is used for package management. If
you’ve introduced a new package to the source code (i.e. anywhere in src/),
please add it to the project.dependencies section of pyproject.toml with
any known version constraints.
To add packages required only for testing, add them to the
[dependency-groups].
Any changes to the dependencies will be automatically reflected in
uv.lock with pre-commit, but you can re-generate the files without committing by
executing:
uv lock --upgrade
Project
uv is used for project management. The project can be built using:
uv build
Linting and syntax checking can be run with:
uv run ruff check
To run the tests and view coverage, execute:
uv run pytest
Documentation
The documentation, including API documentation, is generated using ReadtheDocs and
MkDocs with Material. As you change the source code, remember to update the
documentation at documentation/index.md.
WFP DataBridges Client
The WFPAPI class (hdx.location.wfp_api) uses WFP's data-bridges-client library, which is
published on WFP's own package index rather than PyPI. To install it, use the wfp extra with
that index added:
pip install "hdx-python-country[wfp]" \
--extra-index-url https://d2i4vvypvg40rv.cloudfront.net/pypi/ \
--index-strategy unsafe-best-match
If using uv, add the following to your project's pyproject.toml:
[tool.uv]
index-strategy = "unsafe-best-match"
[[tool.uv.index]]
name = "wfp"
url = "https://d2i4vvypvg40rv.cloudfront.net/pypi/"
then run uv sync --extra wfp.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hdx_python_country-4.1.3.tar.gz.
File metadata
- Download URL: hdx_python_country-4.1.3.tar.gz
- Upload date:
- Size: 540.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ffa387b953a0a1a3251a319801d113b19c062599d8e85b1666a21b7753b169ed
|
|
| MD5 |
3b1b805e4a9210aaff27b6bd8da74a82
|
|
| BLAKE2b-256 |
e951ec921a4ccff39681f60833f0d3cb5786a5c8dbd5960d59d983ba2a3c74fa
|
File details
Details for the file hdx_python_country-4.1.3-py3-none-any.whl.
File metadata
- Download URL: hdx_python_country-4.1.3-py3-none-any.whl
- Upload date:
- Size: 56.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
24da1b3d6c43deaace985934973e4680936b357acb46ebe9e2f09ef3749ed9d9
|
|
| MD5 |
2614973ec733c21e68dcb595e9758f55
|
|
| BLAKE2b-256 |
d261e1ca1873f8ae4a77a6d4e5ead6af1fd7c8b21a880f48617eca47e2005199
|
