# iso639-lang
`iso639-lang` handles the ISO 639 code for individual languages and language groups.
```python
>>> from iso639 import Lang
>>> Lang("French")
Lang(name='French', pt1='fr', pt2b='fre', pt2t='fra', pt3='fra', pt5='')
```
## Installation
```console
$ pip install iso639-lang
```
`iso639-lang` supports Python 3.9+.
## Usage
Begin by importing the `Lang` class.
```python
>>> from iso639 import Lang
```
Let's try with the identifier of an individual language.
```python
>>> lg = Lang("deu")
>>> lg.name # 639-3 reference name
'German'
>>> lg.pt1 # 639-1 identifier
'de'
>>> lg.pt2b # 639-2/B bibliographic identifier
'ger'
>>> lg.pt2t # 639-2/T terminological identifier
'deu'
>>> lg.pt3 # 639-3 identifier
'deu'
```
And now with the identifier of a group of languages.
```python
>>> lg = Lang("cel")
>>> lg.name # 639-5 English name
'Celtic languages'
>>> lg.pt2b # 639-2/B bibliographic identifier
'cel'
>>> lg.pt2t # 639-2/T terminological identifier
'cel'
>>> lg.pt5 # 639-5 identifier
'cel'
```
`Lang` is instantiable with any ISO 639 identifier or reference name.
```python
>>> Lang("German") == Lang("de") == Lang("deu") == Lang("ger")
True
```
`Lang` also recognizes all non-reference English names associated with a language identifier in ISO 639.
```python
>>> Lang("Chinese, Mandarin") # 639-3 inverted name
Lang(name='Mandarin Chinese', pt1='', pt2b='', pt2t='', pt3='cmn', pt5='')
>>> Lang("Uyghur") # other 639-3 printed name
Lang(name='Uighur', pt1='ug', pt2b='uig', pt2t='uig', pt3='uig', pt5='')
>>> Lang("Valencian") # other 639-2 English name
Lang(name='Catalan', pt1='ca', pt2b='cat', pt2t='cat', pt3='cat', pt5='')
```
Please note that `Lang` is case-sensitive.
```python
>>> Lang("ak")
Lang(name='Akan', pt1='ak', pt2b='aka', pt2t='aka', pt3='aka', pt5='')
>>> Lang("Ak")
Lang(name='Ak', pt1='', pt2b='', pt2t='', pt3='akq', pt5='')
```
### Other Language Names
In addition to their reference name, some language identifiers may be associated with other names. You can list them using the `other_names` method.
```python
>>> lg = Lang("ast")
>>> lg.name
'Asturian'
>>> lg.other_names()
['Asturleonese', 'Bable', 'Leonese']
```
### Language Type
The type of a language is accessible thanks to the `type` method.
```python
>>> lg = Lang("Latin")
>>> lg.type()
'Historical'
```
### Macrolanguage & Individual Languages
You can easily determine whether a language is a macrolanguage or an individual language.
```python
>>> lg = Lang("Arabic")
>>> lg.scope()
'Macrolanguage'
```
Use the `macro` method to get the macrolanguage of an individual language.
```python
>>> lg = Lang("Wu Chinese")
>>> lg.macro()
Lang(name='Chinese', pt1='zh', pt2b='chi', pt2t='zho', pt3='zho', pt5='')
```
Conversely, you can also list all the individual languages that share a common macrolanguage.
```python
>>> lg = Lang("Persian")
>>> lg.individuals()
[Lang(name='Iranian Persian', pt1='', pt2b='', pt2t='', pt3='pes', pt5=''),
Lang(name='Dari', pt1='', pt2b='', pt2t='', pt3='prs', pt5='')]
```
### Exceptions
When an invalid language value is passed to `Lang`, an `InvalidLanguageValue` exception is raised.
```python
>>> from iso639.exceptions import InvalidLanguageValue
>>> try:
... Lang("foobar")
... except InvalidLanguageValue as e:
... e.msg
...
"'foobar' is not a valid Lang argument."
```
When a deprecated language value is passed to `Lang`, a `DeprecatedLanguageValue` exception is raised.
```python
>>> from iso639.exceptions import DeprecatedLanguageValue
>>> try:
... Lang("gsc")
... except DeprecatedLanguageValue as e:
... lg = Lang(e.change_to)
... f"{e.name} replaced by {lg.name}."
...
'Gascon replaced by Occitan (post 1500).'
```
Note that you can use the `is_language` language checker if you don't want to handle exceptions.
### Checker
The `is_language` function checks if a language value exists according to ISO 639.
```python
>>> from iso639 import is_language
>>> is_language("fr")
True
>>> is_language("French")
True
```
You can restrict the check to certain identifiers or names by passing an additional argument.
```python
>>> is_language("fr", "pt3") # only 639-3
False
>>> is_language("fre", ("pt2b", "pt2t")) # only 639-2/B or 639-2/T
True
```
### Iterator
`iter_langs()` iterates through all possible `Lang` instances, ordered alphabetically by name.
```python
>>> from iso639 import iter_langs
>>> [lg.name for lg in iter_langs()]
["'Are'are", "'Auhelawa", "A'ou", ... , 'ǂHua', 'ǂUngkue', 'ǃXóõ']
```
## Speed
`iso639-lang` loads its mappings into memory to process calls much faster than Python libraries that rely on an embedded database.
## Sources
As of July 19, 2025, `iso639-lang` is based on the latest tables provided by the ISO 639 registration authorities. Please open a new issue if you find that this library uses out-of-date data files.
| Set | Description | Registration Authority | Last Modified |
|--------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------|---------------------------------------------------------------------------|
| [Set 1](https://iso639-3.sil.org/sites/iso639-3/files/downloads/iso-639-3.tab) | _two-letter language identifiers for major, mostly national individual languages_ | Infoterm | [2009-09-01](https://www.loc.gov/standards/iso639-2/php/code_changes.php) |
| [Set 2](https://www.loc.gov/standards/iso639-2/ISO-639-2_utf-8.txt) | _three-letter language identifiers for a larger number of widely known individual languages and a number of language groups_ | Library of Congress | [2017-12-21](https://www.loc.gov/standards/iso639-2/php/code_changes.php) |
| [Set 3](https://iso639-3.sil.org/sites/iso639-3/files/downloads/iso-639-3.tab) | _three-letter language identifiers covering all individual languages, including living, extinct and ancient languages_ | SIL International | [2025-07-15](https://iso639-3.sil.org/code_tables/download_tables) |
| [Set 5](http://id.loc.gov/vocabulary/iso639-5.tsv) | _three-letter language identifiers covering a larger set of language groups, living and extinct_ | Library of Congress | [2013-02-11](https://www.loc.gov/standards/iso639-5/changes.php) |
To learn more about how the source tables are processed by the `iso639-lang` library, read the [`generate.py`](https://github.com/LBeaudoux/iso639/blob/master/generate.py) script.
## Contributing
We welcome contributions from the community to help improve this Python library. If you're interested in contributing, please follow the guidelines [here](https://github.com/LBeaudoux/iso639/blob/master/CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "iso639-lang",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ISO 639, ISO 639-1, ISO 639-2, ISO 639-3, ISO 639-5, language code",
"author": null,
"author_email": "Laurent Beaudoux <lbeaudoux@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c6/8e/1c7b86a4a3893eb418eeed37cb3b78079ea3be995dfd2a4c6a2f4dfae986/iso639_lang-2.6.2.tar.gz",
"platform": null,
"description": "\n# iso639-lang\n\n\n\n\n \n`iso639-lang` handles the ISO\u00a0639 code for individual languages and language groups.\n\n```python\n>>> from iso639 import Lang\n>>> Lang(\"French\")\nLang(name='French', pt1='fr', pt2b='fre', pt2t='fra', pt3='fra', pt5='')\n```\n\n## Installation\n\n```console\n$ pip install iso639-lang\n```\n`iso639-lang` supports Python 3.9+. \n \n## Usage\n\nBegin by importing the `Lang` class.\n```python\n>>> from iso639 import Lang\n```\n\nLet's try with the identifier of an individual language.\n```python\n>>> lg = Lang(\"deu\")\n>>> lg.name # 639-3 reference name\n'German'\n>>> lg.pt1 # 639-1 identifier\n'de'\n>>> lg.pt2b # 639-2/B bibliographic identifier\n'ger'\n>>> lg.pt2t # 639-2/T terminological identifier\n'deu'\n>>> lg.pt3 # 639-3 identifier\n'deu'\n```\n\nAnd now with the identifier of a group of languages.\n```python\n>>> lg = Lang(\"cel\")\n>>> lg.name # 639-5 English name\n'Celtic languages'\n>>> lg.pt2b # 639-2/B bibliographic identifier\n'cel'\n>>> lg.pt2t # 639-2/T terminological identifier\n'cel'\n>>> lg.pt5 # 639-5 identifier\n'cel'\n```\n\n`Lang` is instantiable with any ISO\u00a0639 identifier or reference name.\n```python\n>>> Lang(\"German\") == Lang(\"de\") == Lang(\"deu\") == Lang(\"ger\")\nTrue\n```\n\n`Lang` also recognizes all non-reference English names associated with a language identifier in ISO\u00a0639.\n```python\n>>> Lang(\"Chinese, Mandarin\") # 639-3 inverted name\nLang(name='Mandarin Chinese', pt1='', pt2b='', pt2t='', pt3='cmn', pt5='')\n>>> Lang(\"Uyghur\") # other 639-3 printed name\nLang(name='Uighur', pt1='ug', pt2b='uig', pt2t='uig', pt3='uig', pt5='')\n>>> Lang(\"Valencian\") # other 639-2 English name\nLang(name='Catalan', pt1='ca', pt2b='cat', pt2t='cat', pt3='cat', pt5='')\n```\n\nPlease note that `Lang` is case-sensitive.\n```python\n>>> Lang(\"ak\")\nLang(name='Akan', pt1='ak', pt2b='aka', pt2t='aka', pt3='aka', pt5='')\n>>> Lang(\"Ak\")\nLang(name='Ak', pt1='', pt2b='', pt2t='', pt3='akq', pt5='')\n```\n\n### Other Language Names\n\nIn addition to their reference name, some language identifiers may be associated with other names. You can list them using the `other_names` method.\n```python\n>>> lg = Lang(\"ast\")\n>>> lg.name\n'Asturian'\n>>> lg.other_names()\n['Asturleonese', 'Bable', 'Leonese']\n```\n\n### Language Type\n\nThe type of a language is accessible thanks to the `type` method.\n```python\n>>> lg = Lang(\"Latin\")\n>>> lg.type()\n'Historical'\n```\n\n### Macrolanguage & Individual Languages\n\nYou can easily determine whether a language is a macrolanguage or an individual language.\n```python\n>>> lg = Lang(\"Arabic\")\n>>> lg.scope()\n'Macrolanguage'\n```\n\nUse the `macro` method to get the macrolanguage of an individual language.\n```python\n>>> lg = Lang(\"Wu Chinese\")\n>>> lg.macro()\nLang(name='Chinese', pt1='zh', pt2b='chi', pt2t='zho', pt3='zho', pt5='')\n```\n\nConversely, you can also list all the individual languages that share a common macrolanguage.\n```python\n>>> lg = Lang(\"Persian\")\n>>> lg.individuals()\n[Lang(name='Iranian Persian', pt1='', pt2b='', pt2t='', pt3='pes', pt5=''), \nLang(name='Dari', pt1='', pt2b='', pt2t='', pt3='prs', pt5='')]\n```\n\n### Exceptions\n\nWhen an invalid language value is passed to `Lang`, an `InvalidLanguageValue` exception is raised.\n```python\n>>> from iso639.exceptions import InvalidLanguageValue\n>>> try:\n... Lang(\"foobar\")\n... except InvalidLanguageValue as e:\n... e.msg\n... \n\"'foobar' is not a valid Lang argument.\"\n```\n\nWhen a deprecated language value is passed to `Lang`, a `DeprecatedLanguageValue` exception is raised.\n```python\n>>> from iso639.exceptions import DeprecatedLanguageValue\n>>> try:\n... Lang(\"gsc\")\n... except DeprecatedLanguageValue as e:\n... lg = Lang(e.change_to)\n... f\"{e.name} replaced by {lg.name}.\"\n...\n'Gascon replaced by Occitan (post 1500).'\n```\n\nNote that you can use the `is_language` language checker if you don't want to handle exceptions.\n\n### Checker\n\nThe `is_language` function checks if a language value exists according to ISO\u00a0639.\n\n```python\n>>> from iso639 import is_language\n>>> is_language(\"fr\")\nTrue\n>>> is_language(\"French\")\nTrue\n```\n\nYou can restrict the check to certain identifiers or names by passing an additional argument.\n```python\n>>> is_language(\"fr\", \"pt3\") # only\u00a0639-3\nFalse\n>>> is_language(\"fre\", (\"pt2b\", \"pt2t\")) # only 639-2/B or 639-2/T\nTrue\n```\n\n### Iterator\n\n`iter_langs()` iterates through all possible `Lang` instances, ordered alphabetically by name.\n\n```python\n>>> from iso639 import iter_langs\n>>> [lg.name for lg in iter_langs()]\n[\"'Are'are\", \"'Auhelawa\", \"A'ou\", ... , '\u01c2Hua', '\u01c2Ungkue', '\u01c3X\u00f3\u00f5']\n```\n\n\n## Speed\n\n`iso639-lang` loads its mappings into memory to process calls much faster than Python libraries that rely on an embedded database.\n\n\n## Sources\n\nAs of July 19, 2025, `iso639-lang` is based on the latest tables provided by the ISO\u00a0639 registration authorities. Please open a new issue if you find that this library uses out-of-date data files.\n \n| Set | Description | Registration Authority | Last Modified |\n|--------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------|---------------------------------------------------------------------------|\n| [Set\u00a01](https://iso639-3.sil.org/sites/iso639-3/files/downloads/iso-639-3.tab) | _two-letter language identifiers for major, mostly national individual languages_ | Infoterm | [2009-09-01](https://www.loc.gov/standards/iso639-2/php/code_changes.php) |\n| [Set\u00a02](https://www.loc.gov/standards/iso639-2/ISO-639-2_utf-8.txt) | _three-letter language identifiers for a larger number of widely known individual languages and a number of language groups_ | Library of Congress | [2017-12-21](https://www.loc.gov/standards/iso639-2/php/code_changes.php) |\n| [Set\u00a03](https://iso639-3.sil.org/sites/iso639-3/files/downloads/iso-639-3.tab) | _three-letter language identifiers covering all individual languages, including living, extinct and ancient languages_ | SIL International | [2025-07-15](https://iso639-3.sil.org/code_tables/download_tables) |\n| [Set\u00a05](http://id.loc.gov/vocabulary/iso639-5.tsv) | _three-letter language identifiers covering a larger set of language groups, living and extinct_ | Library of Congress | [2013-02-11](https://www.loc.gov/standards/iso639-5/changes.php) |\n\nTo learn more about how the source tables are processed by the `iso639-lang` library, read the [`generate.py`](https://github.com/LBeaudoux/iso639/blob/master/generate.py) script.\n\n## Contributing\n\nWe welcome contributions from the community to help improve this Python library. If you're interested in contributing, please follow the guidelines [here](https://github.com/LBeaudoux/iso639/blob/master/CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "A fast, comprehensive, ISO 639 library.",
"version": "2.6.2",
"project_urls": {
"Homepage": "https://github.com/LBeaudoux/iso639"
},
"split_keywords": [
"iso 639",
" iso 639-1",
" iso 639-2",
" iso 639-3",
" iso 639-5",
" language code"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "84033bc05a9dd6d5f0d986f1ea55d030bedbbed8ddb70acdc978c7a2c054a82b",
"md5": "5f85cc3481975496718d182ff6cea598",
"sha256": "fedac2b04ea928b0ac0219ad15ce04dfcadba651dc0e38f101adf4a5c2e41a61"
},
"downloads": -1,
"filename": "iso639_lang-2.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f85cc3481975496718d182ff6cea598",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 324925,
"upload_time": "2025-07-19T08:30:02",
"upload_time_iso_8601": "2025-07-19T08:30:02.494429Z",
"url": "https://files.pythonhosted.org/packages/84/03/3bc05a9dd6d5f0d986f1ea55d030bedbbed8ddb70acdc978c7a2c054a82b/iso639_lang-2.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c68e1c7b86a4a3893eb418eeed37cb3b78079ea3be995dfd2a4c6a2f4dfae986",
"md5": "33f1847336ea5de4ee2e3627bf244267",
"sha256": "f451fce6598bdabba04b4bcf330695444f2d687bd1e341f4870792cf6031c658"
},
"downloads": -1,
"filename": "iso639_lang-2.6.2.tar.gz",
"has_sig": false,
"md5_digest": "33f1847336ea5de4ee2e3627bf244267",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 319324,
"upload_time": "2025-07-19T08:30:03",
"upload_time_iso_8601": "2025-07-19T08:30:03.883271Z",
"url": "https://files.pythonhosted.org/packages/c6/8e/1c7b86a4a3893eb418eeed37cb3b78079ea3be995dfd2a4c6a2f4dfae986/iso639_lang-2.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 08:30:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LBeaudoux",
"github_project": "iso639",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "iso639-lang"
}
JSON
