ENH case-insensitive matching and ignore leading/trailing whitespace

Author: jacksonllee

CHANGELOG.md

@@ -17,10 +17,16 @@ major/minor/micro version numbers like `05` (it'd have to be just `5`).
 ### Fixed
 ### Security
 
+## [2025.2.18]
+
+### Added
+* `Language.match` now supports case-insensitive matching
+  and ignores leading/trailing whitespace by default.
+
 ## [2025.2.8]
 
 ### Added
-* Explcitly indicated that the library is type-annotated.
+* Explicitly indicated that the library is type-annotated.
 
 ## [2025.1.28]
 

README.md

@@ -45,13 +45,13 @@ Create a `Language` instance by one of the class methods.
 Language(part3='fra', part2b='fre', part2t='fra', part1='fr', scope='I', type='L', name='French', comment=None, other_names=None, macrolanguage=None, retire_reason=None, retire_change_to=None, retire_remedy=None, retire_date=None)
 ```
 
-Fast object instantiation for retrieving language information (run on Python 3.13, macOS 15.2, Apple M1 Pro)
+Fast object instantiation for retrieving language information (run on Python 3.13, macOS 15.3.1, Apple M1 Pro)
 
 ```python
 In [1]: import iso639
 
 In [2]: %timeit iso639.Language.from_part3("fra")
-220 ns ± 0.658 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
+217 ns ± 0.139 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 ```
 
 #### From Another ISO 639 Code Set or a Reference Name
@@ -116,11 +116,27 @@ Use the `match` classmethod:
 True
 ```
 
+By default, the classmethod `match` supports case-insensitive matching
+and ignores leading/trailing whitespace.
+To enforce exact matching instead, pass in `exact=True`:
+
+```python
+>>> lang5 = iso639.Language.match('FRA')
+>>> lang6 = iso639.Language.match('fra ')
+>>> lang7 = iso639.Language.match('french')
+>>> lang4 == lang5 == lang6 == lang7
+True
+>>> iso639.Language.match("french", exact=True)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+LanguageNotFoundError: 'french' isn't an ISO language code or name
+```
+
 The classmethod `match` is particularly useful for consistently
 accessing a specific attribute from unknown inputs, e.g., the ISO 639-3 code.
 
 ```python
->>> 'fra' == lang1.part3 == lang2.part3 == lang3.part3 == lang4.part3
+>>> 'fra' == lang1.part3 == lang2.part3 == lang3.part3 == lang4.part3 == lang5.part3 == lang6.part3 == lang7.part3
 True
 ```
 
@@ -223,7 +239,6 @@ Beyond that, the precise order in matching is as follows:
 * ISO 639-3 alternative language names (the "print" ones)
 * ISO 639-3 alternative language names (the "inverted" ones)
 
-Only exact matching is done (there's no fuzzy string matching of any sort).
 As soon as a match is found, `Language.match` returns a `Language` instance.
 If there isn't a match, a `LanguageNotFoundError` is raised.
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-iso639"
-version = "2025.2.8"
+version = "2025.2.18"
 description = "ISO 639 language codes, names, and other associated information"
 readme = "README.md"
 requires-python = ">= 3.9"

src/iso639/language.py

@@ -5,7 +5,7 @@
 import datetime
 from dataclasses import dataclass
 
-from typing import Dict, List, Union, Set
+from typing import Dict, List, NoReturn, Optional, Union, Set
 
 from ._data import (
     _PART3_TO_CODES,
@@ -26,6 +26,12 @@
 )
 
 
+_STRING_CLEANING_FUNCS = [
+    lambda x: x.strip().lower(),
+    lambda x: x.strip().title(),
+]
+
+
 class LanguageNotFoundError(Exception):
     pass
 
@@ -100,13 +106,17 @@ def __eq__(self, other) -> bool:
         return isinstance(other, Language) and self.part3 == other.part3
 
     @classmethod
-    def match(cls, user_input: str, /) -> Language:
+    def match(cls, user_input: str, /, *, exact: bool = False) -> Language:
         """Return a ``Language`` instance by matching on the user input.
 
         Parameters
         ----------
         user_input : str
             A language code or name.
+        exact : bool, optional
+            Whether to enforce exact matching against the user input.
+            Defaults to `False`. If `False`, matching is case-insensitive
+            and ignores leading/trailing whitespace.
 
         Returns
         -------
@@ -140,29 +150,29 @@ def match(cls, user_input: str, /) -> Language:
             _NameIndexColumn.PRINT_NAME,
             _NameIndexColumn.INVERTED_NAME,
         ]
-        return _PART3_TO_LANGUAGES[_get_part3(user_input, query_order)]
+        return _PART3_TO_LANGUAGES[_get_part3(user_input, query_order, exact)]
 
     @classmethod
     def from_part3(cls, user_input: str, /) -> Language:
         """Return a ``Language`` instance from an ISO 639-3 code."""
         return _PART3_TO_LANGUAGES[
-            _get_part3(user_input, [_CodesColumn.ID, _RetirementsColumn.ID])
+            _get_part3_exact(user_input, [_CodesColumn.ID, _RetirementsColumn.ID])
         ]
 
     @classmethod
     def from_part2b(cls, user_input: str, /) -> Language:
         """Return a ``Language`` instance from an ISO 639-2 (bibliographic) code."""
-        return _PART3_TO_LANGUAGES[_get_part3(user_input, [_CodesColumn.PART2B])]
+        return _PART3_TO_LANGUAGES[_get_part3_exact(user_input, [_CodesColumn.PART2B])]
 
     @classmethod
     def from_part2t(cls, user_input: str, /) -> Language:
         """Return a ``Language`` instance from an ISO 639-2 (terminological) code."""
-        return _PART3_TO_LANGUAGES[_get_part3(user_input, [_CodesColumn.PART2T])]
+        return _PART3_TO_LANGUAGES[_get_part3_exact(user_input, [_CodesColumn.PART2T])]
 
     @classmethod
     def from_part1(cls, user_input: str, /) -> Language:
         """Return a ``Language`` instance from an ISO 639-1 code."""
-        return _PART3_TO_LANGUAGES[_get_part3(user_input, [_CodesColumn.PART1])]
+        return _PART3_TO_LANGUAGES[_get_part3_exact(user_input, [_CodesColumn.PART1])]
 
     @classmethod
     def from_name(cls, user_input: str, /) -> Language:
@@ -172,10 +182,57 @@ def from_name(cls, user_input: str, /) -> Language:
             _NameIndexColumn.PRINT_NAME,
             _NameIndexColumn.INVERTED_NAME,
         ]
-        return _PART3_TO_LANGUAGES[_get_part3(user_input, query_order)]
+        return _PART3_TO_LANGUAGES[_get_part3_exact(user_input, query_order)]
+
 
+def _raise_language_not_found_error(user_input: str) -> NoReturn:
+    raise LanguageNotFoundError(f"{user_input!r} isn't an ISO language code or name")
+
+
+def _get_part3(
+    user_input: str, query_order: List[_COLUMN_TYPE], exact: bool = True
+) -> str:
+    """Get the part 3 code of a language.
 
-def _get_part3(user_input: str, query_order: List[_COLUMN_TYPE]) -> str:
+    Parameters
+    ----------
+    user_input : str
+        The user-provided language code or name.
+    query_order : List[_COLUMN_TYPE]
+        A list of columns to specify query order.
+    exact : bool, optional
+        Whether to enforce exact matching against the user input. Defaults to `True`.
+        If `False`, basic string cleaning is applied to the user input.
+
+    Returns
+    -------
+    str
+
+    Raises
+    ------
+    LanguageNotFoundError
+        If `part3` isn't a language name or code
+    """
+    try:
+        return _get_part3_exact(user_input, query_order)
+    except LanguageNotFoundError as e:
+        if exact:
+            raise e
+        else:
+            for func in _STRING_CLEANING_FUNCS:
+                try:
+                    return _get_part3_exact(func(user_input), query_order, user_input)
+                except LanguageNotFoundError:
+                    continue
+            else:
+                _raise_language_not_found_error(user_input)
+
+
+def _get_part3_exact(
+    user_input: str,
+    query_order: List[_COLUMN_TYPE],
+    original_user_input: Optional[str] = None,
+) -> str:
     """Get the part 3 code of a language.
 
     Parameters
@@ -184,6 +241,9 @@ def _get_part3(user_input: str, query_order: List[_COLUMN_TYPE]) -> str:
         The user-provided language code or name.
     query_order : List[_COLUMN_TYPE]
         A list of columns to specify query order.
+    original_user_input : str, optional
+        The original user input. Default is `None`.
+        This argument is used when the user input has been cleaned.
 
     Returns
     -------
@@ -198,8 +258,7 @@ def _get_part3(user_input: str, query_order: List[_COLUMN_TYPE]) -> str:
     for column in query_order:
         if column == _CodesColumn.ID:
             if user_input in _PART3_TO_CODES:
-                part3 = user_input
-                break
+                return user_input
         elif column == _CodesColumn.PART2B:
             part3 = _PART2B_TO_PART3.get(user_input)
         elif column == _CodesColumn.PART2T:
@@ -208,8 +267,7 @@ def _get_part3(user_input: str, query_order: List[_COLUMN_TYPE]) -> str:
             part3 = _PART1_TO_PART3.get(user_input)
         elif column == _RetirementsColumn.ID:
             if user_input in _PART3_TO_RETIREMENTS:
-                part3 = user_input
-                break
+                return user_input
         elif column == _CodesColumn.REF_NAME:
             part3 = _REF_NAME_TO_PART3.get(user_input)
         elif column == _NameIndexColumn.PRINT_NAME:
@@ -222,9 +280,7 @@ def _get_part3(user_input: str, query_order: List[_COLUMN_TYPE]) -> str:
             break
 
     if part3 is None:
-        raise LanguageNotFoundError(
-            f"{user_input!r} isn't an ISO language code or name"
-        )
+        _raise_language_not_found_error(original_user_input or user_input)
 
     return part3
 

tests/test_language.py

@@ -7,18 +7,34 @@
 
 
 @pytest.mark.parametrize(
-    "user_input, expected_part3",
+    "user_input, exact, expected_part3",
     [
-        ("fra", "fra"),
-        ("fre", "fra"),
-        ("fr", "fra"),
-        ("French", "fra"),
-        ("Castilian", "spa"),
+        ("fra", True, "fra"),
+        ("fra", False, "fra"),
+        ("FRA", True, None),
+        ("FRA", False, "fra"),
+        (" FRA  ", False, "fra"),
+        ("Fra", True, None),
+        ("Fra", False, "fra"),
+        (" Fra  ", False, "fra"),
+        ("French", True, "fra"),
+        ("French", False, "fra"),
+        ("FRENCH", True, None),
+        ("FRENCH", False, "fra"),
+        (" FRENCH  ", False, "fra"),
+        ("french", True, None),
+        ("french", False, "fra"),
+        (" french  ", False, "fra"),
+        ("Castilian", True, "spa"),
     ],
 )
-def test_match(user_input, expected_part3):
-    actual_part3 = Language.match(user_input).part3
-    assert actual_part3 == expected_part3
+def test_match(user_input, exact, expected_part3):
+    if expected_part3 is None:
+        with pytest.raises(LanguageNotFoundError):
+            Language.match(user_input, exact=exact)
+    else:
+        actual_part3 = Language.match(user_input, exact=exact).part3
+        assert actual_part3 == expected_part3
 
 
 def test_name():