Simplify i18n API

- Single `Language` class that takes a query and handles everything
- `get_language()` and `get_language_or_none` as goto calls to get it
- kept `find_language_names()` and `is_valid_iso_639_3()` but reusing `Language`

Author: rgaudin

Diff for: src/zimscraperlib/i18n.py

@@ -9,171 +9,188 @@
 ISO_LEVELS = ["1", "2b", "2t", "3", "5"]
 
 
-class NotFoundError(ValueError):
-    pass
+class NotFoundError(ValueError): ...
+
+
+class Language:
+    """Qualified ISO-639-3 language"""
+
+    def __init__(self, query: str):
+        """Instantiate a valid ISO-639-3 Language from query
+
+        params: either an ISO-639 code or a locale or an english language name"""
+        self.iso_639_1: str | None = None
+        self.iso_639_2b: str | None = None
+        self.iso_639_2t: str | None = None
+        self.iso_639_3: str | None = None
+        self.iso_639_5: str | None = None
+        self.english: str | None = None
+        self.native: str | None = None
+        self.iso_types: list[str] = []
+        self.query: str = query
+        self.native_query: str | None = None
+        self.querytype: str | None = None
+
+        def get_adjusted_query(query: str) -> tuple[str, str, str]:
+            # possibily an iso-639 code
+            if query.isalpha() and (2 <= len(query) <= 3):  # noqa: PLR2004
+                adjusted_query = query
+                native_query = query
+                query_type = "purecode"
+            # possibily a locale
+            elif all(x.isalpha() or x in ("-", "_") for x in query) and (
+                query.count("_") + query.count("-") == 1
+            ):
+                adjusted_query = re.split("-|_", query)[0]
+                native_query = query.replace("-", "_")
+                query_type = "locale"
+            # possibily an ISO language name
+            else:
+                adjusted_query = query.title().replace("Languages", "languages")
+                native_query = query
+                query_type = "languagename"
+            return adjusted_query, native_query, query_type
+
+        adjusted_query, self.native_query, self.querytype = get_adjusted_query(query)
 
-
-class Lang:
-
-    def __init__(self, requested_lang: str, iso639_lang_obj: iso639.Lang):
-        self.iso_639_1 = iso639_lang_obj.pt1 or None
-        self.iso_639_2b = iso639_lang_obj.pt2b or None
-        self.iso_639_2t = iso639_lang_obj.pt2t or None
-        self.iso_639_3 = iso639_lang_obj.pt3 or None
-        self.iso_639_5 = iso639_lang_obj.pt5 or None
-        self.english = iso639_lang_obj.name or None
+        try:
+            isolang = iso639.Lang(adjusted_query)
+        except (
+            iso639.exceptions.InvalidLanguageValue,
+            iso639.exceptions.DeprecatedLanguageValue,
+        ) as exc:
+            raise NotFoundError("Not a valid iso language name/code") from exc
+
+        parts_keys_map = {
+            "iso_639_1": "pt1",
+            "iso_639_2b": "pt2b",
+            "iso_639_2t": "pt2t",
+            "iso_639_3": "pt3",
+            "iso_639_5": "pt5",
+            "english": "name",
+        }
+
+        self.iso_639_1 = isolang.pt1 or None
+        self.iso_639_2b = isolang.pt2b or None
+        self.iso_639_2t = isolang.pt2t or None
+        self.iso_639_3 = isolang.pt3 or None
+        self.iso_639_5 = isolang.pt5 or None
+        self.english = isolang.name or None
         self.iso_types = [
             part_level
             for iso_level, part_level in [
                 (f"pt{level}", f"part{level}") for level in ISO_LEVELS
             ]
             + [("name", "name")]
-            if getattr(iso639_lang_obj, iso_level).lower() == requested_lang.lower()
+            if getattr(isolang, iso_level).lower() == adjusted_query.lower()
         ]
 
-
-class LangAndDetails:
-    def __init__(
-        self, lang: Lang, english_name: str, native: str, querytype: str, query: str
-    ):
-        self.iso_639_1 = lang.iso_639_1
-        self.iso_639_2b = lang.iso_639_2b
-        self.iso_639_2t = lang.iso_639_2t
-        self.iso_639_3 = lang.iso_639_3
-        self.iso_639_5 = lang.iso_639_5
-        self.iso_types = lang.iso_types
-        self.english = english_name
-        self.native = native
-        self.querytype = querytype
-        self.query = query
-
-    def __eq__(self, value: object) -> bool:
-        if not isinstance(value, LangAndDetails):
-            return False
-
-        return (
-            self.iso_639_1 == value.iso_639_1
-            and self.iso_639_2b == value.iso_639_2b
-            and self.iso_639_2t == value.iso_639_2t
-            and self.iso_639_3 == value.iso_639_3
-            and self.iso_639_5 == value.iso_639_5
-            and self.english == value.english
-            and self.native == value.native
-        )
-
-    def __repr__(self) -> str:
-        return (
-            f"iso_639_1:{self.iso_639_1}, iso_639_2b:{self.iso_639_2b}, "
-            f"iso_639_2t:{self.iso_639_2t}, iso_639_3:{self.iso_639_3}, "
-            f"iso_639_5:{self.iso_639_5}, iso_639_5:{self.english}, "
-            f"iso_639_5:{self.native}"
-        )
-
-
-def get_iso_lang_data(lang: str) -> tuple[Lang, Lang | None]:
-    """ISO-639-x languages details for lang. Raises NotFoundError
-
-    Returns a tuple (main_language, macro_language | None)"""
-
-    try:
-        isolang = iso639.Lang(lang)
-    except (
-        iso639.exceptions.InvalidLanguageValue,
-        iso639.exceptions.DeprecatedLanguageValue,
-    ) as exc:
-        raise NotFoundError("Not a valid iso language name/code") from exc
-
-    ourlang = Lang(lang, isolang)
-
-    macro = isolang.macro()
-
-    return (ourlang, get_iso_lang_data(macro.name)[0] if macro else None)
-
-
-def find_language_names(
-    query: str, lang_data: Lang | LangAndDetails | 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)
-        if not lang_data:
-            return query, query
-
-    try:
-        query_locale = babel.Locale.parse(query)
-        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_{level}" for level in reversed(ISO_LEVELS)]:
+        # update if language has a macro
+        if isolang.macro():
+            for iso_level in [f"iso_639_{level}" for level in ISO_LEVELS]:
+                if not getattr(self, iso_level):
+                    setattr(
+                        self,
+                        iso_level,
+                        # we'll get the pt attr for each iso_xxx
+                        getattr(isolang.macro(), parts_keys_map[iso_level], None)
+                        # we want None if value is empty
+                        or None,
+                    )
+
+        self.native, self.english = self._get_names_from(self.native_query)
+
+    def _get_names_from(self, query: str) -> tuple[str, str]:
+        """logic to find language names from babel and fallback"""
         try:
-            query_locale = babel.Locale.parse(getattr(lang_data, iso_level))
+            query_locale = babel.Locale.parse(query)
             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.english or query
-    return default, default
 
+        # ISO code lookup order matters (most qualified first)!
+        for iso_level in [f"iso_639_{level}" for level in reversed(ISO_LEVELS)]:
+            try:
+                query_locale = babel.Locale.parse(getattr(self, iso_level))
+                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 = self.english or query
+        return default, default
+
+    def todict(self) -> dict[str, str | None | list[str]]:
+        return {
+            key.replace("_", "-") if key.startswith("iso") else key: getattr(
+                self, key, None
+            )
+            for key in [
+                "iso_639_1",
+                "iso_639_2b",
+                "iso_639_2t",
+                "iso_639_3",
+                "iso_639_5",
+                "english",
+                "iso_types",
+                "native",
+                "querytype",
+                "query",
+            ]
+        }
 
-def update_with_macro(lang_data: Lang, macro_data: Lang | None):
-    """update empty keys from lang_data with ones of macro_data"""
-    if not macro_data:
-        return lang_data
+    def __repr__(self) -> str:
+        data_repr = ", ".join(
+            f'{key.replace("-", "_")}="{value}"' for key, value in self.todict().items()
+        )
+        return f"{type(self).__name__}({data_repr})"
 
-    for iso_level in [f"iso_639_{level}" for level in ISO_LEVELS]:
-        if not getattr(lang_data, iso_level):
-            setattr(lang_data, iso_level, getattr(macro_data, iso_level))
+    def __str__(self) -> str:
+        return f"{self.iso_639_3}: {self.english}"
 
-    return lang_data
+    def __eq__(self, value: object) -> bool:
+        return (
+            self.iso_639_1 == getattr(value, "iso_639_1", None)
+            and self.iso_639_2b == getattr(value, "iso_639_2b", None)
+            and self.iso_639_2t == getattr(value, "iso_639_2t", None)
+            and self.iso_639_3 == getattr(value, "iso_639_3", None)
+            and self.iso_639_5 == getattr(value, "iso_639_5", None)
+            and self.english == getattr(value, "english", None)
+            and self.native == getattr(value, "native", None)
+        )
 
 
-def get_language_details(
-    query: str, failsafe: bool | None = False  # noqa: FBT002
-) -> LangAndDetails | None:
-    """language details dict from query.
+def find_language_names(query: str) -> tuple[str, str]:
+    """(native, english) language names for query"""
+    try:
+        lang = Language(query)
+    except NotFoundError:
+        return query, query
+    # should be qualified but "None" is as valid as anything if not
+    return str(lang.native), str(lang.english)
 
-    When query fails, either raises NotFoundError or return None, based on failsafe
 
-    """
+def get_language(lang_code: str) -> Language:
+    """Language from lang_code"""
+    return Language(lang_code)
 
-    if query.isalpha() and (2 <= len(query) <= 3):  # noqa: PLR2004
-        # possibility of iso-639 code
-        adjusted_query = query
-        native_query = query
-        query_type = "purecode"
-    elif all(x.isalpha() or x in ("-", "_") for x in query) and (
-        query.count("_") + query.count("-") == 1
-    ):
-        # possibility of locale
-        adjusted_query = re.split("-|_", query)[0]
-        native_query = query.replace("-", "_")
-        query_type = "locale"
-    else:
-        # possibility of iso language name
-        adjusted_query = query.title().replace("Languages", "languages")
-        native_query = query
-        query_type = "languagename"
 
+def get_language_or_none(lang_code: str) -> Language | None:
+    """Language from lang_code or None if not found"""
     try:
-        lang_data, macro_data = get_iso_lang_data(adjusted_query)
-    except NotFoundError as exc:
-        if failsafe:
-            return None
-        raise exc
-
-    iso_data = update_with_macro(lang_data, macro_data)
-    native_name, english_name = find_language_names(native_query, iso_data)
-    return LangAndDetails(iso_data, english_name, native_name, query_type, query)
+        return get_language(lang_code)
+    except NotFoundError:
+        return None
 
 
 def is_valid_iso_639_3(code: str) -> bool:
     """whether code is a valid ISO-639-3 code"""
-    lang = get_language_details(code, failsafe=True)
+    lang = get_language_or_none(code)
     return lang is not None and lang.iso_639_3 == code

Diff for: tests/i18n/test_i18n.py

@@ -4,9 +4,11 @@
 import pytest
 
 from zimscraperlib.i18n import (
+    Language,
     NotFoundError,
     find_language_names,
-    get_language_details,
+    get_language,
+    get_language_or_none,
 )
 
 
@@ -168,11 +170,11 @@
 )
 def test_lang_details(query: str, expected: dict[str, Any] | None):
     if expected is None:
-        assert get_language_details(query, failsafe=True) == expected
+        assert get_language_or_none(query) == expected
         with pytest.raises(NotFoundError):
-            get_language_details(query)
+            get_language(query)
     else:
-        result = get_language_details(query)
+        result = get_language_or_none(query)
         assert result
         assert result.iso_639_1 == expected.get("iso-639-1")
         assert result.iso_639_2b == expected.get("iso-639-2b")
@@ -236,7 +238,7 @@ def mock_display_name(lang: str | None = None) -> str | None:
     ],
 )
 def test_lang_details_equality(query_left: str, query_right: str):
-    assert get_language_details(query_left) == get_language_details(query_right)
+    assert Language(query_left) == Language(query_right)
 
 
 @pytest.mark.parametrize(
@@ -252,9 +254,9 @@ def test_lang_details_equality(query_left: str, query_right: str):
     ],
 )
 def test_lang_details_inequality_with_patch(patch_attribute: str):
-    lang_and_details_patched = get_language_details("arq")
+    lang_and_details_patched = get_language("arq")
     setattr(lang_and_details_patched, patch_attribute, "foo")
-    assert get_language_details("arq") != lang_and_details_patched
+    assert get_language("arq") != lang_and_details_patched
 
 
 @pytest.mark.parametrize(
@@ -265,8 +267,8 @@ def test_lang_details_inequality_with_patch(patch_attribute: str):
     ],
 )
 def test_lang_details_inequality(query_left: str, query_right: str):
-    assert get_language_details(query_left) != get_language_details(query_right)
+    assert get_language(query_left) != get_language(query_right)
 
 
 def test_lang_details_inequality_objects():
-    assert get_language_details("ara") != "ara"
+    assert get_language("ara") != "ara"