Update from base

.github/workflows/publish.yaml

@@ -8,6 +8,13 @@ jobs:
   publish:
     runs-on: ubuntu-latest
 
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hdx-python-country
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
     steps:
     - uses: actions/checkout@v4
     - name: Get history and tags for versioning to work
@@ -26,9 +33,5 @@ jobs:
     - name: Build with hatch
       run: |
         hatch build
-    - name: Publish with hatch
-      env:
-        HATCH_INDEX_USER: ${{secrets.HATCH_INDEX_USER}}
-        HATCH_INDEX_AUTH: ${{secrets.HATCH_INDEX_AUTH}}
-      run: |
-        hatch publish
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

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

@@ -17,6 +17,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
 
+    permissions:
+      checks: write
+      pull-requests: write
+
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python

.gitignore

@@ -96,3 +96,6 @@ ENV/
 
 # hatch-vcs
 _version.py
+
+# Mac files
+.DS_Store

.config/pre-commit-config.yaml → .pre-commit-config.yaml

@@ -1,5 +1,5 @@
 default_language_version:
-    python: python3.12
+    python: python3.13
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
@@ -8,16 +8,15 @@ repos:
       - id: end-of-file-fixer
       - id: check-ast
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.7.0
+    rev: v0.12.0
     hooks:
       # Run the linter.
-      - id: ruff
-        args: [--config, .config/ruff.toml, --fix]
+      - id: ruff-check
+        args: [ --fix ]
       # Run the formatter.
       - id: ruff-format
-        args: [--config, .config/ruff.toml]
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.4.24
+    rev: 0.7.14
     hooks:
       # Run the pip compile
       - id: pip-compile

README.md

@@ -30,3 +30,91 @@ For more information, please read the [documentation](https://hdx-python-country
 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
+```

documentation/.readthedocs.yaml

@@ -1,16 +1,14 @@
+# Required
 version: 2
 
-mkdocs:
-  configuration: docs/mkdocs.yml
-  fail_on_warning: false
-
+# Set the version of Python and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "3.12"
   jobs:
     pre_build:
-      - pip install --upgrade mkdocs
-      - pip install mkdocs-material
-      - pip install pydoc-markdown
-      - pydoc-markdown documentation/pydoc-markdown.yaml
+      - pip install .[docs]
+
+mkdocs:
+  configuration: documentation/mkdocs.yaml

documentation/main.md → documentation/index.md

@@ -42,6 +42,8 @@ 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 3.9.2, must call Currency.setup before using Currency methods.
+
 From 3.7.5, removed clean_name function. There is now a function normalise in
 HDX Python Utilities.
 
@@ -68,9 +70,10 @@ The usage of the country mappings functionality is best illustrated by some exam
 
     from hdx.location.country import Country
 
-    Country.countriesdata(use_live=False, country_name_overrides={"PSE": "oPt"})
-    # Set up using non live data from repo rather and override default country name
-    # (Leaving out this step will use live data and no overrides)
+    Country.countriesdata(include_unofficial=True, use_live=False, country_name_overrides={"PSE": "oPt"})
+    # Set up including unofficial alpha2 (eg. AN) and alpha3 codes (eg. XKX)
+    # Use non live data from repo and override default country name
+    # (Leaving out this step will exclude unofficial alpha codes, use live data and no overrides)
     Country.get_country_name_from_iso3("jpn", use_live=False)  # returns "Japan"
     Country.get_country_name_from_iso3("vEn", formal=True)  # returns "the Bolivarian Republic of Venezuela"
     # uselive=False forces the use of internal files instead of accessing the live feeds.
@@ -87,18 +90,22 @@ The usage of the country mappings functionality is best illustrated by some exam
 
     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_unterm": "اليابان", "#country+alt+i_en+name+v_unterm": "Japan",
-    # "#country+alt+i_es+name+v_unterm": "Japón (el)", "#country+alt+i_fr+name+v_unterm": "Japon (le)",
-    # "#country+alt+i_ru+name+v_unterm": "Япония", "#country+alt+i_zh+name+v_unterm": "日本",
-    # "#country+alt+name+v_dgacm"": "", "#country+alt+name+v_fts": "",
-    # "#country+alt+name+v_hrinfo_country": "", "#country+alt+name+v_iso": "",
-    # "#country+alt+name+v_m49": "", "#country+alt+name+v_reliefweb": "",
-    # "#country+code+num+v_m49": "392", "#country+code+v_fts": "112",
-    # "#country+code+v_hrinfo_country": "292", "#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", "#date+start": "1974-01-01",
-    # "#geo+admin_level": "0", "#geo+lat": "37.63209801", "#geo+lon": "138.0812256", "#meta+id": "112",
+    # {"#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"}
@@ -187,9 +194,11 @@ AdminLevel objects in a list or lists of p-codes per parent admin level:
 
 ## Currencies
 
-Various functions support the conversion of monetary amounts to USD. Note that the
-returned values are cached to reduce network usage which means that the library is
-unsuited for use where rates are expected to update while the program is running:
+Various functions support the conversion of monetary amounts to USD. The setup
+method must be called once before using any other methods. Note that the
+returned values are cached to reduce network usage which means that the
+library is unsuited for use where rates are expected to update while the
+program is running:
 
     Currency.setup(fallback_historic_to_current=True, fallback_current_to_static=True, log_level=logging.INFO)
     currency = Country.get_currency_from_iso3("usa")  # returns "USD"

documentation/mkdocs.yaml

@@ -0,0 +1,17 @@
+site_name: HDX Python Country
+repo_url: https://github.com/OCHA-DAP/hdx-python-country/
+repo_name: OCHA-DAP/hdx-python-country
+docs_dir: .
+site_dir: ../site
+theme:
+  name: material
+  highlightjs: true
+plugins:
+  - search
+  - mkapi
+nav:
+  - Home: index.md
+  - API Documentation:
+    - Countries: $src/hdx.location.country.*
+    - Administration Level: $src/hdx.location.adminlevel.*
+    - Currencies: $src/hdx.location.currency.*