### Install python-iso639

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/README.md

Install the library using pip.

```bash
pip install python-iso639
```

--------------------------------

### Install python-iso639 using uv

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Install the package using uv, a fast Python package installer and resolver.

```bash
uv add python-iso639
```

--------------------------------

### Verify python-iso639 Installation

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

Check the installed version, data update timestamp, and the number of languages available.

```python
import iso639
print(f"Version: {iso639.__version__}")
print(f"Data: {iso639.DATA_LAST_UPDATED}")
print(f"Languages: {len(iso639.ALL_LANGUAGES)}")
```

--------------------------------

### Install Package in Editable Mode

Source: https://github.com/jacksonllee/iso639/blob/main/CONTRIBUTING.md

Installs the package in editable mode for development after cloning the repository.

```bash
git clone https://github.com/<your-github-username>/iso639.git
cd iso639
pip install -e ".[dev]"
```

--------------------------------

### Install python-iso639 using conda

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Install the package using conda, a package and environment management system, from the conda-forge channel.

```bash
conda install -c conda-forge python-iso639
```

--------------------------------

### Quick Language Lookup

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

Provides examples of how to quickly look up language information using various codes.

```APIDOC
## Quick Language Lookup

### Description
Provides examples of how to quickly look up language information using various codes.

### Example
```python
import iso639

# Get language by any code
lang = iso639.Language.match('fra')
print(lang.name)  # 'French'

# Get specific attributes
print(lang.part1)   # 'fr'
print(lang.part3)   # 'fra'

# Check if language is active or retired
if lang.status == 'A':
    print("Active language")
else:
    print("Retired language")
```
```

--------------------------------

### Add Upstream Remote

Source: https://github.com/jacksonllee/iso639/blob/main/CONTRIBUTING.md

Adds the official repository as an 'upstream' remote to your local clone. This is a one-time setup step.

```bash
git remote add upstream https://github.com/jacksonllee/iso639.git
```

--------------------------------

### Get Package Version

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

Prints the current version of the python-iso639 package. The version follows the CalVer format YYYY.M.D.

```python
import iso639
print(iso639.__version__)  # '2026.4.20'
```

--------------------------------

### Web Application Language Lookup

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/README.md

Example of a Flask web application endpoint that looks up language information using the iso639 library. Handles language not found errors.

```python
from flask import Flask, request, jsonify
import iso639

@app.route('/language/<code>')
def get_language(code):
    try:
        lang = iso639.Language.match(code, strict_case=False)
        return jsonify({
            'code': lang.part3,
            'name': lang.name,
            'iso639_1': lang.part1,
        })
    except iso639.LanguageNotFoundError:
        return {'error': 'Language not found'}, 404
```

--------------------------------

### Example Usage of Name in Language

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/types.md

Demonstrates how to access and print alternative names associated with a language. The `other_names` attribute is a list of `Name` objects.

```python
import iso639

lang = iso639.Language.match('yue')
if lang.other_names:
    for name in lang.other_names:
        print(f"{name.print} ({name.inverted})")
        # Output: Yue Chinese (Chinese, Yue)
```

--------------------------------

### Filter Languages by Alternative Names

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/data-reference.md

Identify and display languages that have alternative names, printing the first 5 examples.

```python
import iso639

# Languages with alternative names
with_alt_names = [l for l in iso639.ALL_LANGUAGES if l.other_names]

print(f"Languages with alternative names: {len(with_alt_names)}")

# Print examples
for lang in list(with_alt_names)[:5]:
    print(f"\n{lang.name}:")
    for name in lang.other_names:
        print(f"  - {name.print} ({name.inverted})")
```

--------------------------------

### Create Language from ISO 639-1 Code

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Use `from_part1` to get a Language instance from an ISO 639-1 code. Input is case-sensitive and stripped of whitespace. This code covers only major languages.

```python
import iso639

lang = iso639.Language.from_part1('fr')
print(lang.part3)  # 'fra'
print(lang.name)  # 'French'
```

--------------------------------

### Robust Code Lookup with Error Handling

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Provides an example of performing lookups for multiple language codes, including valid and potentially invalid ones, and handling 'LanguageNotFoundError' gracefully for each lookup.

```Python
import iso639

codes = ['fra', 'fre', 'fr', 'French', 'Castilian', 'spa']

for code in codes:
    try:
        lang = iso639.Language.match(code)
        print(f"{code:15} -> {lang.name}")
    except iso639.LanguageNotFoundError:
        print(f"{code:15} -> Not found")
```

--------------------------------

### Name Class Definition and Attributes

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Name.md

This snippet details the structure of the Name class, including its attributes 'print' and 'inverted', and provides an example of its instantiation and usage.

```APIDOC
## Name Class

### Description
The `Name` class represents an alternative print name and inverted name for an ISO 639-3 language. It is a frozen dataclass used to store alternative language name representations from the ISO 639-3 name index.

### Class Definition
```python
@dataclass(frozen=True, slots=True)
class Name:
    print: str
    inverted: str
```

### Attributes
| Attribute | Type | Nullable | Description |
|-----------|------|----------|-------------|
| print | str | No | The print form of an alternative language name |
| inverted | str | No | The inverted form of an alternative language name (typically inverted for alphabetical ordering) |

### Example Usage
```python
from iso639.language import Name

# Create an alternative name
alt_name = Name(print="Yue Chinese", inverted="Chinese, Yue")
print(alt_name.print)      # 'Yue Chinese'
print(alt_name.inverted)   # 'Chinese, Yue'

# Usage in Language context
import iso639
yue = iso639.Language.match('yue')
if yue.other_names:
    for name in yue.other_names:
        assert isinstance(name, Name)
        print(f"{name.print} / {name.inverted}")
```
```

--------------------------------

### Creating and Using Name Instances

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Name.md

Shows how to manually create a Name instance and then demonstrates its usage within the context of a Language object's 'other_names' attribute.

```python
from iso639.language import Name

# Create an alternative name
alt_name = Name(print="Yue Chinese", inverted="Chinese, Yue")
print(alt_name.print)      # 'Yue Chinese'
print(alt_name.inverted)   # 'Chinese, Yue'

# Usage in Language context
import iso639
yue = iso639.Language.match('yue')
if yue.other_names:
    for name in yue.other_names:
        assert isinstance(name, Name)
        print(f"{name.print} / {name.inverted}")
```

--------------------------------

### Importing Specific Items

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

Demonstrates how to import specific classes and constants from the iso639 module.

```APIDOC
## Importing Specific Items

### Description
Demonstrates how to import specific classes and constants from the iso639 module.

### Example
```python
# Import the main class and exception
from iso639 import Language, LanguageNotFoundError

# Or import everything
from iso639 import Language, LanguageNotFoundError, ALL_LANGUAGES, DATA_LAST_UPDATED

# Or use the module namespace
import iso639
lang = iso639.Language.from_part3('fra')
```
```

--------------------------------

### Create Language instance from other ISO 639 codes or name

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Shows how to create Language instances using different ISO 639 code sets (part2b, part2t, part1) or the language reference name.

```python
lang2 = iso639.Language.from_part2b('fre')  # ISO 639-2 (bibliographic)
lang3 = iso639.Language.from_part2t('fra')  # ISO 639-2 (terminological)
lang4 = iso639.Language.from_part1('fr')  # ISO 639-1
lang5 = iso639.Language.from_name('French')  # ISO 639-3 reference language name
```

--------------------------------

### Create Language instance from ISO 639-3 code

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Demonstrates creating a Language instance using the `from_part3` class method with an ISO 639-3 code. Note that the input is case-sensitive.

```python
import iso639
lang1 = iso639.Language.from_part3('fra')
print(type(lang1))
print(lang1)
```

--------------------------------

### Graceful Fallback

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/LanguageNotFoundError.md

Provides an example of a function that gracefully handles LanguageNotFoundError by returning a default value when a language cannot be found.

```APIDOC
## Graceful Fallback

```python
import iso639

def get_language_name(code, default='Unknown'):
    try:
        return iso639.Language.match(code).name
    except iso639.LanguageNotFoundError:
        return default

print(get_language_name('fra'))           # 'French'
print(get_language_name('invalid'))       # 'Unknown'
print(get_language_name('xyz', 'N/A'))    # 'N/A'
```
```

--------------------------------

### Creating Language Instances

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Demonstrates how to create Language instances using various class methods, including from_part3, from_part2b, from_part2t, from_part1, and from_name. It also shows the expected LanguageNotFoundError for invalid inputs.

```APIDOC
## Creating Language Instances

### `from_part3`, with an ISO 639-3 code

```python
>>> import iso639
>>> lang1 = iso639.Language.from_part3('fra')
>>> type(lang1)
<class 'iso639.language.Language'>
>>> lang1
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)
```

### From Another ISO 639 Code Set or a Reference Name

```python
>>> lang2 = iso639.Language.from_part2b('fre')  # ISO 639-2 (bibliographic)
>>> lang3 = iso639.Language.from_part2t('fra')  # ISO 639-2 (terminological)
>>> lang4 = iso639.Language.from_part1('fr')  # ISO 639-1
>>> lang5 = iso639.Language.from_name('French')  # ISO 639-3 reference language name
```

### A `LanguageNotFoundError` is Raised for Invalid Inputs

```python
>>> iso639.Language.from_part3('Fra')  # The user input is case-sensitive!
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
LanguageNotFoundError: 'Fra' isn't an ISO language code or name
>>> 
>>> iso639.Language.from_name("unknown language")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
LanguageNotFoundError: 'unknown language' isn't an ISO language code or name
```
```

--------------------------------

### Case Sensitivity Handling

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/LanguageNotFoundError.md

Illustrates how to manage case sensitivity for language codes, showing both the default behavior and how to enable case-insensitive matching.

```APIDOC
## Case Sensitivity

Remember that language codes and reference names are **case-sensitive** by default:

```python
import iso639

# This raises LanguageNotFoundError
try:
    iso639.Language.from_part3('Fra')  # Should be lowercase 'fra'
except iso639.LanguageNotFoundError:
    print("Code must be lowercase")

# Use strict_case=False for case-insensitive matching
lang = iso639.Language.match('FRA', strict_case=False)
print(lang.name)  # 'French'
```
```

--------------------------------

### Import Specific Items from iso639

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

Shows different ways to import items from the `iso639` module, including specific classes and constants, or importing everything.

```python
# Import the main class and exception
from iso639 import Language, LanguageNotFoundError

# Or import everything
from iso639 import Language, LanguageNotFoundError, ALL_LANGUAGES, DATA_LAST_UPDATED

# Or use the module namespace
import iso639
lang = iso639.Language.from_part3('fra')
```

--------------------------------

### Filtering Languages by Type and Status

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/index.md

Provides examples of filtering the list of all languages based on their type (e.g., living) and status (e.g., active or retired).

```python
import iso639

# Living languages
living = [l for l in iso639.ALL_LANGUAGES if l.type == 'L']
print(f"Living languages: {len(living)}")

# Active vs retired
active = [l for l in iso639.ALL_LANGUAGES if l.status == 'A']
retired = [l for l in iso639.ALL_LANGUAGES if l.status == 'R']
print(f"Active: {len(active)}, Retired: {len(retired)}")

# Has ISO 639-1 code
major_langs = [l for l in iso639.ALL_LANGUAGES if l.part1]
print(f"Major languages: {len(major_langs)}")
```

--------------------------------

### Working with Macrolanguages

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Illustrates how to identify and access information related to macrolanguages, such as retrieving the macrolanguage code for 'Yue Chinese' and iterating through alternative names.

```Python
import iso639

yue = iso639.Language.match('yue')
print(yue.name)  # 'Yue Chinese'
print(yue.macrolanguage)  # 'zho' (Chinese)

if yue.other_names:
    for alt_name in yue.other_names:
        print(f"Print: {alt_name.print}, Inverted: {alt_name.inverted}")
```

--------------------------------

### Get Data Update Date

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Retrieves the last updated date of the language code data included in the library. This constant indicates the freshness of the dataset.

```python
import iso639
iso639.DATA_LAST_UPDATED
```

--------------------------------

### Access All Languages

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

Demonstrates how to access and use the `ALL_LANGUAGES` set, which contains all `Language` objects from the ISO 639-3 database. It shows how to check the type and size of the set, iterate over languages, check for language membership, and find languages by criteria like 'living' or 'retired'.

```python
import iso639

print(type(iso639.ALL_LANGUAGES))  # <class 'set'>
print(len(iso639.ALL_LANGUAGES))   # 8315

# Iterate over all languages
for lang in list(iso639.ALL_LANGUAGES)[:5]:
    print(f"{lang.part3}: {lang.name}")

# Check if a language is in the set
french = iso639.Language.from_part3('fra')
assert french in iso639.ALL_LANGUAGES

# Find languages by criteria
living_languages = [l for l in iso639.ALL_LANGUAGES if l.type == 'L']
print(f"Living languages: {len(living_languages)}")

# Find retired languages
retired_languages = [l for l in iso639.ALL_LANGUAGES if l.status == 'R']
print(f"Retired languages: {len(retired_languages)}")
```

--------------------------------

### Migrate from iso-639 (unmaintained)

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

The migration is straightforward; replace imports and use `iso639.Language.match` for language lookup.

```python
# Migration: both packages similar, but this one maintains current data
import iso639

# Simply replace imports and update code to use Language class
lang = iso639.Language.match('fra')
```

--------------------------------

### Basic Language Lookup

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/README.md

Get language details by providing any valid ISO 639 code or name. Includes a safe lookup method that handles not found errors.

```python
import iso639

# Get language by any code or name
lang = iso639.Language.match('fra')
print(lang.name)    # 'French'
print(lang.part1)   # 'fr'
print(lang.part3)   # 'fra'

# Safe lookup
try:
    lang = iso639.Language.from_part3('spa')
except iso639.LanguageNotFoundError:
    print("Language not found")
```

--------------------------------

### Fast object instantiation for language information

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Measures the performance of creating a Language instance using `from_part3`. This snippet is intended for performance benchmarking.

```python
import iso639

iso639.Language.from_part3("fra")
```

--------------------------------

### Integrate with Python Dataclasses

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/index.md

Demonstrates how to use iso639 Language objects with Python's dataclasses module for conversion to dictionaries and accessing field information.

```python
import dataclasses
import iso639

lang = iso639.Language.from_part3('fra')

# Convert to dict
data = dataclasses.asdict(lang)

# Access field information
fields = dataclasses.fields(lang)
for field in fields:
    print(f"{field.name}: {field.type}")
```

--------------------------------

### Access Data Last Updated Date

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/data-reference.md

Get the release date of the ISO 639-3 language code data. This is useful for version checking and ensuring compatibility with specific data versions.

```python
import iso639
import datetime

print(iso639.DATA_LAST_UPDATED)
assert isinstance(iso639.DATA_LAST_UPDATED, datetime.date)

# Use for version checking
if iso639.DATA_LAST_UPDATED >= datetime.date(2026, 1, 1):
    print("Using 2026 data")
```

--------------------------------

### Access Language instance attributes

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Demonstrates how to access various attributes of a Language instance, such as `part3` and `name`, after it has been created.

```python
lang1 = iso639.Language.from_part3('fra')
print(lang1.part3)
print(lang1.name)
```

--------------------------------

### Import Statements for ISO 639 Library

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/QUICK-REFERENCE.md

Demonstrates how to import specific items or the entire module namespace for the iso639 library. Useful for accessing Language, errors, and language data.

```python
# Import specific items
from iso639 import Language, LanguageNotFoundError, ALL_LANGUAGES, DATA_LAST_UPDATED

# Or use module namespace
import iso639
lang = iso639.Language.from_part3('fra')
```

--------------------------------

### Query Documents by Language Code

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

Filter database records using the stored language code. This example shows filtering by a single ISO 639-3 code or a list of codes using Django ORM.

```python
# Django ORM example
documents = Document.objects.filter(language_code='fra')

# Or filter by multiple codes
french_spanish = Document.objects.filter(
    language_code__in=['fra', 'spa']
)
```

--------------------------------

### Working with Macrolanguages

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/index.md

Demonstrates how to identify if a language belongs to a macrolanguage and how to access alternative names for languages.

```python
import iso639

# Get a language that's part of a macrolanguage
yue = iso639.Language.match('yue')  # Yue Chinese (Cantonese)
print(yue.name)            # 'Yue Chinese'
print(yue.macrolanguage)   # 'zho' (Chinese)

# View alternative names
if yue.other_names:
    for name in yue.other_names:
        print(f"{name.print} / {name.inverted}")
        # Output: Yue Chinese / Chinese, Yue
```

--------------------------------

### Create Language from ISO 639-2 Terminological Code

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Use `from_part2t` to get a Language instance from an ISO 639-2 terminological code. Input is case-sensitive and stripped of whitespace. Not all languages have a 639-2 terminological code.

```python
import iso639

lang = iso639.Language.from_part2t('fra')
print(lang.part3)  # 'fra'
print(lang.name)  # 'French'
```

--------------------------------

### Language Equality Comparison

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Demonstrates how Language instances are considered equal if their ISO 639-3 codes match, regardless of how they were initialized (e.g., from part3, part1, or name).

```python
import iso639

lang1 = iso639.Language.from_part3('fra')
lang2 = iso639.Language.from_part1('fr')
lang3 = iso639.Language.from_name('French')

assert lang1 == lang2 == lang3  # All represent French
```

--------------------------------

### Convert Between ISO 639 Standards

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

Use `iso639.Language.match()` with any known code (ISO 639-1, 639-2, 639-3, or name) to get a Language object. Access specific code parts like `part3` from the returned object.

```python
import iso639

# Input might be from different sources
codes = {
    'iso639_1': 'fr',
    'iso639_2': 'fre',
    'iso639_3': 'fra',
    'name': 'French',
}

lang = iso639.Language.match(codes['iso639_1'])  # Works for any code
print(f"Normalized to 639-3: {lang.part3}")
```

--------------------------------

### Serialize Language Objects for Databases/JSON

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/index.md

Shows how to serialize iso639 Language instances into a JSON string using dataclasses.asdict and json.dumps, including handling date serialization.

```python
import dataclasses
import json
import iso639

lang = iso639.Language.from_part3('fra')
data = dataclasses.asdict(lang)

# Handle datetime.date serialization
json_str = json.dumps(
    data,
    default=str,  # Converts date to string
    indent=2
)
```

--------------------------------

### Get Data Last Updated Date

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

Prints the last updated date of the ISO 639-3 language code data. This date indicates when the underlying language database was last refreshed and can be used for version compatibility checks.

```python
import iso639
import datetime

print(iso639.DATA_LAST_UPDATED)  # datetime.date(2026, 4, 15)
assert isinstance(iso639.DATA_LAST_UPDATED, datetime.date)

# Use for version compatibility checks
if iso639.DATA_LAST_UPDATED >= datetime.date(2026, 1, 1):
    print("Using recent data")
```

--------------------------------

### Migrate from iso639 (unmaintained)

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

Replace imports and update calls to use `iso639.Language.from_part2b` for Part 2B codes.

```python
# Old package (different API)
# import iso639
# lang = iso639.languages.get(part2='fre')

# New package
import iso639
lang = iso639.Language.from_part2b('fre')
```

--------------------------------

### Unit Tests for Language Lookup

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

Demonstrates how to test valid and invalid language codes, and flexible matching using unittest.

```python
import iso639
import unittest

class TestLanguageLookup(unittest.TestCase):
    def test_valid_code(self):
        lang = iso639.Language.from_part3('fra')
        self.assertEqual(lang.name, 'French')
    
    def test_invalid_code(self):
        with self.assertRaises(iso639.LanguageNotFoundError):
            iso639.Language.from_part3('invalid')
    
    def test_match_flexibility(self):
        lang1 = iso639.Language.match('fra')
        lang2 = iso639.Language.match('French')
        lang3 = iso639.Language.match('fre')
        self.assertEqual(lang1, lang2)  # Both French
```

--------------------------------

### Create Language from Language Name

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Use `from_name` to get a Language instance from an ISO 639-3 language name or alternative name. Input is case-sensitive and stripped of whitespace. The lookup order prioritizes reference names, then alternative print names, and finally alternative inverted names.

```python
import iso639

lang = iso639.Language.from_name('French')
print(lang.part3)  # 'fra'
print(lang.part1)  # 'fr'

# Alternative names also work
lang2 = iso639.Language.from_name('Castilian')
print(lang2.part3)  # 'spa'
```

--------------------------------

### Basic Language Matching and Information Retrieval

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/index.md

Demonstrates how to find a language using various codes or names and print its details. Includes safe lookup with error handling and iterating through a subset of all languages.

```python
import iso639

# Get a language by any code or name
lang = iso639.Language.match('fra')
print(lang.name)    # 'French'
print(lang.part1)   # 'fr'
print(lang.part3)   # 'fra'

# Safe lookup with error handling
try:
    lang = iso639.Language.from_part3('spa')
except iso639.LanguageNotFoundError:
    print("Language not found")

# Browse all languages
for lang in list(iso639.ALL_LANGUAGES)[:5]:
    print(f"{lang.part3}: {lang.name}")
```

--------------------------------

### `__eq__` Method

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Compares two `Language` instances for equality based on their ISO 639-3 codes.

```APIDOC
## `__eq__`

Two `Language` instances are equal if their ISO 639-3 codes are equal.

```python
def __eq__(self, other) -> bool
```

#### Example

```python
import iso639

lang1 = iso639.Language.from_part3('fra')
lang2 = iso639.Language.from_part1('fr')
lang3 = iso639.Language.from_name('French')

assert lang1 == lang2 == lang3  # All represent French
```
```

--------------------------------

### Handling Retired Languages

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Demonstrates how to safely retrieve information about retired languages, including their status, retirement reason, and suggested remedy, using a try-except block to handle potential 'LanguageNotFoundError'.

```Python
import iso639

try:
    lang = iso639.Language.match('bvs')
    print(lang.name)  # 'Belgian Sign Language'
    print(lang.status)  # 'R' (Retired)
    if lang.retire_reason:
        print(f"Reason: {lang.retire_reason}")
        print(f"Remedy: {lang.retire_remedy}")
except iso639.LanguageNotFoundError:
    print("Language not found")
```

--------------------------------

### from_part1

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Creates a Language instance from an ISO 639-1 code. The input code is case-sensitive and whitespace is stripped before lookup. Only major languages are covered by ISO 639-1 codes.

```APIDOC
## `from_part1` (classmethod)

### Description
Returns a `Language` instance from an ISO 639-1 code.

### Method Signature
```python
@classmethod
def from_part1(cls, user_input: str, /) -> Language
```

### Parameters
#### Path Parameters
- **user_input** (str) - Required - An ISO 639-1 code (case-sensitive)

### Returns
`Language` — The language instance

### Raises
- **LanguageNotFoundError**: If the code is not a valid ISO 639-1 code

### Notes
- Input is stripped of whitespace before lookup
- Not all languages have an ISO 639-1 code (639-1 covers only major languages)

### Example
```python
import iso639

lang = iso639.Language.from_part1('fr')
print(lang.part3)  # 'fra'
print(lang.name)  # 'French'
```
```

--------------------------------

### Dataclass Functionality for Language Objects

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Demonstrates how to use standard Python dataclass features with the iso639.Language object, including converting to a dictionary and accessing fields.

```Python
import dataclasses
import iso639

lang = iso639.Language.from_part3('fra')

# Convert to dictionary
data = dataclasses.asdict(lang)
print(data['part3'])  # 'fra'
print(data['name'])   # 'French'

# Access via standard dataclass features
print(dataclasses.fields(lang))  # Tuple of Field objects
```

--------------------------------

### Language Comparison

Source: https://github.com/jacksonllee/iso639/blob/main/README.md

Illustrates how Language objects can be compared for equality, both with themselves and with other Language objects representing different languages.

```APIDOC
## Comparison

```python
>>> lang1 == lang2 == lang3 == lang4 == lang5  # All are French
True
>>> lang6 = iso639.Language.from_part3('spa')  # Spanish
>>> lang1 == lang6  # French vs. Spanish
False
>>> 'French' == lang1.name == lang2.name == lang3.name == lang4.name == lang5.name
True
>>> lang6.name
'Spanish'
```
```

--------------------------------

### Access Package Version

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/data-reference.md

Retrieve the current version of the python-iso639 package. This version follows Calendar Versioning (CalVer) format.

```python
import iso639
print(iso639.__version__)
```

--------------------------------

### Language.from_part3()

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Class method to create a Language instance directly from an ISO 639-3 code. This method is case-sensitive.

```APIDOC
## Language.from_part3 (classmethod)

Returns a `Language` instance from an ISO 639-3 code.

### Method Signature
```python
@classmethod
def from_part3(cls, user_input: str, /) -> Language
```

### Parameters
#### Path Parameters
- **user_input** (str) - Required - An ISO 639-3 code (case-sensitive)

### Returns
`Language` — The language instance

### Raises
- `LanguageNotFoundError` - If the code is not a valid ISO 639-3 code.

### Notes
- Matches both active and retired codes.
- Case-sensitive; 'fra' matches but 'Fra' and 'FRA' do not.
- Input is stripped of whitespace before lookup.

### Example
```python
import iso639

lang = iso639.Language.from_part3('fra')
print(lang.name)  # 'French'
print(lang.part1)  # 'fr'

# Retired codes also work
retired = iso639.Language.from_part3('bvs')
print(retired.status)  # 'R'
```
```

--------------------------------

### Language Hashing for Collections

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Illustrates how Language instances can be used in hash-based collections like dictionaries and sets, as their hash is derived from their ISO 639-3 code. This ensures that different representations of the same language are treated as identical in these collections.

```python
import iso639

lang1 = iso639.Language.from_part3('fra')
lang2 = iso639.Language.from_part1('fr')

# Can be used as dict key
codes_dict = {lang1: 'French is the reference name'}
print(codes_dict[lang2])  # 'French is the reference name'

# Can be added to a set
lang_set = {lang1, lang2}
print(len(lang_set))  # 1 (duplicates removed by hash)
```

--------------------------------

### Optimizing Bulk Language Lookups

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

Compares a slow method of repeated lookups in a loop with a faster method using a list comprehension for batch operations.

```python
import iso639

# Don't repeat lookups in loops
def slow(codes):
    results = []
    for code in codes:
        lang = iso639.Language.match(code)  # Repeated lookup
        results.append(lang.name)
    return results

# Better: batch lookup
def fast(codes):
    return [iso639.Language.match(code).name for code in codes]
```

--------------------------------

### Detect Support for New Language Codes

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

Use a try-except block with `iso639.Language.from_part3` to check if a specific language code is supported, indicating whether a package upgrade might be needed.

```python
import iso639

# Check if specific language exists
try:
    new_lang = iso639.Language.from_part3('new_code')
    print("New language is supported")
except iso639.LanguageNotFoundError:
    print("Upgrade package for newer languages")
```

--------------------------------

### Language.from_part2b()

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Class method to create a Language instance from an ISO 639-2 bibliographic code. This method is case-sensitive.

```APIDOC
## Language.from_part2b (classmethod)

Returns a `Language` instance from an ISO 639-2 bibliographic code.

### Method Signature
```python
@classmethod
def from_part2b(cls, user_input: str, /) -> Language
```

### Parameters
#### Path Parameters
- **user_input** (str) - Required - An ISO 639-2 bibliographic code (case-sensitive)

### Returns
`Language` — The language instance

### Raises
- `LanguageNotFoundError` - If the code is not a valid ISO 639-2 bibliographic code.

### Notes
- Input is stripped of whitespace before lookup.
- Not all languages have a 639-2 bibliographic code.

### Example
```python
import iso639

lang = iso639.Language.from_part2b('fre')
print(lang.part3)  # 'fra'
print(lang.name)  # 'French'
```
```

--------------------------------

### from_name

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Creates a Language instance from an ISO 639-3 language name or alternative name. The lookup is case-sensitive and prioritizes reference names, then alternative print names, and finally alternative inverted names. Whitespace is stripped before lookup.

```APIDOC
## `from_name` (classmethod)

### Description
Returns a `Language` instance from an ISO 639-3 language name.

### Method Signature
```python
@classmethod
def from_name(cls, user_input: str, /) -> Language
```

### Parameters
#### Path Parameters
- **user_input** (str) - Required - An ISO 639-3 reference language name or alternative name (case-sensitive)

### Returns
`Language` — The language instance

### Raises
- **LanguageNotFoundError**: If the name is not found in the reference names or alternative names

### Lookup Order
1. ISO 639-3 reference language names
2. ISO 639-3 alternative print names
3. ISO 639-3 alternative inverted names

### Notes
- Input is stripped of whitespace before lookup
- Case-sensitive; 'French' matches but 'french' and 'FRENCH' do not
- Some languages have multiple alternative names

### Example
```python
import iso639

lang = iso639.Language.from_name('French')
print(lang.part3)  # 'fra'
print(lang.part1)  # 'fr'

# Alternative names also work
lang2 = iso639.Language.from_name('Castilian')
print(lang2.part3)  # 'spa'
```
```

--------------------------------

### Store ISO 639-3 Code in Database

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

For database storage, using only the ISO 639-3 code is efficient. A helper method can reconstruct the `Language` object from the stored code when needed.

```python
# Database schema
class Document:
    language_code = CharField(max_length=3)  # ISO 639-3
    
    def get_language(self):
        return iso639.Language.from_part3(self.language_code)

# Usage
doc.language_code = 'fra'
lang = doc.get_language()
print(lang.name)  # 'French'
```

--------------------------------

### from_part2t

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Creates a Language instance from an ISO 639-2 terminological code. The input code is case-sensitive and whitespace is stripped before lookup. Not all languages have a 639-2 terminological code.

```APIDOC
## `from_part2t` (classmethod)

### Description
Returns a `Language` instance from an ISO 639-2 terminological code.

### Method Signature
```python
@classmethod
def from_part2t(cls, user_input: str, /) -> Language
```

### Parameters
#### Path Parameters
- **user_input** (str) - Required - An ISO 639-2 terminological code (case-sensitive)

### Returns
`Language` — The language instance

### Raises
- **LanguageNotFoundError**: If the code is not a valid ISO 639-2 terminological code

### Notes
- Input is stripped of whitespace before lookup
- Not all languages have a 639-2 terminological code

### Example
```python
import iso639

lang = iso639.Language.from_part2t('fra')
print(lang.part3)  # 'fra'
print(lang.name)  # 'French'
```
```

--------------------------------

### Basic Language Lookup by Code

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/QUICK-REFERENCE.md

Performs a basic lookup of a language using its code (e.g., 'fra'). Requires the iso639 library to be imported. Prints the full name of the language.

```python
import iso639

lang = iso639.Language.match('fra')
print(lang.name)  # 'French'
print(lang.part1)  # 'fr'
```

--------------------------------

### Case-Insensitive Matching in iso639

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/match-algorithm.md

Illustrates case-insensitive matching where the method retries with lowercase and title case inputs if an exact match fails. Useful for variable user input.

```python
import iso639

# All succeed with case-insensitive matching
lang1 = iso639.Language.match('fra', strict_case=False)
lang2 = iso639.Language.match('FRA', strict_case=False)
lang3 = iso639.Language.match('Fra', strict_case=False)

# All refer to the same language
assert lang1 == lang2 == lang3

# Applies to names too
lang4 = iso639.Language.match('French', strict_case=False)  # Title case
lang5 = iso639.Language.match('french', strict_case=False)  # Lowercase
lang6 = iso639.Language.match('FRENCH', strict_case=False)  # Uppercase

assert lang4 == lang5 == lang6
```

--------------------------------

### Strict Case Matching in iso639

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/match-algorithm.md

Demonstrates strict case matching where only exact input matches are successful. Raises LanguageNotFoundError for case mismatches.

```python
import iso639

# Succeeds (exact match)
lang1 = iso639.Language.match('fra')

# Fails (uppercase not matched)
try:
    lang2 = iso639.Language.match('FRA')
except iso639.LanguageNotFoundError:
    print("Uppercase code not found")

# Succeeds (reference name)
lang3 = iso639.Language.match('French')

# Fails (lowercase name not matched)
try:
    lang4 = iso639.Language.match('french')
except iso639.LanguageNotFoundError:
    print("Lowercase name not found")
```

--------------------------------

### Basic Exception Handling

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/LanguageNotFoundError.md

Demonstrates how to catch and handle the LanguageNotFoundError when an invalid language code is provided.

```APIDOC
## Basic Exception Handling

```python
import iso639

try:
    lang = iso639.Language.from_part3('invalid')
except iso639.LanguageNotFoundError as e:
    print(f"Error: {e}")
```
```

--------------------------------

### Case-Insensitive Language Code Matching

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/errors.md

Demonstrates how to perform case-insensitive lookups for language codes using `Language.match` with `strict_case=False`. This is useful when input casing may vary.

```python
import iso639

# This fails (case-sensitive)
try:
    lang = iso639.Language.from_part3('FRA')
except iso639.LanguageNotFoundError:
    print("Uppercase code not found")

# This succeeds (case-insensitive match)
lang = iso639.Language.match('FRA', strict_case=False)
print(lang.name)  # 'French'
```

--------------------------------

### Migrate from pycountry

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/migration-guide.md

Adapt calls from `pycountry.languages.get(alpha_3='fra')` to `iso639.Language.from_part3('fra')` and access the name attribute.

```python
# Old pycountry
# import pycountry
# lang = pycountry.languages.get(alpha_3='fra')
# name = lang.name

# New python-iso639
import iso639
lang = iso639.Language.from_part3('fra')
name = lang.name
```

--------------------------------

### __version__

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

The version of the python-iso639 package. Uses calendar versioning (CalVer format YYYY.M.D).

```APIDOC
## __version__

### Description
The version of the python-iso639 package. Uses calendar versioning (CalVer format YYYY.M.D).

### Type
`str`

### Example
```python
import iso639
print(iso639.__version__)  # '2026.4.20'
```
```

--------------------------------

### Accessing Alternative Language Names

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Name.md

Demonstrates how to retrieve and iterate through alternative names for a language using the Language.match() method and the 'other_names' attribute.

```python
import iso639

language = iso639.Language.match('yue')
if language.other_names:
    for name in language.other_names:
        print(f"Print: {name.print}")
        print(f"Inverted: {name.inverted}")
```

--------------------------------

### Safe Lookups

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

Illustrates how to safely look up languages and handle potential `LanguageNotFoundError` exceptions.

```APIDOC
## Safe Lookups

### Description
Illustrates how to safely look up languages and handle potential `LanguageNotFoundError` exceptions.

### Example
```python
import iso639

code = 'xyz'
try:
    lang = iso639.Language.from_part3(code)
except iso639.LanguageNotFoundError:
    print(f"Language code '{code}' not found")
```
```

--------------------------------

### Safe Language Lookup with Error Handling

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/module-iso639.md

Demonstrates how to safely look up a language by its part3 code using a try-except block to catch `LanguageNotFoundError` if the code is not found.

```python
import iso639

code = 'xyz'
try:
    lang = iso639.Language.from_part3(code)
except iso639.LanguageNotFoundError:
    print(f"Language code '{code}' not found")
```

--------------------------------

### Language Dataclass to Dictionary Conversion

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/types.md

Shows how to convert a Language dataclass instance into a dictionary using `dataclasses.asdict`. This is useful for inspecting language data or serializing it.

```python
import dataclasses
import iso639

lang = iso639.Language.from_part3('fra')
data = dataclasses.asdict(lang)
print(data['part3'])  # 'fra'
```

--------------------------------

### Check Language Status

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/data-reference.md

Demonstrates how to count active and retired ISO 639-3 codes.

```python
import iso639

# Active codes
active = [l for l in iso639.ALL_LANGUAGES if l.status == 'A']
print(f"Active codes: {len(active)}")

# Retired codes
retired = [l for l in iso639.ALL_LANGUAGES if l.status == 'R']
print(f"Retired codes: {len(retired)}")
```

--------------------------------

### Create Language from ISO 639-3 Code

Source: https://github.com/jacksonllee/iso639/blob/main/_autodocs/api-reference/Language.md

Instantiate a `Language` object using its ISO 639-3 code with the `from_part3` classmethod. This method is case-sensitive and supports both active and retired codes. Raises `LanguageNotFoundError` if the code is invalid.

```python
import iso639

lang = iso639.Language.from_part3('fra')
print(lang.name)  # 'French'
print(lang.part1)  # 'fr'

# Retired codes also work
retired = iso639.Language.from_part3('bvs')
print(retired.status)  # 'R'
```