Process / return a new typed Lang class in i18n methods

Author: benoit74

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Automatically index PDF documents content #167
 - Automatically set proper title on PDF documents #168
 
+### Changed
+- **BREAKING** `i18n.get_language_details()`, `i18n.get_iso_lang_data()`, `i18n.find_language_names()` and `i18n.update_with_macro` now process / return a new typed `Lang` class #151
+
 ### Fixed
 
 - Metadata length validation is buggy for unicode strings #158

src/zimscraperlib/i18n.py

@@ -65,7 +65,78 @@ def setlocale(root_dir: pathlib.Path, locale_name: str):
         ) from exc
 
 
-def get_iso_lang_data(lang: str) -> tuple[dict, dict | None]:
+class Lang:
+    def __init__(self, lang_data: dict):
+        self._lang_data = lang_data
+
+    @property
+    def iso_639_1(self) -> str | None:
+        """ISO-639-1 language code"""
+        return self._lang_data["iso-639-1"]
+
+    @property
+    def iso_639_2b(self) -> str | None:
+        """ISO-639-2b language code"""
+        return self._lang_data["iso-639-2b"]
+
+    @property
+    def iso_639_2t(self) -> str | None:
+        """ISO-639-2t language code"""
+        return self._lang_data["iso-639-2t"]
+
+    @property
+    def iso_639_3(self) -> str | None:
+        """ISO-639-3 language code"""
+        return self._lang_data["iso-639-3"]
+
+    @property
+    def iso_639_5(self) -> str | None:
+        """ISO-639-5 language code"""
+        return self._lang_data["iso-639-5"]
+
+    @property
+    def english(self) -> str:
+        """language name in English"""
+        return self._lang_data["english"]
+
+    @property
+    def native(self) -> str:
+        """language name in native language"""
+        return self._lang_data["native"]
+
+    @property
+    def iso_types(self) -> list[str]:
+        """list of supported iso types"""
+        return self._lang_data["iso_types"]
+
+    @property
+    def query(self) -> list[str]:
+        """Query issued for these language details"""
+        return self._lang_data["query"]
+
+    @property
+    def querytype(self) -> list[str]:
+        """Type of query issued to retrieve language details"""
+        return self._lang_data["querytype"]
+
+    def get(self, attribute: str) -> str | None:
+        """Return language code for given ISO code"""
+        return self._lang_data.get(attribute)
+
+    def __eq__(self, value: object) -> bool:
+        """Compare with another value, either Lang or dict supported"""
+        if isinstance(value, Lang):
+            return self._lang_data == value._lang_data
+        if isinstance(value, dict):
+            return self._lang_data == value
+        return False
+
+    def __iter__(self):
+        """Iterate over dict properties"""
+        return self._lang_data.__iter__()
+
+
+def get_iso_lang_data(lang: str) -> tuple[Lang, Lang | None]:
     """ISO-639-x languages details for lang. Raises NotFound
 
     Included keys: iso-639-1, iso-639-2b, iso-639-2t, iso-639-3, iso-639-5
@@ -112,51 +183,54 @@ def replace_types(new_type: str) -> str:
 
     if isolang.macro():
         return (
-            lang_data,
+            Lang(lang_data),
             get_iso_lang_data(isolang.macro().name)[0],
         )  # first item in the returned tuple
-    return lang_data, None
+    return Lang(lang_data), None
 
 
-def find_language_names(query: str, lang_data: dict | None = None) -> tuple[str, str]:
-    """(native, english) language names for lang with help from language_details dict
+def find_language_names(query: str, lang_data: Lang | None = None) -> tuple[str, str]:
+    """(native, english) language names for lang with help from lang_data
 
     Falls back to English name if available or query if not"""
     if lang_data is None:
-        lang_data = get_language_details(query, failsafe=True) or {}
+        lang_data = get_language_details(query, failsafe=True)
+        if not lang_data:
+            return query, query
+
     try:
         query_locale = babel.Locale.parse(query)
-        return query_locale.get_display_name(), query_locale.get_display_name(
-            "en"
-        )  # pyright: ignore
+        if native_display_name := query_locale.get_display_name():
+            if english_display_name := query_locale.get_display_name("en"):
+                return native_display_name, english_display_name
     except (babel.UnknownLocaleError, TypeError, ValueError, AttributeError):
         pass
 
     # ISO code lookup order matters (most qualified first)!
     for iso_level in [f"iso-639-{lang_}" for lang_ in reversed(ISO_LEVELS)]:
         try:
             query_locale = babel.Locale.parse(lang_data.get(iso_level))
-            return query_locale.get_display_name(), query_locale.get_display_name(
-                "en"
-            )  # pyright: ignore
+            if native_display_name := query_locale.get_display_name():
+                if english_display_name := query_locale.get_display_name("en"):
+                    return native_display_name, english_display_name
         except (babel.UnknownLocaleError, TypeError, ValueError, AttributeError):
             pass
-    default = lang_data.get("english", query)
+    default = lang_data.get("english") or query
     return default, default
 
 
-def update_with_macro(lang_data: dict, macro_data: dict):
+def update_with_macro(lang_data: Lang, macro_data: Lang | None):
     """update empty keys from lang_data with ones of macro_data"""
     if macro_data:
-        for key, value in macro_data.items():
-            if key in lang_data and not lang_data[key]:
-                lang_data[key] = value
+        for key, value in macro_data._lang_data.items():
+            if key in lang_data and not lang_data.get(key):
+                lang_data._lang_data[key] = value
     return lang_data
 
 
 def get_language_details(
     query: str, failsafe: bool | None = False  # noqa: FBT002
-) -> dict:
+) -> Lang | None:
     """language details dict from query.
 
     Raises NotFound or return `und` language details if failsafe
@@ -194,12 +268,12 @@ def get_language_details(
         lang_data, macro_data = get_iso_lang_data(adjusted_query)
     except NotFound as exc:
         if failsafe:
-            return None  # pyright: ignore
+            return None
         raise exc
 
-    iso_data = update_with_macro(lang_data, macro_data)  # pyright: ignore
+    iso_data = update_with_macro(lang_data, macro_data)
     native_name, english_name = find_language_names(native_query, iso_data)
-    iso_data.update(
+    iso_data._lang_data.update(
         {
             "english": english_name,
             "native": native_name,

tests/i18n/test_i18n.py

@@ -190,7 +190,19 @@ def test_lang_details(query, expected):
         with pytest.raises(NotFound):
             get_language_details(query)
     else:
-        assert get_language_details(query) == expected
+        result = get_language_details(query)
+        assert result == expected
+        if result:
+            assert result.iso_639_1 == expected.get("iso-639-1")
+            assert result.iso_639_2b == expected.get("iso-639-2b")
+            assert result.iso_639_2t == expected.get("iso-639-2t")
+            assert result.iso_639_3 == expected.get("iso-639-3")
+            assert result.iso_639_5 == expected.get("iso-639-5")
+            assert result.english == expected.get("english")
+            assert result.native == expected.get("native")
+            assert result.iso_types == expected.get("iso_types")
+            assert result.query == expected.get("query")
+            assert result.querytype == expected.get("querytype")
 
 
 @pytest.mark.parametrize(