iso639

python-iso639 is a Python package for ISO 639 language codes, names, and other associated information, built directly on SIL’s ISO 639-3 data tables. It exposes a single Language dataclass with classmethod constructors for each ISO 639 code set (639-1, 639-2 bibliographic/terminological, and 639-3), plus a match() method that guesses which code set an unknown input belongs to, with optional case-insensitive matching.

Beyond simple code lookups, it resolves retired/deprecated ISO 639-3 codes to their replacements, links languages to their macrolanguages (e.g. Yue Chinese to Chinese), and surfaces alternative print and inverted names. The library has zero runtime dependencies, ships type hints via a py.typed marker, and precomputes all language records at import time for fast, allocation-free lookups afterward.

What You Get

• A single Language frozen dataclass unifying ISO 639-1, 639-2 (bibliographic & terminological), and 639-3 code sets plus reference/alternative names, macrolanguage links, and retirement metadata.
• Classmethod constructors (from_part1, from_part2b, from_part2t, from_part3, from_name) for exact lookups by a known code set, and Language.match() for guessing the code set of arbitrary input.
• The full ALL_LANGUAGES set and DATA_LAST_UPDATED constant for iterating or auditing the underlying SIL ISO 639-3 dataset.
• Type hints and a py.typed marker for static type-checker support, with zero runtime dependencies.

Common Use Cases

• Normalizing language codes across inconsistent data sources in NLP pipelines.
• Displaying human-readable language names in localization/i18n UIs.
• Migrating datasets tagged with retired ISO 639-3 codes to their current equivalents.
• Validating user- or API-submitted language codes before storage or processing.

Under The Hood

Architecture The library is a single flat-module architecture: _data/__init__.py loads TSV data files at import time into module-level dicts (_PART3_TO_CODES, _PART3_TO_NAME_INDEX, _PART3_TO_MACROLANGUAGES, _PART3_TO_RETIREMENTS, plus reverse-lookup dicts like _PART2B_TO_PART3) using csv.DictReader, keyed by Enum column identifiers for type safety. language.py builds on that data layer: a frozen, slots dataclass Language represents one language entry, and a module-level _get_all_languages() eagerly constructs every Language instance once at import time into _PART3_TO_LANGUAGES and the ALL_LANGUAGES set — this eager precomputation is what gives constant-time lookups afterward. The public API is entirely classmethods on Language (match, from_part3, from_part2b, from_part2t, from_part1, from_name), all delegating to private helpers _get_part3/_get_part3_exact, which walk an ordered list of column enums and short-circuit on the first successful dict lookup. There is no class hierarchy and no I/O beyond the one-time data load — a pure lookup-table design where every public method funnels through one dispatch function.

Tech Stack Pure Python (>=3.10) with zero runtime dependencies. The build system is setuptools (>=77) via pyproject.toml with a src/-layout package; data ships as packaged .tab (TSV) files declared in package-data, versioned separately by a DATA_LAST_UPDATED constant from the calendar-versioned __version__ (read via importlib.metadata). Dev tooling declared under [project.optional-dependencies].dev includes black, build, flake8, mypy, pytest, and twine. CI spans CircleCI (multi-Python-version matrix across Linux and Windows via a win orb, uv-managed virtual environments) and GitHub Actions (trusted-publishing release workflow to PyPI). No web framework, database, or external service integration — fully self-contained.

Code Quality The test suite (test_language.py, test_version_number.py) uses pytest with heavy @pytest.mark.parametrize coverage across the match/from_* classmethods, strict vs. case-insensitive matching, and edge cases like retired codes and macrolanguages. pytest config in pyproject.toml enforces strict markers. Error handling is explicit: a single custom LanguageNotFoundError is raised deliberately through a NoReturn-annotated helper rather than swallowed. Type hints are used throughout with from __future__ import annotations, a py.typed marker ships for downstream type-checkers, and mypy, flake8, and black all run in CI. Naming is consistent (leading-underscore for all private module state) — a small, disciplined, well-tested codebase.

API Design The API centers on one class with classmethod constructors named directly after the ISO 639 code sets they resolve (from_part3, from_part2b, etc.), plus a single fuzzy-matching entry point (Language.match) with an explicit strict_case keyword-only parameter for the common case of not knowing which code set an input is. Positional-only parameters prevent accidental keyword misuse. The dataclass is frozen and slotted for both immutability and memory efficiency, with custom __eq__/__hash__ based solely on the ISO 639-3 code so instances compare and hash predictably. Minimal boilerplate — import iso639; iso639.Language.from_part3('fra') is the entire integration surface — with thorough NumPy-style docstrings and runnable examples embedded directly in the README.