hdx-python-country 3.7.1__tar.gz → 3.7.2__tar.gz

{hdx_python_country-3.7.1 → hdx_python_country-3.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hdx-python-country
-Version: 3.7.1
+Version: 3.7.2
 Summary: HDX Python country code and exchange rate (fx) utilities
 Project-URL: Homepage, https://github.com/OCHA-DAP/hdx-python-country
 Author: Michael Rans

{hdx_python_country-3.7.1 → hdx_python_country-3.7.2}/documentation/main.md

@@ -113,10 +113,19 @@ The administration level mappings takes input configuration dictionary,
 
 *admin_config* can have the following optional keys:
 
-*countries_fuzzy_try* are countries (iso3 codes) for which to try fuzzy matching. Default is all countries.
-*admin_name_mappings* is a dictionary of mappings from name to pcode (for where fuzzy matching fails)
-*admin_name_replacements* is a dictionary of textual replacements to try when fuzzy matching
-*admin_fuzzy_dont* is a list of names for which fuzzy matching should not be tried
+*countries_fuzzy_try* are countries (iso3 codes) for which to try fuzzy
+matching. Default is all countries.
+*admin_name_mappings* is a dictionary of mappings from name to pcode. These can
+be global or they can be restricted by country or parent (if the AdminLevel
+object has been set up with parents). Keys take the form "MAPPING",
+"AFG|MAPPING" or "AF01|MAPPING".
+*admin_name_replacements* is a dictionary of textual replacements to try when
+fuzzy matching. It maps from string to string replacement. The replacements can 
+be global or they can be restricted by country or parent (if the AdminLevel 
+object has been set up with parents). Keys take the form "STRING_TO_REPLACE",
+"AFG|STRING_TO_REPLACE" or "AF01|STRING_TO_REPLACE".
+*admin_fuzzy_dont* is a list of names for which fuzzy matching should not be
+tried
 
 Once an AdminLevel object is constructed, one of three setup methods must be
 called: *setup_from_admin_info*, *setup_from_libhxl_dataset* or

{hdx_python_country-3.7.1 → hdx_python_country-3.7.2}/src/hdx/location/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '3.7.1'
-__version_tuple__ = version_tuple = (3, 7, 1)
+__version__ = version = '3.7.2'
+__version_tuple__ = version_tuple = (3, 7, 2)

{hdx_python_country-3.7.1 → hdx_python_country-3.7.2}/src/hdx/location/adminlevel.py

@@ -306,7 +306,7 @@ class AdminLevel:
         """Get admin level for country
 
         Args:
-            countryiso3 (str): Iso3 country code
+            countryiso3 (str): ISO3 country code
 
         Returns:
             int: Admin level
@@ -320,7 +320,7 @@ class AdminLevel:
         """Get pcode length for country
 
         Args:
-            countryiso3 (str): Iso3 country code
+            countryiso3 (str): ISO3 country code
 
         Returns:
             Optional[int]: Country's pcode length or None
@@ -517,6 +517,41 @@ class AdminLevel:
             return pcode
         return None
 
+    def get_admin_name_replacements(
+        self, countryiso3: str, parent: Optional[str]
+    ) -> Dict[str, str]:
+        """Get relevant admin name replacements from admin name replacements
+        which is a dictionary of mappings from string to string replacement.
+        These can be global or they can be restricted by
+        country or parent (if the AdminLevel object has been set up with
+        parents). Keys take the form "STRING_TO_REPLACE",
+        "AFG|STRING_TO_REPLACE" or "AF01|STRING_TO_REPLACE".
+
+        Args:
+            countryiso3 (str): ISO3 country code
+            parent (Optional[str]): Parent admin code
+
+        Returns:
+            Dict[str, str]: Relevant admin name replacements
+        """
+        relevant_name_replacements = {}
+        for key, value in self.admin_name_replacements.items():
+            if "|" not in key:
+                if key not in relevant_name_replacements:
+                    relevant_name_replacements[key] = value
+                continue
+            prefix, name = key.split("|")
+            if parent:
+                if prefix == parent:
+                    if name not in relevant_name_replacements:
+                        relevant_name_replacements[name] = value
+                    continue
+            if prefix == countryiso3:
+                if name not in relevant_name_replacements:
+                    relevant_name_replacements[name] = value
+                continue
+        return relevant_name_replacements
+
     def fuzzy_pcode(
         self,
         countryiso3: str,
@@ -526,7 +561,7 @@ class AdminLevel:
         """Fuzzy match name to pcode
 
         Args:
-            countryiso3 (str): Iso3 country code
+            countryiso3 (str): ISO3 country code
             name (str): Name to match
             **kwargs:
             parent (Optional[str]): Parent admin code
@@ -543,8 +578,17 @@ class AdminLevel:
             if logname:
                 self.ignored.add((logname, countryiso3))
             return None
-        if self.use_parent and "parent" in kwargs:
-            parent = kwargs["parent"]
+        if self.use_parent:
+            parent = kwargs.get("parent")
+        else:
+            parent = None
+        if parent is None:
+            name_to_pcode = self.name_to_pcode.get(countryiso3)
+            if not name_to_pcode:
+                if logname:
+                    self.errors.add((logname, countryiso3))
+                return None
+        else:
             name_parent_to_pcode = self.name_parent_to_pcode.get(countryiso3)
             if not name_parent_to_pcode:
                 if logname:
@@ -555,15 +599,10 @@ class AdminLevel:
                 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
+            adm_name_lookup,
+            self.get_admin_name_replacements(countryiso3, parent),
         )
         pcode = name_to_pcode.get(
             adm_name_lookup, name_to_pcode.get(adm_name_lookup2)
@@ -643,6 +682,33 @@ class AdminLevel:
                 )
         return pcode
 
+    def get_name_mapped_pcode(
+        self, countryiso3: str, name: str, parent: Optional[str]
+    ) -> Optional[str]:
+        """Get pcode from admin name mappings which is a dictionary of mappings
+        from name to pcode. These can be global or they can be restricted by
+        country or parent (if the AdminLevel object has been set up with
+        parents). Keys take the form "MAPPING", "AFG|MAPPING" or
+        "AF01|MAPPING".
+
+        Args:
+            countryiso3 (str): ISO3 country code
+            name (str): Name to match
+            parent (Optional[str]): Parent admin code
+
+        Returns:
+            Optional[str]: P code match from admin name mappings or None if no match
+        """
+        if parent:
+            pcode = self.admin_name_mappings.get(f"{parent}|{name}")
+            if pcode is None:
+                pcode = self.admin_name_mappings.get(f"{countryiso3}|{name}")
+        else:
+            pcode = self.admin_name_mappings.get(f"{countryiso3}|{name}")
+        if pcode is None:
+            pcode = self.admin_name_mappings.get(name)
+        return pcode
+
     def get_pcode(
         self,
         countryiso3: str,
@@ -653,7 +719,7 @@ class AdminLevel:
         """Get pcode for a given name
 
         Args:
-            countryiso3 (str): Iso3 country code
+            countryiso3 (str): ISO3 country code
             name (str): Name to match
             fuzzy_match (bool): Whether to try fuzzy matching. Defaults to True.
             **kwargs:
@@ -663,9 +729,17 @@ class AdminLevel:
         Returns:
             Tuple[Optional[str], bool]: (Matched P code or None if no match, True if exact match or False if not)
         """
-        pcode = self.admin_name_mappings.get(name)
+        if self.use_parent:
+            parent = kwargs.get("parent")
+        else:
+            parent = None
+        pcode = self.get_name_mapped_pcode(countryiso3, name, parent)
         if pcode and self.pcode_to_iso3[pcode] == countryiso3:
-            return pcode, True
+            if parent:
+                if self.pcode_to_parent[pcode] == parent:
+                    return pcode, True
+            else:
+                return pcode, True
         if self.looks_like_pcode(name):
             pcode = name.upper()
             if pcode in self.pcodes:  # name is a p-code
@@ -677,8 +751,7 @@ class AdminLevel:
             )
             return pcode, True
         else:
-            if self.use_parent and "parent" in kwargs:
-                parent = kwargs["parent"]
+            if parent:
                 name_parent_to_pcode = self.name_parent_to_pcode.get(
                     countryiso3
                 )
@@ -756,3 +829,16 @@ class AdminLevel:
             logger.info(line)
             output.append(line)
         return output
+
+    def output_admin_name_replacements(self) -> List[str]:
+        """Output log of name replacements
+
+        Returns:
+            List[str]: List of name replacements
+        """
+        output = []
+        for name, replacement in self.admin_name_replacements.items():
+            line = f"{name}: {replacement}"
+            logger.info(line)
+            output.append(line)
+        return output

hdx_python_country-3.7.2/tests/fixtures/adminlevelparent.yaml

@@ -0,0 +1,25 @@
+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
+  - {pcode: AF0301, name: Charikar, iso3: AFG, parent: AF03}
+  - {pcode: AF0401, name: Maydan Shahr, iso3: AFG, parent: AF04}
+  - {pcode: AF0501, name: Pul-e-Alam, iso3: AFG, parent: AF05}
+  - {pcode: AF0501, name: Pul-e-Alam, iso3: AFG, parent: AF05}
+  - {pcode: CD2013, name: Mbanza-Ngungu, iso3: COD, parent: CD20}
+  - {pcode: CD3102, name: Kenge, iso3: COD, parent: CD31}
+  - {pcode: MW305, name: Blantyre, iso3: MWI, parent: MW3}
+
+admin_name_mappings:
+  "MyMapping": "AF0301"
+  "AFG|MyMapping2": "AF0401"
+  "AF05|MyMapping3": "AF0501"
+
+admin_name_replacements:
+  " city": ""
+
+alt1_admin_name_replacements:
+  "COD| city": ""
+
+alt2_admin_name_replacements:
+  "CD20| city": ""

{hdx_python_country-3.7.1 → hdx_python_country-3.7.2}/tests/hdx/location/test_adminlevel.py

@@ -14,6 +14,10 @@ class TestAdminLevel:
     def config(self):
         return load_yaml(join("tests", "fixtures", "adminlevel.yaml"))
 
+    @pytest.fixture(scope="function")
+    def config_parent(self):
+        return load_yaml(join("tests", "fixtures", "adminlevelparent.yaml"))
+
     @pytest.fixture(scope="function")
     def url(self):
         return "https://raw.githubusercontent.com/OCHA-DAP/hdx-python-country/main/tests/fixtures/global_pcodes_adm_1_2.csv"
@@ -161,6 +165,20 @@ class TestAdminLevel:
         assert output[31] == "Juba Dhexe: Middle Juba (SO27)"
         assert output[61] == "CU Niamey: Niamey (NER008)"
 
+        output = adminone.output_admin_name_replacements()
+        assert output == [
+            " urban: ",
+            "sud: south",
+            "ouest: west",
+            "est: east",
+            "nord: north",
+            "': ",
+            "/:  ",
+            ".:  ",
+            " region: ",
+            " oblast: ",
+        ]
+
     def test_adminlevel_fuzzy(self, config):
         adminone = AdminLevel(config)
         adminone.setup_from_admin_info(config["admin_info"])
@@ -184,10 +202,10 @@ class TestAdminLevel:
             "test - YEM: Matching (fuzzy) Al Dhale'e / الضالع to Ad Dali on map",
         ]
 
-    def test_adminlevel_parent(self, config):
-        admintwo = AdminLevel(config)
+    def test_adminlevel_parent(self, config_parent):
+        admintwo = AdminLevel(config_parent)
         admintwo.countries_fuzzy_try = None
-        admintwo.setup_from_admin_info(config["admin_info_with_parent"])
+        admintwo.setup_from_admin_info(config_parent["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") == (
@@ -223,6 +241,123 @@ class TestAdminLevel:
             "ABC", "Kabull", parent="AF02", logname="test"
         ) == (None, False)
 
+        output = admintwo.output_admin_name_mappings()
+        assert output == [
+            "MyMapping: Charikar (AF0301)",
+            "AFG|MyMapping2: Maydan Shahr (AF0401)",
+            "AF05|MyMapping3: Pul-e-Alam (AF0501)",
+        ]
+        assert admintwo.get_pcode("AFG", "MyMapping", logname="test") == (
+            "AF0301",
+            True,
+        )
+        assert admintwo.get_pcode(
+            "AFG", "MyMapping", parent="AF03", logname="test"
+        ) == ("AF0301", True)
+        assert admintwo.get_pcode(
+            "AFG", "MyMapping", parent="AF04", logname="test"
+        ) == (None, False)
+
+        assert admintwo.get_pcode("AFG", "MyMapping2", logname="test") == (
+            "AF0401",
+            True,
+        )
+        assert admintwo.get_pcode(
+            "AFG", "MyMapping2", parent="AF04", logname="test"
+        ) == ("AF0401", True)
+        assert admintwo.get_pcode(
+            "AFG", "MyMapping2", parent="AF05", logname="test"
+        ) == (None, False)
+
+        assert admintwo.get_pcode("AFG", "MyMapping3", logname="test") == (
+            None,
+            False,
+        )
+        assert admintwo.get_pcode(
+            "AFG", "MyMapping3", parent="AF05", logname="test"
+        ) == ("AF0501", True)
+        assert admintwo.get_pcode(
+            "AFG", "MyMapping3", parent="AF04", logname="test"
+        ) == (None, False)
+
+        output = admintwo.output_admin_name_replacements()
+        assert output == [" city: "]
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", logname="test"
+        ) == ("CD2013", False)
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", parent="CD20", logname="test"
+        ) == ("CD2013", False)
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", parent="CD19", logname="test"
+        ) == (None, False)
+        assert admintwo.get_pcode("COD", "Kenge city", logname="test") == (
+            "CD3102",
+            False,
+        )
+        assert admintwo.get_pcode("MWI", "Blantyre city", logname="test") == (
+            "MW305",
+            False,
+        )
+
+        admintwo.admin_name_replacements = config_parent[
+            "alt1_admin_name_replacements"
+        ]
+        output = admintwo.output_admin_name_replacements()
+        assert output == ["COD| city: "]
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", logname="test"
+        ) == ("CD2013", False)
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", parent="CD20", logname="test"
+        ) == ("CD2013", False)
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", parent="CD19", logname="test"
+        ) == (None, False)
+        assert admintwo.get_pcode("COD", "Kenge city", logname="test") == (
+            "CD3102",
+            False,
+        )
+        assert admintwo.get_pcode(
+            "COD", "Kenge city", parent="CD31", logname="test"
+        ) == ("CD3102", False)
+        assert admintwo.get_pcode("MWI", "Blantyre city", logname="test") == (
+            None,
+            False,
+        )
+        assert admintwo.get_pcode(
+            "MWI", "Blantyre city", parent="MW3", logname="test"
+        ) == (None, False)
+
+        admintwo.admin_name_replacements = config_parent[
+            "alt2_admin_name_replacements"
+        ]
+        output = admintwo.output_admin_name_replacements()
+        assert output == ["CD20| city: "]
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", logname="test"
+        ) == (None, False)
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", parent="CD20", logname="test"
+        ) == ("CD2013", False)
+        assert admintwo.get_pcode(
+            "COD", "Mbanza-Ngungu city", parent="CD19", logname="test"
+        ) == (None, False)
+        assert admintwo.get_pcode("COD", "Kenge city", logname="test") == (
+            None,
+            False,
+        )
+        assert admintwo.get_pcode(
+            "COD", "Kenge city", parent="CD31", logname="test"
+        ) == (None, False)
+        assert admintwo.get_pcode("MWI", "Blantyre city", logname="test") == (
+            None,
+            False,
+        )
+        assert admintwo.get_pcode(
+            "MWI", "Blantyre city", parent="MW3", logname="test"
+        ) == (None, False)
+
     def test_adminlevel_with_url(self, config, url):
         adminone = AdminLevel(config)
         with pytest.raises(HXLIOException):