hdx-python-country 4.0.1__tar.gz → 4.1.1__tar.gz

hdx_python_country-4.1.1/.github/workflows/publish.yaml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hdx-python-country
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - 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: Install uv
+      uses: astral-sh/setup-uv@v7
+
+    - name: Build with uv
+      run: uv build
+
+    - name: Publish distribution 📦 to PyPI
+      run: uv publish

hdx_python_country-4.1.1/.github/workflows/run-python-tests.yaml

@@ -0,0 +1,49 @@
+name: Run tests
+
+on:
+  workflow_dispatch:
+  push:
+    branches-ignore: [gh-pages, "dependabot/**"]
+  pull_request:
+    branches-ignore: [gh-pages]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
+
+    steps:
+      - 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

{hdx_python_country-4.0.1 → hdx_python_country-4.1.1}/.pre-commit-config.yaml

@@ -1,5 +1,6 @@
 default_language_version:
-    python: python3.13
+  python: python3.13
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -7,20 +8,18 @@ repos:
       - 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

{hdx_python_country-4.0.1 → hdx_python_country-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hdx-python-country
-Version: 4.0.1
+Version: 4.1.1
 Summary: HDX Python country code and exchange rate (fx) utilities
 Project-URL: Homepage, https://github.com/OCHA-DAP/hdx-python-country
 Author: Michael Rans
@@ -18,23 +18,17 @@ Classifier: Operating System :: Unix
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: hdx-python-utilities>=4.0.1
-Requires-Dist: libhxl>=5.2.2
+Requires-Dist: hdx-python-utilities<5,>=4.0.4
 Requires-Dist: tenacity
-Provides-Extra: dev
-Requires-Dist: pre-commit; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkapi; extra == 'docs'
-Provides-Extra: test
-Requires-Dist: pytest; extra == 'test'
-Requires-Dist: pytest-cov; extra == 'test'
 Description-Content-Type: text/markdown
 
 [![Build Status](https://github.com/OCHA-DAP/hdx-python-country/actions/workflows/run-python-tests.yaml/badge.svg)](https://github.com/OCHA-DAP/hdx-python-country/actions/workflows/run-python-tests.yaml)
@@ -70,30 +64,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
 ```
 
@@ -106,20 +94,6 @@ 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
@@ -127,33 +101,40 @@ 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`.

{hdx_python_country-4.0.1 → hdx_python_country-4.1.1}/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,20 +61,6 @@ 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
@@ -88,33 +68,40 @@ 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`.

{hdx_python_country-4.0.1 → hdx_python_country-4.1.1}/documentation/index.md

@@ -42,7 +42,15 @@ 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.0.0, Python 3.10 or later is required
+From 4.1.1, HXL hashtags no longer used in AdminLevel class. The header names are used
+instead. setup_from_iterable replaces setup_from_admin_info and
+setup_from_libhxl_dataset using keys: "Location", "P-Code", "Name" and "Parent P-Code".
+
+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.
 
 From 3.9.2, must call Currency.setup before using Currency methods.
 
@@ -91,26 +99,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"))
@@ -143,23 +158,21 @@ A Retrieve object can be passed in the *retriever* parameter that enables
 saving data downloaded to a file or loading previously saved data depending
 on how the Retrieve object is configured.
 
-Once an AdminLevel object is constructed, one of three setup methods must be
-called: *setup_from_admin_info*, *setup_from_libhxl_dataset* or
-*setup_from_url*.
+Once an AdminLevel object is constructed, either *setup_from_iterable* or
+*setup_from_url* must be called.
+
+Method *setup_from_iterable* takes an iterable (eg. iterator or sequence) of the form:
 
-Method *setup_from_admin_info* takes key *admin_info* which is a list with
-values of the form:
+    {"Location": "AFG", "P-Code": "AF01", "Name": "Kabul"}
+    {"Location": "AFG", "P-Code": "AF0101", "Name": "Kabul", "Parent P-Code": "AF01"}
 
-    {"iso3": "AFG", "pcode": "AF01", "name": "Kabul"}
-    {"iso3": "AFG", "pcode": "AF0101", "name": "Kabul", "parent": "AF01"}
 
 Dictionaries *pcode_to_name* and *pcode_to_iso3* are populated in the
-AdminLevel object. *parent* is optional, but if provided enables lookup of
+AdminLevel object. *Parent P-Code* is optional, but if provided enables lookup of
 location names by both country and parent rather than just country which should
 help with any name clashes. It also results in the population of a dictionary
 in the AdminLevel object *pcode_to_parent*.
 
-Method *setup_from_libhxl_dataset* takes a libhxl Dataset object, while
 *setup_from_url* takes a URL which defaults to a resource in the global p-codes
 dataset on HDX.
 

hdx_python_country-4.1.1/pyproject.toml

@@ -0,0 +1,139 @@
+#########################
+# Project Configuration #
+#########################
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hdx-python-country"
+description = "HDX Python country code and exchange rate (fx) utilities"
+authors = [{name = "Michael Rans"}]
+license = {text = "MIT"}
+keywords = ["HDX", "location", "country", "country code", "iso 3166", "iso2", "iso3", "region", "fx", "currency", "currencies", "exchange rate", "foreign exchange"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Unix",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+]
+readme = "README.md"
+dynamic = ["version"]
+requires-python = ">=3.10"
+
+dependencies = [
+    "hdx-python-utilities>=4.0.4,<5",
+    "tenacity",
+]
+
+[project.optional-dependencies]
+docs = ["mkapi"]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "pre-commit",
+    "ruff==0.14.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/OCHA-DAP/hdx-python-country"
+
+# ----------------------------------------------------------------------------
+# Hatchling (Build & Versioning)
+# ----------------------------------------------------------------------------
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+local_scheme = "no-local-version"
+version_scheme = "python-simplified-semver"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/hdx/location/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hdx"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+# ----------------------------------------------------------------------------
+# Ruff (Linting & Formatting)
+# ----------------------------------------------------------------------------
+
+[tool.ruff]
+target-version = "py310"
+src = ["src"]
+exclude = ["_version.py"]
+
+[tool.ruff.lint]
+# Defaults are E (pycodestyle) and F (pyflakes). We extend them:
+extend-select = [
+  "I",   # isort
+  "UP",  # pyupgrade
+]
+ignore = [
+    "E501", # Line too long
+]
+
+[tool.ruff.lint.isort]
+known-local-folder = ["hdx.location"]
+known-third-party = [
+    "hdx.utilities",
+]
+
+# ----------------------------------------------------------------------------
+# Pytest (Testing)
+# ----------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+pythonpath = "src"
+log_cli = true
+addopts = """
+    --color=yes
+    --rootdir=.
+    --junitxml=test-results.xml
+    --cov
+    --no-cov-on-fail
+    --cov-report=lcov
+    --cov-report=term-missing
+"""
+
+# ----------------------------------------------------------------------------
+# Coverage (Reporting)
+# ----------------------------------------------------------------------------
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/_version.py"]
+
+[tool.coverage.report]
+exclude_also = [
+    "from ._version",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@(abc\\.)?abstractmethod",
+]