Repository files navigation

The HDX Python Country Library provides utilities to map between country and regioncodes and names and to match administrative level names from different sources.It also provides utilities for foreign exchange enabling obtaining current and historicFX rates for different currencies.

It provides country mappings including ISO 2 and ISO 3 letter codes (ISO 3166) and regionsusing live official data from theUN OCHA feed withfallbacks to an internal static file if there is any problem with retrieving data fromthe 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 afuzzy matching for English look up that can handle abbreviations in country names likeDem. for Democratic and Rep. for Republic.

Mapping administration level names from a source to a given base set is also handledincluding phonetic fuzzy name matching.

It also provides foreign exchange rates and conversion from amounts in localcurrency to USD and vice-versa. The conversion relies on Yahoo Finance, fallingback oncurrency-api for current rates, and Yahoo Finance falling backon IMF data via IATI (with interpolation) for historic daily rates.

For more information, please read thedocumentation.

This library is part of theHumanitarian Data Exchange(HDX) project. If you have humanitarian related data, please upload your datasets toHDX.

Development is currently done using Python 3.12. We recommend using a virtualenvironment such asvenv:

    python -m venv venvsource venv/bin/activate

In your virtual environment, install all packages for development by running:

    pip install -r requirements.txt

Be sure to installpre-commit, which is run every time you make a git commit:

    pip install pre-commit    pre-commit install

With pre-commit, all code is formatted according toruff guidelines.

To check if your changes pass pre-commit without committing, run:

    pre-commit run --all-files

Ensure you have the required packages to run the tests:

    pip install -r requirements.txt

To run the tests and view coverage, execute:

    pytest -c --cov hdx

uv is used for package management. Ifyou’ve introduced a new package to the source code (i.e. anywhere insrc/),please add it to theproject.dependencies section ofpyproject.toml withany known version constraints.

To add packages required only for testing, add them to thetest section under[project.optional-dependencies].

Any changes to the dependencies will be automatically reflected inrequirements.txt withpre-commit, but you can re-generate the file withoutcommitting by executing:

    pre-commit run pip-compile --all-files

Hatch is used for project management. The project can be built using:

    hatch build

Linting and syntax checking can be run with:

    hatch fmt --check

Tests can be executed using:

    hatchtest