OCHA-DAP · mcarans · Jan 29, 2026 · Jan 29, 2026 · Jan 29, 2026
diff --git a/.coveragerc b/.coveragerc
diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml
@@ -13,25 +13,22 @@ jobs:
       url: https://pypi.org/p/hdx-python-country
 
     permissions:
-      id-token: write  # IMPORTANT: mandatory for trusted publishing
+      id-token: write
+      contents: read
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
+
     - name: Get history and tags for versioning to work
       run: |
         git fetch --prune --unshallow
         git fetch --depth=1 origin +refs/tags/*:refs/tags/*
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-    - name: Install Hatch
-      uses: pypa/hatch@install
-    - name: Build with hatch
-      run: |
-        hatch build
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+
+    - name: Build with uv
+      run: uv build
+
     - name: Publish distribution 📦 to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
+      run: uv publish
diff --git a/.github/workflows/run-python-tests.yaml b/.github/workflows/run-python-tests.yaml
@@ -1,53 +1,49 @@
-# This workflow will install Python dependencies, lint and run tests
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-
 name: Run tests
 
 on:
-  workflow_dispatch: # add run button in github
+  workflow_dispatch:
   push:
-    branches-ignore:
-      - gh-pages
-      - 'dependabot/**'
+    branches-ignore: [gh-pages, "dependabot/**"]
   pull_request:
-    branches-ignore:
-      - gh-pages
+    branches-ignore: [gh-pages]
 
 jobs:
   build:
     runs-on: ubuntu-latest
-
     permissions:
+      contents: read
       checks: write
       pull-requests: write
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-    - name: Install Hatch
-      uses: pypa/hatch@install
-    - name: Test with hatch/pytest
-      run: |
-        hatch test
-    - name: Check styling
-      if: always()
-      run: |
-        hatch fmt --check
-    - name: Publish Unit Test Results
-      uses: EnricoMi/publish-unit-test-result-action@v2
-      if: always()
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        junit_files: test-results.xml
-    - name: Publish in Coveralls
-      uses: coverallsapp/github-action@v2
-      with:
-        github-token: ${{ secrets.GITHUB_TOKEN }}
-        flag-name: tests
-        format: lcov
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Check styling
+        run: |
+          uv run ruff format --check
+          uv run ruff check
+
+      - name: Test with pytest
+        run: uv run pytest
+
+      - name: Publish Unit Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        if: always()
+        with:
+          files: test-results.xml
+
+      - name: Publish in Coveralls
+        uses: coverallsapp/github-action@v2
+        if: always()
+        with:
+          flag-name: tests
+          format: lcov
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,26 +1,25 @@
 default_language_version:
-    python: python3.13
+  python: python3.13
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-ast
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.10
+    rev: v0.14.13
     hooks:
       # Run the linter.
       - id: ruff-check
         args: [ --fix ]
       # Run the formatter.
       - id: ruff-format
+
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.9.22
+    rev: 0.9.25
     hooks:
-      # Run the pip compile
-      - id: pip-compile
-        name: pip-compile requirements.txt
-        files: pyproject.toml
-        args: [ pyproject.toml, --resolver=backtracking, --upgrade, -q,
-                -o, requirements.txt ]
+      # Ensure the lockfile is up-to-date with pyproject.toml
+      - id: uv-lock
diff --git a/README.md b/README.md
@@ -31,30 +31,24 @@ This library is part of the [Humanitarian Data Exchange](https://data.humdata.or
 (HDX) project. If you have humanitarian related data, please upload your datasets to
 HDX.
 
-## Development
+# Development
 
-### Environment
+## Environment
 
-Development is currently done using Python 3.12. We recommend using a virtual
-environment such as ``venv``:
+Development is currently done using Python 3.13. The environment can be created with:
 
 ```shell
-    python -m venv venv
-    source venv/bin/activate
+    uv sync
 ```
 
-In your virtual environment, install all packages for development by running:
-
-```shell
-    pip install -r requirements.txt
-```
+This creates a .venv folder with the versions specified in the project's uv.lock file.
 
 ### Pre-commit
 
-Be sure to install `pre-commit`, which is run every time you make a git 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:
 
 ```shell
-    pip install pre-commit
     pre-commit install
 ```
 
@@ -67,54 +61,47 @@ To check if your changes pass pre-commit without committing, run:
     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]`.
+To add packages required only for testing, add them to the
+`[dependency-groups]`.
 
 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:
+`uv.lock` with `pre-commit`, but you can re-generate the files without committing by
+executing:
 
 ```shell
-    pre-commit run pip-compile --all-files
+    uv lock --upgrade
 ```
 
 ## Project
 
-[Hatch](https://hatch.pypa.io/) is used for project management. The project can be built using:
+[uv](https://github.com/astral-sh/uv) is used for project management. The project can be
+built using:
 
 ```shell
-    hatch build
+    uv build
 ```
 
 Linting and syntax checking can be run with:
 
 ```shell
-    hatch fmt --check
+    uv run ruff check
 ```
 
-Tests can be executed using:
+To run the tests and view coverage, execute:
 
 ```shell
-    hatch test
+    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`.
diff --git a/documentation/index.md b/documentation/index.md
@@ -42,6 +42,9 @@ The code for the library is [here](https://github.com/OCHA-DAP/hdx-python-countr
 The library has detailed API documentation which can be found in the menu at the top.
 
 ## Breaking Changes
+From 4.1.0, HXL hashtags no longer used in Country class. The header names are used
+instead.
+
 From 4.0.0, Python 3.10 or later is required as well as HDX Python Utilities >= 4. To
 continue using HDX Python Country < 4, please pin to HDX Python Utilities < 4.
 
@@ -92,26 +95,33 @@ The usage of the country mappings functionality is best illustrated by some exam
     # returns ("CZE", False)
 
     Country.get_country_info_from_iso2("jp")
-    # Returns dictionary with HXL hashtags as keys. For more on HXL, see http://hxlstandard.org/
-    # {"#country+alt+i_ar+name+v_m49": "اليابان", "#country+alt+i_ar+name+v_unterm": "اليابان",
-    # "#country+alt+i_en+name+v_m49": "Japan", "#country+alt+i_en+name+v_unterm": "Japan",
-    # "#country+alt+i_es+name+v_m49": "Japón", "#country+alt+i_es+name+v_unterm": "Japón",
-    # "#country+alt+i_fr+name+v_m49": "Japon", "#country+alt+i_fr+name+v_unterm": "Japon",
-    # "#country+alt+i_ru+name+v_m49": "Япония", "#country+alt+i_ru+name+v_unterm": "Япония",
-    # "#country+alt+i_zh+name+v_m49": "日本", "#country+alt+i_zh+name+v_unterm": "日本",
-    # "#country+alt+name+v_dgacm": "", "#country+alt+name+v_hpctools": "",
-    # "#country+alt+name+v_iso": "", "#country+alt+name+v_reliefweb": "",
-    # "#country+code+num+v_m49": "392", "#country+code+v_hpctools": "112",
-    # "#country+code+v_iso2": "JP", "#country+code+v_iso3": "JPN",
-    # "#country+code+v_reliefweb": "128", "#country+formal+i_en+name+v_unterm": "Japan",
-    # "#country+name+preferred": "Japan", "#country+name+short+v_reliefweb": "",
-    # "#country+regex": "japan", "#currency+code": "JPY", "#date+start": "1974-01-01",
-    # "#geo+admin_level": "0", "#geo+lat": "37.63209801", "#geo+lon": "138.0812256",
-    # "#indicator+bool+hrp": "", "#indicator+bool+gho": "", "#indicator+incomelevel": "High",
-    # "#meta+bool+deprecated": "N", "#meta+bool+independent": "Y", "#meta+id": "112",
-    # "#region+code+intermediate": "", "#region+code+main": "142", "#region+code+sub": "30",
-    # "#region+intermediate+name+preferred": "", "#region+main+name+preferred": "Asia",
-    # "#region+name+preferred+sub": "Eastern Asia"}
+    # Returns dictionary of country data
+    # {
+    #     "Admin Level": "0",                     "Appears in DGACM list": "Y",
+    #     "Appears in UNTERM list": "Y",          "Arabic Short": "اليابان",
+    #     "Chinese Short": "日本",                 "Concatenation": "112 - Japan",
+    #     "Currency": "JPY",                      "DGACM Alt Term": None,
+    #     "Deprecated": "N",                      "English Formal": "Japan",
+    #     "English Short": "Japan",               "French Short": "Japon",
+    #     "HPC Tools API ID": "112",              "HPC Tools Alt Term": None,
+    #     "Has HRP": None,                        "ID": "112",
+    #     "ISO 3166-1 Alpha 2-Codes": "JP",       "ISO 3166-1 Alpha 3-Codes": "JPN",
+    #     "ISO Alt Term": None,                   "In GHO": None,
+    #     "Independent": "Y",                     "Intermediate Region Code": None,
+    #     "Intermediate Region Name": None,       "Latitude": "37.63209801",
+    #     "Longitude": "138.0812256",             "M49 Arabic": "اليابان",
+    #     "M49 Chinese": "日本",                   "M49 English": "Japan",
+    #     "M49 French": "Japon",                  "M49 Russian": "Япония",
+    #     "M49 Spanish": "Japón",                 "Preferred Term": "Japan",
+    #     "RW API Alt Term": None,                "RW ID": "128",
+    #     "RW Short Name": None,                  "Reference Period Start": "1974-01-01",
+    #     "Regex": "japan",                       "Region Code": "142",
+    #     "Region Name": "Asia",                  "Russian Short": "Япония",
+    #     "Spanish Short": "Japón",               "Sub-region Code": "30",
+    #     "Sub-region Name": "Eastern Asia",      "World Bank Income Level": "High",
+    #     "m49 numerical code": "392",            "x Alpha2 codes": None,
+    #     "x Alpha3 codes": None
+    # }
     Country.get_countries_in_region("Channel Islands")
     # ["GGY", "JEY"]
     len(Country.get_countries_in_region("Africa"))

diff --git a/hatch.toml b/hatch.toml