python-iso639 2025.1.28__tar.gz → 2025.2.18__tar.gz

{python_iso639-2025.1.28 → python_iso639-2025.2.18}/CHANGELOG.md

@@ -17,6 +17,17 @@ 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
+* Explicitly indicated that the library is type-annotated.
+
 ## [2025.1.28]
 
 ### Changed

{python_iso639-2025.1.28/src/python_iso639.egg-info → python_iso639-2025.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: python-iso639
-Version: 2025.1.28
+Version: 2025.2.18
 Summary: ISO 639 language codes, names, and other associated information
 Author-email: "Jackson L. Lee" <jacksonlunlee@gmail.com>
 License: Apache 2.0
@@ -28,10 +28,10 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Provides-Extra: dev
-Requires-Dist: black==24.10.0; extra == "dev"
+Requires-Dist: black==25.1.0; extra == "dev"
 Requires-Dist: build==1.2.2; extra == "dev"
 Requires-Dist: flake8==7.1.1; extra == "dev"
-Requires-Dist: mypy==1.14.1; extra == "dev"
+Requires-Dist: mypy==1.15.0; extra == "dev"
 Requires-Dist: pytest==8.3.4; extra == "dev"
 Requires-Dist: requests==2.32.3; extra == "dev"
 Requires-Dist: twine==6.1.0; extra == "dev"
@@ -48,9 +48,10 @@ other associated information.
 
 Current features:
 
-* A representation of languages mapped across ISO 639-1, 639-2, and 639-3.
-* Functionality to "guess" what a language is for a given
+* 🌐 A representation of languages mapped across ISO 639-1, 639-2, and 639-3.
+* 🔎 Functionality to "guess" what a language is for a given
   unknown language code or name.
+* 🚀 Optimized for speed in retrieving language information.
 
 ## Installation
 
@@ -82,6 +83,15 @@ 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.3.1, Apple M1 Pro)
+
+```python
+In [1]: import iso639
+
+In [2]: %timeit iso639.Language.from_part3("fra")
+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
 
 ```python
@@ -144,11 +154,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
 ```
 
@@ -251,7 +277,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.
 

{python_iso639-2025.1.28 → python_iso639-2025.2.18}/README.md

@@ -10,9 +10,10 @@ other associated information.
 
 Current features:
 
-* A representation of languages mapped across ISO 639-1, 639-2, and 639-3.
-* Functionality to "guess" what a language is for a given
+* 🌐 A representation of languages mapped across ISO 639-1, 639-2, and 639-3.
+* 🔎 Functionality to "guess" what a language is for a given
   unknown language code or name.
+* 🚀 Optimized for speed in retrieving language information.
 
 ## Installation
 
@@ -44,6 +45,15 @@ 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.3.1, Apple M1 Pro)
+
+```python
+In [1]: import iso639
+
+In [2]: %timeit iso639.Language.from_part3("fra")
+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
 
 ```python
@@ -106,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
 ```
 
@@ -213,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.
 

{python_iso639-2025.1.28 → python_iso639-2025.2.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-iso639"
-version = "2025.1.28"
+version = "2025.2.18"
 description = "ISO 639 language codes, names, and other associated information"
 readme = "README.md"
 requires-python = ">= 3.9"
@@ -34,10 +34,10 @@ classifiers = [
 
 [project.optional-dependencies]
 dev = [
-    "black == 24.10.0",
+    "black == 25.1.0",
     "build == 1.2.2",
     "flake8 == 7.1.1",
-    "mypy == 1.14.1",
+    "mypy == 1.15.0",
     "pytest == 8.3.4",
     "requests == 2.32.3",
     "twine == 6.1.0",
@@ -52,7 +52,7 @@ where = [ "src" ]
 [tool.setuptools]
 zip-safe = false
 package-dir = { "" = "src" }
-package-data = { "iso639" = ["_data/*.tab"] }
+package-data = { "iso639" = ["_data/*.tab", "py.typed"] }
 
 [tool.pytest.ini_options]
 addopts = "-vv --durations=0 --strict-markers"

{python_iso639-2025.1.28 → python_iso639-2025.2.18}/src/iso639/language.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 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 @@ from ._data import (
 )
 
 
+_STRING_CLEANING_FUNCS = [
+    lambda x: x.strip().lower(),
+    lambda x: x.strip().title(),
+]
+
+
 class LanguageNotFoundError(Exception):
     pass
 
@@ -100,13 +106,17 @@ class Language:
         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 @@ class 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 @@ class 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
 

{python_iso639-2025.1.28 → python_iso639-2025.2.18/src/python_iso639.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: python-iso639
-Version: 2025.1.28
+Version: 2025.2.18
 Summary: ISO 639 language codes, names, and other associated information
 Author-email: "Jackson L. Lee" <jacksonlunlee@gmail.com>
 License: Apache 2.0
@@ -28,10 +28,10 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Provides-Extra: dev
-Requires-Dist: black==24.10.0; extra == "dev"
+Requires-Dist: black==25.1.0; extra == "dev"
 Requires-Dist: build==1.2.2; extra == "dev"
 Requires-Dist: flake8==7.1.1; extra == "dev"
-Requires-Dist: mypy==1.14.1; extra == "dev"
+Requires-Dist: mypy==1.15.0; extra == "dev"
 Requires-Dist: pytest==8.3.4; extra == "dev"
 Requires-Dist: requests==2.32.3; extra == "dev"
 Requires-Dist: twine==6.1.0; extra == "dev"
@@ -48,9 +48,10 @@ other associated information.
 
 Current features:
 
-* A representation of languages mapped across ISO 639-1, 639-2, and 639-3.
-* Functionality to "guess" what a language is for a given
+* 🌐 A representation of languages mapped across ISO 639-1, 639-2, and 639-3.
+* 🔎 Functionality to "guess" what a language is for a given
   unknown language code or name.
+* 🚀 Optimized for speed in retrieving language information.
 
 ## Installation
 
@@ -82,6 +83,15 @@ 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.3.1, Apple M1 Pro)
+
+```python
+In [1]: import iso639
+
+In [2]: %timeit iso639.Language.from_part3("fra")
+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
 
 ```python
@@ -144,11 +154,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
 ```
 
@@ -251,7 +277,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.
 

{python_iso639-2025.1.28 → python_iso639-2025.2.18}/src/python_iso639.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ README.md
 pyproject.toml
 src/iso639/__init__.py
 src/iso639/language.py
+src/iso639/py.typed
 src/iso639/_data/__init__.py
 src/iso639/_data/iso-639-3-macrolanguages.tab
 src/iso639/_data/iso-639-3.tab

{python_iso639-2025.1.28 → python_iso639-2025.2.18}/src/python_iso639.egg-info/requires.txt

@@ -1,9 +1,9 @@
 
 [dev]
-black==24.10.0
+black==25.1.0
 build==1.2.2
 flake8==7.1.1
-mypy==1.14.1
+mypy==1.15.0
 pytest==8.3.4
 requests==2.32.3
 twine==6.1.0

{python_iso639-2025.1.28 → python_iso639-2025.2.18}/tests/test_language.py

@@ -7,18 +7,34 @@ import pytest
 
 
 @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():