hdx-python-utilities 4.1.0

HDX Python Utilities for streaming tabular data, date and time handling and other helpful functions

The HDX Python Utilities Library provides a range of helpful utilities for Python developers. Note that these are not specific to HDX.

1. Easy downloading of files with support for authentication, streaming and hashing
2. Retrieval of data from url with saving to file or from data previously saved
3. Date utilities
4. Loading and saving JSON and YAML (maintaining order)
5. Dictionary and list utilities
6. HTML utilities (inc. BeautifulSoup helper)
7. Compare files (eg. for testing)
8. Simple emailing
9. Easy logging setup and error logging
10. State utility
11. Path utilities
12. URL utilities
13. Text processing
14. Stable file hashing
15. Matching utilities
16. Encoding utilities
17. Check valid UUID
18. Easy building and packaging

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.