hdx-python-country 3.5.4__tar.gz → 3.5.6__tar.gz

{hdx_python_country-3.5.4 → hdx_python_country-3.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hdx-python-country
-Version: 3.5.4
+Version: 3.5.6
 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>
@@ -26,7 +26,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Requires-Dist: hdx-python-utilities>=3.6.2
-Requires-Dist: libhxl
+Requires-Dist: libhxl>=5.0.3
 Requires-Dist: pyphonetics
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == 'dev'

{hdx_python_country-3.5.4 → hdx_python_country-3.5.6}/documentation/main.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 3.5.5, after creating an Adminlevel, call either setup_from_admin_info,
+setup_from_libhxl_dataset or setup_from_url.
+
 From 3.4.6, Python 3.7 no longer supported
 
 From 3.3.2, major update to foreign exchange code and use of new Yahoo data source
@@ -105,21 +108,33 @@ The usage of the country mappings functionality is best illustrated by some exam
 
 ## Administration Level
 
-The administration level mappings requires using an input configuration dictionary, 
-admin_config, with key *admin_info* which is a list with values of the form:
-
-    {"iso3": "AFG", "pcode": "AF01", "name": "Kabul"}
+The administration level mappings takes input configuration dictionary, 
+*admin_config*, which defaults to an empty dictionary.  
 
-Various other keys are optional:
+*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
 
+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*.
+
+Method *setup_from_admin_info* takes key *admin_info* which is a list with 
+values of the form:
+
+    {"iso3": "AFG", "pcode": "AF01", "name": "Kabul"}
+
+Method *setup_from_libhxl_dataset* takes a libhxl Dataset object, while
+*setup_from_url* takes a URL which defaults to the global p-codes dataset on 
+HDX.
+
 Examples of usage:
 
     adminlevel = AdminLevel(config)
+    adminlevel.setup_from_admin_info(admin_info)
     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)

{hdx_python_country-3.5.4 → hdx_python_country-3.5.6}/pyproject.toml

@@ -35,7 +35,7 @@ requires-python = ">=3.8"
 
 dependencies = [
     "hdx-python-utilities>=3.6.2",
-    "libhxl",
+    "libhxl>=5.0.3",
     "pyphonetics",
 ]
 dynamic = ["version"]

{hdx_python_country-3.5.4 → hdx_python_country-3.5.6}/requirements.txt

@@ -13,35 +13,31 @@ attrs==23.1.0
     #   jsonschema
 certifi==2023.7.22
     # via requests
-cfgv==3.3.1
+cfgv==3.4.0
     # via pre-commit
 chardet==5.2.0
     # via frictionless
 charset-normalizer==3.2.0
     # via requests
-click==8.1.6
+click==8.1.7
     # via typer
 colorama==0.4.6
     # via typer
-coverage[toml]==7.2.7
+coverage[toml]==7.3.1
     # via pytest-cov
-decorator==5.1.1
-    # via
-    #   jsonpath-ng
-    #   validators
 distlib==0.3.7
     # via virtualenv
 et-xmlfile==1.1.0
     # via openpyxl
-filelock==3.12.2
+filelock==3.12.4
     # via virtualenv
 frictionless==5.15.10
     # via hdx-python-utilities
 hdx-python-utilities==3.6.2
     # via hdx-python-country (pyproject.toml)
-humanize==4.7.0
+humanize==4.8.0
     # via frictionless
-identify==2.5.26
+identify==2.5.29
     # via pre-commit
 idna==3.4
     # via requests
@@ -53,17 +49,17 @@ isodate==0.6.1
     # via frictionless
 jinja2==3.1.2
     # via frictionless
-jsonlines==3.1.0
+jsonlines==4.0.0
     # via hdx-python-utilities
-jsonpath-ng==1.5.3
+jsonpath-ng==1.6.0
     # via libhxl
 jsonschema==4.17.3
     # via
     #   frictionless
     #   tableschema-to-template
-libhxl==5.0.2
+libhxl==5.0.3
     # via hdx-python-country (pyproject.toml)
-loguru==0.7.0
+loguru==0.7.2
     # via hdx-python-utilities
 markdown-it-py==3.0.0
     # via rich
@@ -79,21 +75,21 @@ openpyxl==3.1.2
     # via hdx-python-utilities
 packaging==23.1
     # via pytest
-petl==1.7.12
+petl==1.7.14
     # via frictionless
 platformdirs==3.10.0
     # via virtualenv
-pluggy==1.2.0
+pluggy==1.3.0
     # via pytest
 ply==3.11
     # via
     #   jsonpath-ng
     #   libhxl
-pre-commit==3.3.3
+pre-commit==3.4.0
     # via hdx-python-country (pyproject.toml)
-pydantic==2.1.1
+pydantic==2.3.0
     # via frictionless
-pydantic-core==2.4.0
+pydantic-core==2.6.3
     # via pydantic
 pygments==2.16.1
     # via rich
@@ -101,10 +97,9 @@ pyphonetics==0.5.3
     # via hdx-python-country (pyproject.toml)
 pyrsistent==0.19.3
     # via jsonschema
-pytest==7.4.0
+pytest==7.4.2
     # via
     #   hdx-python-country (pyproject.toml)
-    #   libhxl
     #   pytest-cov
 pytest-cov==4.1.0
     # via hdx-python-country (pyproject.toml)
@@ -133,20 +128,19 @@ requests-file==1.5.1
     # via hdx-python-utilities
 rfc3986==2.0.0
     # via frictionless
-rich==13.5.2
+rich==13.5.3
     # via typer
 ruamel-yaml==0.17.32
     # via hdx-python-utilities
 ruamel-yaml-clib==0.2.7
     # via ruamel-yaml
-shellingham==1.5.0.post1
+shellingham==1.5.3
     # via typer
 simpleeval==0.9.13
     # via frictionless
 six==1.16.0
     # via
     #   isodate
-    #   jsonpath-ng
     #   python-dateutil
     #   requests-file
 stringcase==1.2.0
@@ -161,7 +155,7 @@ text-unidecode==1.3
     # via python-slugify
 typer[all]==0.9.0
     # via frictionless
-typing-extensions==4.7.1
+typing-extensions==4.8.0
     # via
     #   frictionless
     #   pydantic
@@ -171,21 +165,21 @@ unidecode==1.3.6
     # via
     #   libhxl
     #   pyphonetics
-urllib3==2.0.4
+urllib3==2.0.5
     # via
     #   libhxl
     #   requests
-validators==0.20.0
+validators==0.22.0
     # via frictionless
-virtualenv==20.24.2
+virtualenv==20.24.5
     # via pre-commit
-wheel==0.41.1
+wheel==0.41.2
     # via libhxl
 xlrd==2.0.1
     # via hdx-python-utilities
 xlrd3==1.1.0
     # via libhxl
-xlsxwriter==3.1.2
+xlsxwriter==3.1.4
     # via tableschema-to-template
 xlwt==1.3.0
     # via hdx-python-utilities

hdx_python_country-3.5.6/src/hdx/location/_version.py

@@ -0,0 +1,6 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+from __future__ import annotations
+
+__version__ = version = '3.5.6'  # type: str
+__version_tuple__ = version_tuple = (3, 5, 6)  # type: tuple[int | str, ...]

{hdx_python_country-3.5.4 → hdx_python_country-3.5.6}/src/hdx/location/adminlevel.py

@@ -1,57 +1,113 @@
 import logging
 from typing import Dict, List, Optional, Tuple
 
+import hxl
+from hxl import InputOptions
+from hxl.input import HXLIOException
 from unidecode import unidecode
 
 from hdx.location.country import Country
 from hdx.location.names import clean_name
 from hdx.location.phonetics import Phonetics
 from hdx.utilities.text import multiple_replace
+from hdx.utilities.typehint import ListTuple
 
 logger = logging.getLogger(__name__)
 
 
 class AdminLevel:
-    """AdminLevel class which takes in pcodes and then maps names to those pcodes with fuzzy matching if necessary. The
-    input configuration dictionary, admin_config, requires key admin_info which is a list with values of the form:
-    ::
-        {"iso3": "AFG", "pcode": "AF01", "name": "Kabul"}
-
-    Various other keys are optional:
-    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
+    """AdminLevel class which takes in p-codes and then maps names to those
+    p-codes with fuzzy matching if necessary.
+
+    The dictionary admin_config, which defaults to an empty dictionary, 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 p-code (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
 
     Args:
-        admin_config (Dict): Configuration dictionary
+        admin_config (Dict): Configuration dictionary. Defaults to {}.
         admin_level (int): Admin level. Defaults to 1.
         admin_level_overrides (Dict): Countries at other admin levels.
     """
 
+    _admin_url_default = "https://data.humdata.org/dataset/cb963915-d7d1-4ffa-90dc-31277e24406f/resource/f65bc260-4d8b-416f-ac07-f2433b4d5142/download/global_pcodes_adm_1_2.csv"
+    _admin_url = _admin_url_default
+
     def __init__(
         self,
-        admin_config: Dict,
+        admin_config: Dict = {},
         admin_level: int = 1,
-        admin_level_overrides: Dict = dict(),
+        admin_level_overrides: Dict = {},
     ) -> None:
-        admin_info = admin_config["admin_info"]
         self.admin_level = admin_level
         self.admin_level_overrides = admin_level_overrides
         self.countries_fuzzy_try = admin_config.get("countries_fuzzy_try")
-        self.admin_name_mappings = admin_config.get(
-            "admin_name_mappings", dict()
-        )
+        self.admin_name_mappings = admin_config.get("admin_name_mappings", {})
         self.admin_name_replacements = admin_config.get(
-            "admin_name_replacements", dict()
+            "admin_name_replacements", {}
         )
         self.admin_fuzzy_dont = admin_config.get("admin_fuzzy_dont", list())
         self.pcodes = list()
-        self.pcode_lengths = dict()
-        self.name_to_pcode = dict()
-        self.pcode_to_name = dict()
-        self.pcode_to_iso3 = dict()
+        self.pcode_lengths = {}
+        self.name_to_pcode = {}
+        self.pcode_to_name = {}
+        self.pcode_to_iso3 = {}
+
+        self.init_matches_errors()
+        self.phonetics = Phonetics()
+
+    @classmethod
+    def set_default_admin_url(cls, admin_url: Optional[str] = None) -> None:
+        """
+        Set default admin URL from which to retrieve admin data
+
+        Args:
+            admin_url (Optional[str]): Admin URL from which to retrieve admin data. Defaults to internal value.
+
+        Returns:
+            None
+        """
+        if admin_url is None:
+            admin_url = cls._admin_url_default
+        cls._admin_url = admin_url
 
+    @classmethod
+    def get_libhxl_dataset(cls, admin_url: str = _admin_url) -> hxl.Dataset:
+        """
+        Get libhxl Dataset object given a URL which defaults to global p-codes
+        dataset on HDX.
+
+        Args:
+            admin_url (str): URL from which to load data. Defaults to global p-codes dataset.
+
+        Returns:
+            None
+        """
+        try:
+            return hxl.data(admin_url, InputOptions(encoding="utf-8"))
+        except HXLIOException:
+            logger.exception(
+                f"Setup of libhxl Dataset object with {admin_url} failed!"
+            )
+            raise
+
+    def setup_from_admin_info(self, admin_info: ListTuple[Dict]) -> None:
+        """
+        Setup p-codes from admin_info which is a list with values of the form:
+        ::
+            {"iso3": "AFG", "pcode": "AF01", "name": "Kabul"}
+        Args:
+            admin_info (ListTuple[Dict]): p-code dictionary
+
+        Returns:
+            None
+        """
         for row in admin_info:
             countryiso3 = row["iso3"]
             pcode = row.get("pcode")
@@ -59,12 +115,48 @@ class AdminLevel:
             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, dict())
+            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.init_matches_errors()
-        self.phonetics = Phonetics()
+
+    def setup_from_libhxl_dataset(self, libhxl_dataset: hxl.Dataset) -> None:
+        """
+        Setup p-codes from a libhxl Dataset object.
+
+        Args:
+            libhxl_dataset (hxl.Dataset): Dataset object from libhxl library
+
+        Returns:
+            None
+        """
+        admin_info = libhxl_dataset.with_rows(
+            f"#geo+admin_level={self.admin_level}"
+        )
+        for row in admin_info:
+            countryiso3 = row.get("#country+code")
+            pcode = row.get("#adm+code")
+            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
+
+    def setup_from_url(self, admin_url: str = _admin_url) -> None:
+        """
+        Setup p-codes from a URL. Defaults to global p-codes dataset on HDX.
+
+        Args:
+            admin_url (str): URL from which to load data. Defaults to global p-codes dataset.
+
+        Returns:
+            None
+        """
+        admin_info = self.get_libhxl_dataset(admin_url)
+        self.setup_from_libhxl_dataset(admin_info)
 
     def get_pcode_list(self) -> List[str]:
         """Get list of all pcodes

{hdx_python_country-3.5.4 → hdx_python_country-3.5.6}/src/hdx/location/country.py

@@ -69,8 +69,8 @@ class Country:
         "PROTECTORATE",
     ]
     _countriesdata = None
-    _ochaurl_int = "https://docs.google.com/spreadsheets/d/1NjSI2LaS3SqbgYc0HdD8oIb7lofGtiHgoKKATCpwVdY/export?format=csv&gid=1088874596"
-    _ochaurl = _ochaurl_int
+    _ochaurl_default = "https://docs.google.com/spreadsheets/d/1NjSI2LaS3SqbgYc0HdD8oIb7lofGtiHgoKKATCpwVdY/export?format=csv&gid=1088874596"
+    _ochaurl = _ochaurl_default
     _country_name_overrides = dict()
     _country_name_mappings = dict()
 
@@ -246,18 +246,18 @@ class Country:
         return cls._countriesdata
 
     @classmethod
-    def set_ocha_url(cls, url: str = None) -> None:
+    def set_ocha_url(cls, url: Optional[str] = None) -> None:
         """
-        Set World Bank url from which to retrieve countries data
+        Set OCHA url from which to retrieve countries data
 
         Args:
-            url (str): World Bank url from which to retrieve countries data. Defaults to internal value.
+            url (Optional[str]): OCHA url from which to retrieve countries data. Defaults to internal value.
 
         Returns:
             None
         """
         if url is None:
-            url = cls._ochaurl_int
+            url = cls._ochaurl_default
         cls._ochaurl = url
 
     @classmethod