hdx-python-country 3.6.9__tar.gz → 3.7.0__tar.gz

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/.github/workflows/publish.yaml

@@ -9,13 +9,13 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - 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@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: Install dependencies

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/.github/workflows/run-python-tests.yaml

@@ -18,9 +18,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: Install dependencies

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/CONTRIBUTING.md

@@ -21,15 +21,14 @@ you make a git commit:
     pre-commit install
 
 The configuration file for this project is in a
-non-start location. Thus, you will need to edit your
+non-standard location. Thus, you will need to edit your
 `.git/hooks/pre-commit` file to reflect this. Change
 the line that begins with `ARGS` to:
 
     ARGS=(hook-impl --config=.config/pre-commit-config.yaml --hook-type=pre-commit)
 
 With pre-commit, all code is formatted according to
-[black]("https://github.com/psf/black") and
-[ruff]("https://github.com/charliermarsh/ruff") guidelines.
+[ruff](https://github.com/astral-sh/ruff) guidelines.
 
 To check if your changes pass pre-commit without committing, run:
 
@@ -41,7 +40,7 @@ To run the tests and view coverage, execute:
 
     pytest -c .config/pytest.ini --cov hdx --cov-config .config/coveragerc
 
-Follow the example set out already in ``api.rst`` as you write the documentation.
+Follow the example set out already in ``documentation/main.md`` as you write the documentation.
 
 ## Packages
 

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: hdx-python-country
-Version: 3.6.9
+Version: 3.7.0
 Summary: HDX Python country code and exchange rate (fx) utilities
 Project-URL: Homepage, https://github.com/OCHA-DAP/hdx-python-country
-Author-email: Michael Rans <rans@email.com>
+Author: Michael Rans
 License: MIT
 License-File: LICENSE
 Keywords: HDX,country,country code,currencies,currency,exchange rate,foreign exchange,fx,iso 3166,iso2,iso3,location,region
@@ -25,7 +25,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
-Requires-Dist: hdx-python-utilities>=3.6.6
+Requires-Dist: hdx-python-utilities>=3.6.7
 Requires-Dist: libhxl>=5.2.1
 Requires-Dist: pyphonetics
 Provides-Extra: dev

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/documentation/main.md

@@ -126,6 +126,13 @@ Method *setup_from_admin_info* takes key *admin_info* which is a list with
 values of the form:
 
     {"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
+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
@@ -144,6 +151,7 @@ Examples of usage:
     adminlevel.get_pcode("YEM", "YEM030", logname="test")  # returns ("YE30", True)
     adminlevel.get_pcode("YEM", "Al Dhale"e / الضالع")  # returns ("YE30", False)
     adminlevel.get_pcode("YEM", "Al Dhale"e / الضالع", fuzzy_match=False)  # returns (None, True)
+    assert admintwo.get_pcode("AFG", "Kabul", parent="AF01") == ("AF0101", True)
 
 There is basic admin 1 p-code length conversion by default. A more advanced
 p-code length conversion can be activated by calling *load_pcode_formats*

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "hatchling.build"
 [project]
 name = "hdx-python-country"
 description = "HDX Python country code and exchange rate (fx) utilities"
-authors = [{name = "Michael Rans", email = "rans@email.com"}]
+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 = [
@@ -34,7 +34,7 @@ classifiers = [
 requires-python = ">=3.8"
 
 dependencies = [
-    "hdx-python-utilities>=3.6.6",
+    "hdx-python-utilities>=3.6.7",
     "libhxl>=5.2.1",
     "pyphonetics",
 ]

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/requirements.txt

@@ -23,17 +23,17 @@ click==8.1.7
     # via typer
 colorama==0.4.6
     # via typer
-coverage[toml]==7.4.3
+coverage[toml]==7.4.4
     # via pytest-cov
 distlib==0.3.8
     # via virtualenv
 et-xmlfile==1.1.0
     # via openpyxl
-filelock==3.13.1
+filelock==3.13.3
     # via virtualenv
 frictionless==5.16.1
     # via hdx-python-utilities
-hdx-python-utilities==3.6.6
+hdx-python-utilities==3.6.7
     # via hdx-python-country (pyproject.toml)
 humanize==4.9.0
     # via frictionless
@@ -85,7 +85,7 @@ ply==3.11
     # via
     #   jsonpath-ng
     #   libhxl
-pre-commit==3.6.2
+pre-commit==3.7.0
     # via hdx-python-country (pyproject.toml)
 pydantic==2.6.4
     # via frictionless
@@ -101,7 +101,7 @@ pytest==8.1.1
     # via
     #   hdx-python-country (pyproject.toml)
     #   pytest-cov
-pytest-cov==4.1.0
+pytest-cov==5.0.0
     # via hdx-python-country (pyproject.toml)
 python-dateutil==2.8.2
     # via
@@ -152,7 +152,7 @@ tabulate==0.9.0
     # via frictionless
 text-unidecode==1.3
     # via python-slugify
-typer[all]==0.9.0
+typer[all]==0.10.0
     # via frictionless
 typing-extensions==4.10.0
     # via
@@ -168,7 +168,7 @@ urllib3==2.2.1
     # via
     #   libhxl
     #   requests
-validators==0.22.0
+validators==0.24.0
     # via frictionless
 virtualenv==20.25.1
     # via pre-commit

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/src/hdx/location/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '3.6.9'
-__version_tuple__ = version_tuple = (3, 6, 9)
+__version__ = version = '3.7.0'
+__version_tuple__ = version_tuple = (3, 7, 0)

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/src/hdx/location/adminlevel.py

@@ -1,6 +1,6 @@
 import logging
 import re
-from typing import Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 
 import hxl
 from hxl import InputOptions
@@ -61,9 +61,12 @@ class AdminLevel:
         self.pcodes = []
         self.pcode_lengths = {}
         self.name_to_pcode = {}
+        self.name_parent_to_pcode = {}
         self.pcode_to_name = {}
         self.pcode_to_iso3 = {}
+        self.pcode_to_parent = {}
         self.pcode_formats = {}
+        self.use_parent = False
         self.zeroes = {}
         self.parent_admins = []
 
@@ -120,15 +123,55 @@ class AdminLevel:
             )
             raise
 
+    def setup_row(
+        self,
+        countryiso3: str,
+        pcode: str,
+        adm_name: str,
+        parent: Optional[str],
+    ):
+        """
+        Setup a single p-code
+
+        Args:
+            countryiso3 (str): Country
+            pcode (str): P-code
+            adm_name (str): Administrative name
+            parent (Optional[str]): Parent p-code
+
+        Returns:
+            None
+        """
+        self.pcode_lengths[countryiso3] = len(pcode)
+        self.pcodes.append(pcode)
+        self.pcode_to_name[pcode] = adm_name
+
+        name_to_pcode = self.name_to_pcode.get(countryiso3, {})
+        name_to_pcode[unidecode(adm_name).lower()] = pcode
+        self.name_to_pcode[countryiso3] = name_to_pcode
+        self.pcode_to_iso3[pcode] = countryiso3
+        self.pcode_to_iso3[pcode] = countryiso3
+
+        if self.use_parent:
+            name_parent_to_pcode = self.name_parent_to_pcode.get(
+                countryiso3, {}
+            )
+            name_to_pcode = name_parent_to_pcode.get(parent, {})
+            name_to_pcode[unidecode(adm_name).lower()] = pcode
+            name_parent_to_pcode[parent] = name_to_pcode
+            self.name_parent_to_pcode[countryiso3] = name_parent_to_pcode
+            self.pcode_to_parent[pcode] = parent
+
     def setup_from_admin_info(
         self,
         admin_info: ListTuple[Dict],
         countryiso3s: Optional[ListTuple[str]] = None,
     ) -> None:
         """
-        Setup p-codes from admin_info which is a list with values of the form:
+        Setup p-codes from admin_info which is a list with values of the form
+        below with parent optional:
         ::
-            {"iso3": "AFG", "pcode": "AF01", "name": "Kabul"}
+            {"iso3": "AFG", "pcode": "AF0101", "name": "Kabul", parent: "AF01"}
         Args:
             admin_info (ListTuple[Dict]): p-code dictionary
             countryiso3s (Optional[ListTuple[str]]): Countries to read. Defaults to None (all).
@@ -140,19 +183,15 @@ class AdminLevel:
             countryiso3s = [
                 countryiso3.upper() for countryiso3 in countryiso3s
             ]
+        self.use_parent = "parent" in admin_info[0]
         for row in admin_info:
             countryiso3 = row["iso3"].upper()
             if countryiso3s and countryiso3 not in countryiso3s:
                 continue
             pcode = row.get("pcode").upper()
-            self.pcodes.append(pcode)
-            self.pcode_lengths[countryiso3] = len(pcode)
             adm_name = row["name"]
-            self.pcode_to_name[pcode] = adm_name
-            name_to_pcode = self.name_to_pcode.get(countryiso3, {})
-            name_to_pcode[unidecode(adm_name).lower()] = pcode
-            self.name_to_pcode[countryiso3] = name_to_pcode
-            self.pcode_to_iso3[pcode] = countryiso3
+            parent = row.get("parent")
+            self.setup_row(countryiso3, pcode, adm_name, parent)
 
     def setup_from_libhxl_dataset(
         self,
@@ -176,19 +215,15 @@ class AdminLevel:
             countryiso3s = [
                 countryiso3.upper() for countryiso3 in countryiso3s
             ]
+        self.use_parent = "#adm+code+parent" in admin_info.display_tags
         for row in admin_info:
             countryiso3 = row.get("#country+code").upper()
             if countryiso3s and countryiso3 not in countryiso3s:
                 continue
             pcode = row.get("#adm+code").upper()
-            self.pcodes.append(pcode)
-            self.pcode_lengths[countryiso3] = len(pcode)
             adm_name = row.get("#adm+name")
-            self.pcode_to_name[pcode] = adm_name
-            name_to_pcode = self.name_to_pcode.get(countryiso3, {})
-            name_to_pcode[unidecode(adm_name).lower()] = pcode
-            self.name_to_pcode[countryiso3] = name_to_pcode
-            self.pcode_to_iso3[pcode] = countryiso3
+            parent = row.get("#adm+code+parent")
+            self.setup_row(countryiso3, pcode, adm_name, parent)
 
     def setup_from_url(
         self,
@@ -304,7 +339,7 @@ class AdminLevel:
         self.errors = set()
 
     def convert_admin_pcode_length(
-        self, countryiso3: str, pcode: str, logname: Optional[str] = None
+        self, countryiso3: str, pcode: str, **kwargs: Any
     ) -> Optional[str]:
         """Standardise pcode length by country and match to an internal pcode.
         Requires that p-code formats be loaded (eg. using load_pcode_formats)
@@ -312,11 +347,14 @@ class AdminLevel:
         Args:
             countryiso3 (str): ISO3 country code
             pcode (str): P code to match
-            logname (Optional[str]): Identifying name to use when logging. Defaults to None (don't log).
+            **kwargs:
+            parent (Optional[str]): Parent admin code
+            logname (str): Log using this identifying name. Defaults to not logging.
 
         Returns:
             Optional[str]: Matched P code or None if no match
         """
+        logname = kwargs.get("logname")
         match = self.pcode_regex.match(pcode)
         if not match:
             return None
@@ -480,18 +518,24 @@ class AdminLevel:
         return None
 
     def fuzzy_pcode(
-        self, countryiso3: str, name: str, logname: Optional[str] = None
+        self,
+        countryiso3: str,
+        name: str,
+        **kwargs: Any,
     ) -> Optional[str]:
         """Fuzzy match name to pcode
 
         Args:
             countryiso3 (str): Iso3 country code
             name (str): Name to match
-            logname (Optional[str]): Identifying name to use when logging. Defaults to None (don't log).
+            **kwargs:
+            parent (Optional[str]): Parent admin code
+            logname (str): Log using this identifying name. Defaults to not logging.
 
         Returns:
             Optional[str]: Matched P code or None if no match
         """
+        logname = kwargs.get("logname")
         if (
             self.countries_fuzzy_try is not None
             and countryiso3 not in self.countries_fuzzy_try
@@ -499,11 +543,24 @@ class AdminLevel:
             if logname:
                 self.ignored.add((logname, countryiso3))
             return None
-        name_to_pcode = self.name_to_pcode.get(countryiso3)
-        if not name_to_pcode:
-            if logname:
-                self.errors.add((logname, countryiso3))
-            return None
+        if self.use_parent and "parent" in kwargs:
+            parent = kwargs["parent"]
+            name_parent_to_pcode = self.name_parent_to_pcode.get(countryiso3)
+            if not name_parent_to_pcode:
+                if logname:
+                    self.errors.add((logname, countryiso3))
+                return None
+            name_to_pcode = name_parent_to_pcode.get(parent)
+            if not name_to_pcode:
+                if logname:
+                    self.errors.add((logname, countryiso3, parent))
+                return None
+        else:
+            name_to_pcode = self.name_to_pcode.get(countryiso3)
+            if not name_to_pcode:
+                if logname:
+                    self.errors.add((logname, countryiso3))
+                return None
         adm_name_lookup = clean_name(name)
         adm_name_lookup2 = multiple_replace(
             adm_name_lookup, self.admin_name_replacements
@@ -591,7 +648,7 @@ class AdminLevel:
         countryiso3: str,
         name: str,
         fuzzy_match: bool = True,
-        logname: Optional[str] = None,
+        **kwargs: Any,
     ) -> Tuple[Optional[str], bool]:
         """Get pcode for a given name
 
@@ -599,7 +656,9 @@ class AdminLevel:
             countryiso3 (str): Iso3 country code
             name (str): Name to match
             fuzzy_match (bool): Whether to try fuzzy matching. Defaults to True.
-            logname (Optional[str]): Identifying name to use when logging. Defaults to None (don't log).
+            **kwargs:
+            parent (Optional[str]): Parent admin code
+            logname (str): Log using this identifying name. Defaults to not logging.
 
         Returns:
             Tuple[Optional[str], bool]: (Matched P code or None if no match, True if exact match or False if not)
@@ -614,18 +673,30 @@ class AdminLevel:
             # name looks like a p-code, but doesn't match p-codes
             # so try adjusting p-code length
             pcode = self.convert_admin_pcode_length(
-                countryiso3, pcode, logname
+                countryiso3, pcode, **kwargs
             )
             return pcode, True
         else:
-            name_to_pcode = self.name_to_pcode.get(countryiso3)
-            if name_to_pcode is not None:
-                pcode = name_to_pcode.get(name.lower())
-                if pcode:
-                    return pcode, True
+            if self.use_parent and "parent" in kwargs:
+                parent = kwargs["parent"]
+                name_parent_to_pcode = self.name_parent_to_pcode.get(
+                    countryiso3
+                )
+                if name_parent_to_pcode:
+                    name_to_pcode = name_parent_to_pcode.get(parent)
+                    if name_to_pcode is not None:
+                        pcode = name_to_pcode.get(name.lower())
+                        if pcode:
+                            return pcode, True
+            else:
+                name_to_pcode = self.name_to_pcode.get(countryiso3)
+                if name_to_pcode is not None:
+                    pcode = name_to_pcode.get(name.lower())
+                    if pcode:
+                        return pcode, True
             if not fuzzy_match:
                 return None, True
-            pcode = self.fuzzy_pcode(countryiso3, name, logname)
+            pcode = self.fuzzy_pcode(countryiso3, name, **kwargs)
             return pcode, False
 
     def output_matches(self) -> List[str]:

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/tests/fixtures/adminlevel.yaml

@@ -556,3 +556,8 @@ admin_fuzzy_dont:
   - "sahil"
   - "say'on"
   - "syria"
+
+admin_info_with_parent:
+  - {pcode: AF0101, name: Kabul, iso3: AFG, parent: AF01}
+  - {pcode: AF0102, name: Paghman, iso3: AFG, parent: AF01}
+  - {pcode: AF0201, name: Kabul, iso3: AFG, parent: AF02}  # testing purposes

{hdx_python_country-3.6.9 → hdx_python_country-3.7.0}/tests/hdx/location/test_adminlevel.py

@@ -33,6 +33,8 @@ class TestAdminLevel:
         assert adminone.get_admin_level("YEM") == 1
         assert len(adminone.get_pcode_list()) == 433
         assert adminone.get_pcode_length("YEM") == 4
+        assert adminone.use_parent is False
+        assert adminone.pcode_to_iso3["YE30"] == "YEM"
         assert adminone.get_pcode("YEM", "YE30", logname="test") == (
             "YE30",
             True,
@@ -177,6 +179,45 @@ class TestAdminLevel:
             "test - YEM: Matching (fuzzy) Al Dhale'e / الضالع to Ad Dali on map",
         ]
 
+    def test_adminlevel_parent(self, config):
+        admintwo = AdminLevel(config)
+        admintwo.countries_fuzzy_try = None
+        admintwo.setup_from_admin_info(config["admin_info_with_parent"])
+        assert admintwo.use_parent is True
+        assert admintwo.pcode_to_parent["AF0101"] == "AF01"
+        assert admintwo.get_pcode("AFG", "AF0101", logname="test") == (
+            "AF0101",
+            True,
+        )
+        assert admintwo.get_pcode(
+            "AFG", "AF0101", parent="blah", logname="test"
+        ) == ("AF0101", True)
+        assert admintwo.get_pcode("AFG", "Kabul", logname="test") == (
+            "AF0201",
+            True,
+        )
+        assert admintwo.get_pcode(
+            "AFG", "Kabul", parent="AF01", logname="test"
+        ) == ("AF0101", True)
+        assert admintwo.get_pcode(
+            "AFG", "Kabul", parent="blah", logname="test"
+        ) == (None, False)
+        assert admintwo.get_pcode(
+            "AFG", "Kabul", parent="AF02", logname="test"
+        ) == ("AF0201", True)
+        assert admintwo.get_pcode(
+            "AFG", "Kabull", parent="AF01", logname="test"
+        ) == ("AF0101", False)
+        assert admintwo.get_pcode(
+            "AFG", "Kabull", parent="blah", logname="test"
+        ) == (None, False)
+        assert admintwo.get_pcode(
+            "AFG", "Kabull", parent="AF02", logname="test"
+        ) == ("AF0201", False)
+        assert admintwo.get_pcode(
+            "ABC", "Kabull", parent="AF02", logname="test"
+        ) == (None, False)
+
     def test_adminlevel_with_url(self, config, url):
         adminone = AdminLevel(config)
         with pytest.raises(HXLIOException):
@@ -190,12 +231,25 @@ class TestAdminLevel:
         adminone = AdminLevel(config)
         adminone.setup_from_url()
         assert adminone.get_admin_level("YEM") == 1
-        assert len(adminone.get_pcode_list()) == 2553
+        assert len(adminone.get_pcode_list()) == 2506
         assert adminone.get_pcode_length("YEM") == 4
         assert adminone.get_pcode("YEM", "YE30", logname="test") == (
             "YE30",
             True,
         )
+        assert adminone.get_pcode(
+            "YEM", "YE30", parent="YEM", logname="test"
+        ) == (
+            "YE30",
+            True,
+        )
+        # Exact match of p-code so doesn't need parent
+        assert adminone.get_pcode(
+            "YEM", "YE30", parent="Blah1", logname="test"
+        ) == (
+            "YE30",
+            True,
+        )
         assert adminone.get_pcode("YEM", "YEM30", logname="test") == (
             "YE30",
             True,
@@ -269,6 +323,19 @@ class TestAdminLevel:
             "YE30",
             False,
         )
+        assert adminone.get_pcode(
+            "YEM", "Ad Dal", parent="YEM", logname="test"
+        ) == (
+            "YE30",
+            False,
+        )
+        # Invalid parent means fuzzy matching won't match
+        assert adminone.get_pcode(
+            "YEM", "Ad Dal", parent="Blah2", logname="test"
+        ) == (
+            None,
+            False,
+        )
         assert adminone.get_pcode("YEM", "nord", logname="test") == (
             None,
             False,
@@ -307,6 +374,7 @@ class TestAdminLevel:
         assert output == [
             "test - Could not find ABC in map names!",
             "test - NER: Could not find ABCDEFGH in map names!",
+            "test - YEM: Could not find Blah2 in map names!",
         ]
 
     def test_adminlevel_pcode_formats(self, config, url, formats_url):
@@ -357,6 +425,7 @@ class TestAdminLevel:
 
         admintwo = AdminLevel(config, admin_level=2)
         admintwo.setup_from_url(admin_url=url)
+        assert admintwo.pcode_to_parent["YE3001"] == "YE30"
         assert admintwo.get_pcode("YEM", "YE03001", logname="test") == (
             None,
             True,
@@ -371,6 +440,12 @@ class TestAdminLevel:
             "YE3001",
             True,
         )
+        assert admintwo.get_pcode(
+            "YEM", "YEM3001", parent="Blah", logname="test"
+        ) == (
+            "YE3001",
+            True,
+        )
         assert admintwo.get_pcode("YEM", "YEM03001", logname="test") == (
             "YE3001",
             True,
@@ -456,6 +531,12 @@ class TestAdminLevel:
             None,
             True,
         )
+        assert admintwo.get_pcode(
+            "NER", "NE00409", parent="blah", logname="test"
+        ) == (
+            None,
+            True,
+        )
 
         admintwo.set_parent_admins_from_adminlevels([adminone])
         # The lookup in admin1 reveals that adding a 0 prefix to the admin1
@@ -465,6 +546,14 @@ class TestAdminLevel:
             "NER004009",
             True,
         )
+        # we don't use the parent because it could have a pcode length issue
+        # itself
+        assert admintwo.get_pcode(
+            "NER", "NE00409", parent="blah", logname="test"
+        ) == (
+            "NER004009",
+            True,
+        )
         # The lookup in admin1 reveals that removing the 0 prefix from the
         # admin1 is not a valid admin1 (CO80849) so the algorithm tries
         # removing the 0 prefix at the admin2 level instead and hence succeeds