[](https://github.com/OCHA-DAP/hdx-python-country/actions/workflows/run-python-tests.yaml)
[](https://coveralls.io/github/OCHA-DAP/hdx-python-country?branch=main)
[](https://github.com/astral-sh/ruff)
[](https://pypistats.org/packages/hdx-python-country)
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](https://vocabulary.unocha.org/) 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](https://github.com/fawazahmed0/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](https://hdx-python-country.readthedocs.io/en/latest/).
This library is part of the [Humanitarian Data Exchange](https://data.humdata.org/)
(HDX) project. If you have humanitarian related data, please upload your datasets to
HDX.
## Development
### Environment
Development is currently done using Python 3.12. We recommend using a virtual
environment such as ``venv``:
```shell
python -m venv venv
source venv/bin/activate
```
In your virtual environment, install all packages for development by running:
```shell
pip install -r requirements.txt
```
### Pre-commit
Be sure to install `pre-commit`, which is run every time you make a git commit:
```shell
pip install pre-commit
pre-commit install
```
With pre-commit, all code is formatted according to
[ruff](https://docs.astral.sh/ruff/) guidelines.
To check if your changes pass pre-commit without committing, run:
```shell
pre-commit run --all-files
```
### Testing
Ensure you have the required packages to run the tests:
```shell
pip install -r requirements.txt
```
To run the tests and view coverage, execute:
```shell
pytest -c --cov hdx
```
## Packages
[uv](https://github.com/astral-sh/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 `test` section under
`[project.optional-dependencies]`.
Any changes to the dependencies will be automatically reflected in
`requirements.txt` with `pre-commit`, but you can re-generate the file without
committing by executing:
```shell
pre-commit run pip-compile --all-files
```
## Project
[Hatch](https://hatch.pypa.io/) is used for project management. The project can be built using:
```shell
hatch build
```
Linting and syntax checking can be run with:
```shell
hatch fmt --check
```
Tests can be executed using:
```shell
hatch test
```
Raw data
{
"_id": null,
"home_page": null,
"name": "hdx-python-country",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "HDX, country, country code, currencies, currency, exchange rate, foreign exchange, fx, iso 3166, iso2, iso3, location, region",
"author": "Michael Rans",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/88/96/ac55b204699cd216a22a943f64aafac32bba818f624a5d44879d60368fad/hdx_python_country-3.9.6.tar.gz",
"platform": null,
"description": "[](https://github.com/OCHA-DAP/hdx-python-country/actions/workflows/run-python-tests.yaml)\n[](https://coveralls.io/github/OCHA-DAP/hdx-python-country?branch=main)\n[](https://github.com/astral-sh/ruff)\n[](https://pypistats.org/packages/hdx-python-country)\n\nThe HDX Python Country Library provides utilities to map between country and region\ncodes and names and to match administrative level names from different sources.\nIt also provides utilities for foreign exchange enabling obtaining current and historic\nFX rates for different currencies.\n\nIt provides country mappings including ISO 2 and ISO 3 letter codes (ISO 3166) and regions\nusing live official data from the [UN OCHA](https://vocabulary.unocha.org/) feed with\nfallbacks to an internal static file if there is any problem with retrieving data from\nthe url. (Also it is possible to force the use of the internal static files.)\n\nIt can exact match English, French, Spanish, Russian, Chinese and Arabic. There is a\nfuzzy matching for English look up that can handle abbreviations in country names like\nDem. for Democratic and Rep. for Republic.\n\nMapping administration level names from a source to a given base set is also handled\nincluding phonetic fuzzy name matching.\n\nIt also provides foreign exchange rates and conversion from amounts in local\ncurrency to USD and vice-versa. The conversion relies on Yahoo Finance, falling\nback on [currency-api](https://github.com/fawazahmed0/currency-api) for current rates, and Yahoo Finance falling back\non IMF data via IATI (with interpolation) for historic daily rates.\n\nFor more information, please read the [documentation](https://hdx-python-country.readthedocs.io/en/latest/).\n\nThis library is part of the [Humanitarian Data Exchange](https://data.humdata.org/)\n(HDX) project. If you have humanitarian related data, please upload your datasets to\nHDX.\n\n## Development\n\n### Environment\n\nDevelopment is currently done using Python 3.12. We recommend using a virtual\nenvironment such as ``venv``:\n\n```shell\n python -m venv venv\n source venv/bin/activate\n```\n\nIn your virtual environment, install all packages for development by running:\n\n```shell\n pip install -r requirements.txt\n```\n\n### Pre-commit\n\nBe sure to install `pre-commit`, which is run every time you make a git commit:\n\n```shell\n pip install pre-commit\n pre-commit install\n```\n\nWith pre-commit, all code is formatted according to\n[ruff](https://docs.astral.sh/ruff/) guidelines.\n\nTo check if your changes pass pre-commit without committing, run:\n\n```shell\n pre-commit run --all-files\n```\n\n### Testing\n\nEnsure you have the required packages to run the tests:\n\n```shell\n pip install -r requirements.txt\n```\n\nTo run the tests and view coverage, execute:\n\n```shell\n pytest -c --cov hdx\n```\n\n## Packages\n\n[uv](https://github.com/astral-sh/uv) is used for package management. If\nyou\u2019ve introduced a new package to the source code (i.e. anywhere in `src/`),\nplease add it to the `project.dependencies` section of `pyproject.toml` with\nany known version constraints.\n\nTo add packages required only for testing, add them to the `test` section under\n`[project.optional-dependencies]`.\n\nAny changes to the dependencies will be automatically reflected in\n`requirements.txt` with `pre-commit`, but you can re-generate the file without\ncommitting by executing:\n\n```shell\n pre-commit run pip-compile --all-files\n```\n\n## Project\n\n[Hatch](https://hatch.pypa.io/) is used for project management. The project can be built using:\n\n```shell\n hatch build\n```\n\nLinting and syntax checking can be run with:\n\n```shell\n hatch fmt --check\n```\n\nTests can be executed using:\n\n```shell\n hatch test\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "HDX Python country code and exchange rate (fx) utilities",
"version": "3.9.6",
"project_urls": {
"Homepage": "https://github.com/OCHA-DAP/hdx-python-country"
},
"split_keywords": [
"hdx",
" country",
" country code",
" currencies",
" currency",
" exchange rate",
" foreign exchange",
" fx",
" iso 3166",
" iso2",
" iso3",
" location",
" region"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4590646b56ec12df459799510d6d0869ada210ad9f765ad104e50dae4867eb50",
"md5": "a946827b3f54c4957fe7f0aca3349dc6",
"sha256": "4c1833bdf3cbd14dfff0146e0bdcae5763931d344fce5f1b42493dc8751e3d4a"
},
"downloads": -1,
"filename": "hdx_python_country-3.9.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a946827b3f54c4957fe7f0aca3349dc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 55554,
"upload_time": "2025-07-09T22:56:30",
"upload_time_iso_8601": "2025-07-09T22:56:30.128250Z",
"url": "https://files.pythonhosted.org/packages/45/90/646b56ec12df459799510d6d0869ada210ad9f765ad104e50dae4867eb50/hdx_python_country-3.9.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8896ac55b204699cd216a22a943f64aafac32bba818f624a5d44879d60368fad",
"md5": "8c9a62ab07a906fe7549e288e96be71e",
"sha256": "7791f4b9c5ae3e62e82795c266a3ca6ee23c7bab706c91533844edf2ebd9bb18"
},
"downloads": -1,
"filename": "hdx_python_country-3.9.6.tar.gz",
"has_sig": false,
"md5_digest": "8c9a62ab07a906fe7549e288e96be71e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 529232,
"upload_time": "2025-07-09T22:56:32",
"upload_time_iso_8601": "2025-07-09T22:56:32.162181Z",
"url": "https://files.pythonhosted.org/packages/88/96/ac55b204699cd216a22a943f64aafac32bba818f624a5d44879d60368fad/hdx_python_country-3.9.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 22:56:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OCHA-DAP",
"github_project": "hdx-python-country",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "annotated-types",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "astdoc",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "attrs",
"specs": [
[
"==",
"25.3.0"
]
]
},
{
"name": "babel",
"specs": [
[
"==",
"2.17.0"
]
]
},
{
"name": "backrefs",
"specs": [
[
"==",
"5.9"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.7.9"
]
]
},
{
"name": "cfgv",
"specs": [
[
"==",
"3.4.0"
]
]
},
{
"name": "chardet",
"specs": [
[
"==",
"5.2.0"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.2"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.2.1"
]
]
},
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "coverage",
"specs": [
[
"==",
"7.9.2"
]
]
},
{
"name": "distlib",
"specs": [
[
"==",
"0.3.9"
]
]
},
{
"name": "et-xmlfile",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "filelock",
"specs": [
[
"==",
"3.18.0"
]
]
},
{
"name": "frictionless",
"specs": [
[
"==",
"5.18.1"
]
]
},
{
"name": "ghp-import",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "hdx-python-utilities",
"specs": [
[
"==",
"3.8.7"
]
]
},
{
"name": "humanize",
"specs": [
[
"==",
"4.12.3"
]
]
},
{
"name": "identify",
"specs": [
[
"==",
"2.6.12"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "ijson",
"specs": [
[
"==",
"3.4.0"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "isodate",
"specs": [
[
"==",
"0.7.2"
]
]
},
{
"name": "jinja2",
"specs": [
[
"==",
"3.1.6"
]
]
},
{
"name": "jsonlines",
"specs": [
[
"==",
"4.0.0"
]
]
},
{
"name": "jsonpath-ng",
"specs": [
[
"==",
"1.7.0"
]
]
},
{
"name": "jsonschema",
"specs": [
[
"==",
"4.24.0"
]
]
},
{
"name": "jsonschema-specifications",
"specs": [
[
"==",
"2025.4.1"
]
]
},
{
"name": "libhxl",
"specs": [
[
"==",
"5.2.2"
]
]
},
{
"name": "loguru",
"specs": [
[
"==",
"0.7.3"
]
]
},
{
"name": "markdown",
"specs": [
[
"==",
"3.8.2"
]
]
},
{
"name": "markdown-it-py",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "marko",
"specs": [
[
"==",
"2.1.4"
]
]
},
{
"name": "markupsafe",
"specs": [
[
"==",
"3.0.2"
]
]
},
{
"name": "mdurl",
"specs": [
[
"==",
"0.1.2"
]
]
},
{
"name": "mergedeep",
"specs": [
[
"==",
"1.3.4"
]
]
},
{
"name": "mkapi",
"specs": [
[
"==",
"4.4.3"
]
]
},
{
"name": "mkdocs",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "mkdocs-get-deps",
"specs": [
[
"==",
"0.2.0"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
"==",
"9.6.15"
]
]
},
{
"name": "mkdocs-material-extensions",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "nodeenv",
"specs": [
[
"==",
"1.9.1"
]
]
},
{
"name": "openpyxl",
"specs": [
[
"==",
"3.1.5"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"25.0"
]
]
},
{
"name": "paginate",
"specs": [
[
"==",
"0.5.7"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "petl",
"specs": [
[
"==",
"1.7.16"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.3.8"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.6.0"
]
]
},
{
"name": "ply",
"specs": [
[
"==",
"3.11"
]
]
},
{
"name": "pre-commit",
"specs": [
[
"==",
"4.2.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.11.7"
]
]
},
{
"name": "pydantic-core",
"specs": [
[
"==",
"2.33.2"
]
]
},
{
"name": "pygments",
"specs": [
[
"==",
"2.19.2"
]
]
},
{
"name": "pymdown-extensions",
"specs": [
[
"==",
"10.16"
]
]
},
{
"name": "pyphonetics",
"specs": [
[
"==",
"0.5.3"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.4.1"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"6.2.1"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "python-io-wrapper",
"specs": [
[
"==",
"0.3.1"
]
]
},
{
"name": "python-slugify",
"specs": [
[
"==",
"8.0.4"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "pyyaml-env-tag",
"specs": [
[
"==",
"1.1"
]
]
},
{
"name": "ratelimit",
"specs": [
[
"==",
"2.2.1"
]
]
},
{
"name": "referencing",
"specs": [
[
"==",
"0.36.2"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.4"
]
]
},
{
"name": "requests-file",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "rfc3986",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"14.0.0"
]
]
},
{
"name": "rpds-py",
"specs": [
[
"==",
"0.26.0"
]
]
},
{
"name": "ruamel-yaml",
"specs": [
[
"==",
"0.18.14"
]
]
},
{
"name": "ruamel-yaml-clib",
"specs": [
[
"==",
"0.2.12"
]
]
},
{
"name": "shellingham",
"specs": [
[
"==",
"1.5.4"
]
]
},
{
"name": "simpleeval",
"specs": [
[
"==",
"1.0.3"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.17.0"
]
]
},
{
"name": "structlog",
"specs": [
[
"==",
"25.4.0"
]
]
},
{
"name": "tableschema-to-template",
"specs": [
[
"==",
"0.0.13"
]
]
},
{
"name": "tabulate",
"specs": [
[
"==",
"0.9.0"
]
]
},
{
"name": "tenacity",
"specs": [
[
"==",
"9.1.2"
]
]
},
{
"name": "text-unidecode",
"specs": [
[
"==",
"1.3"
]
]
},
{
"name": "typer",
"specs": [
[
"==",
"0.16.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.14.1"
]
]
},
{
"name": "typing-inspection",
"specs": [
[
"==",
"0.4.1"
]
]
},
{
"name": "unidecode",
"specs": [
[
"==",
"1.4.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.5.0"
]
]
},
{
"name": "validators",
"specs": [
[
"==",
"0.35.0"
]
]
},
{
"name": "virtualenv",
"specs": [
[
"==",
"20.31.2"
]
]
},
{
"name": "watchdog",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "wheel",
"specs": [
[
"==",
"0.45.1"
]
]
},
{
"name": "xlrd",
"specs": [
[
"==",
"2.0.2"
]
]
},
{
"name": "xlrd3",
"specs": [
[
"==",
"1.1.0"
]
]
},
{
"name": "xlsx2csv",
"specs": [
[
"==",
"0.8.4"
]
]
},
{
"name": "xlsxwriter",
"specs": [
[
"==",
"3.2.5"
]
]
},
{
"name": "xlwt",
"specs": [
[
"==",
"1.3.0"
]
]
}
],
"lcname": "hdx-python-country"
}
