# PYCLD2 - Python Bindings to CLD2
Python bindings for the Compact Langauge Detect 2 (CLD2).
[](https://pypi.python.org/pypi/pycld2)
[](https://pypi.python.org/pypi/pycld2)
[](https://pypi.python.org/pypi/pycld2)
[](https://pypi.python.org/pypi/pycld2)
[](https://pypi.python.org/pypi/pycld2)
[](https://travis-ci.org/aboSamoor/pycld2)
This package contains forks of:
- The [`cld2` C++ library](https://github.com/CLD2Owners/cld2), developed by Dick Sites
- The [`chromium-compact-language-detector` C++ extension module](https://github.com/mikemccand/chromium-compact-language-detector),
originally created by Mike McCandless, which has been modified post-fork.
These bindings, among other changes, make the support of over 165 languages
the default.
The goal of this project is to consolidate the upstream library with its bindings, so the user can `pip install` one package instead of two.
The LICENSE is the same as Chromium's LICENSE and is included in the
LICENSE file for reference.
## Installing
```bash
$ python -m pip install -U pycld2
```
## Example
```python
import pycld2 as cld2
isReliable, textBytesFound, details = cld2.detect(
"а неправильный формат идентификатора дн назад"
)
print(isReliable)
# True
details[0]
# ('RUSSIAN', 'ru', 98, 404.0)
fr_en_Latn = """\
France is the largest country in Western Europe and the third-largest in Europe as a whole.
A accès aux chiens et aux frontaux qui lui ont été il peut consulter et modifier ses collections
et exporter Cet article concerne le pays européen aujourd’hui appelé République française.
Pour d’autres usages du nom France, Pour une aide rapide et effective, veuiller trouver votre aide
dans le menu ci-dessus.
Motoring events began soon after the construction of the first successful gasoline-fueled automobiles.
The quick brown fox jumped over the lazy dog."""
isReliable, textBytesFound, details, vectors = cld2.detect(
fr_en_Latn, returnVectors=True
)
print(vectors)
# ((0, 94, 'ENGLISH', 'en'), (94, 329, 'FRENCH', 'fr'), (423, 139, 'ENGLISH', 'en'))
```
## API
This package exports one function, `detect()`. See `help(detect)` for the full docstring.
The first parameter (`utf8Bytes`) is the text for which you want to detect language.
`utf8Bytes` may be either:
- `str` (example: `"¼ cup of flour"`)
- `bytes` that have been encoded using UTF-8 (example: `"¼ cup of flour".encode("utf-8")`)
Bytes that are *not* UTF-8 encoded will raise a `pycld2.error`. For example, passing
b"\xbc cup of flour" (which is `"¼ cup of flour".encode("latin-1")`) will raise.
All other parameters are optional:
| Parameter | Type/Default | Use |
| --------- | ------------ | --- |
| `utf8Bytes` | `str` or `bytes`\* | The text to detect language for. |
| `isPlainText` | `bool`, default `False` | If `False`, then the input is HTML and CLD will skip HTML tags, expand HTML entities, detect HTML `<lang ...>` tags, etc. |
| `hintTopLevelDomain` | `str` | E.g., `'id'` boosts Indonesian. |
| `hintLanguage` | `str` | E.g., `'ITALIAN'` or `'it'` boosts Italian; see `cld.LANGUAGES` for all known languages. |
| `hintLanguageHTTPHeaders` | `str` | E.g., `'mi,en'` boosts Maori and English. |
| `hintEncoding` | `str` | E.g, `'SJS'` boosts Japanese; see `cld.ENCODINGS` for all known encodings. |
| `returnVectors` | `bool`, default `False` | If `True`, then the vectors indicating which language was detected in which byte range are returned in addition to details. The vectors are a sequence of `(bytesOffset, bytesLength, languageName, languageCode)`, in order. `bytesOffset` is the start of the vector, `bytesLength `is the length of the vector. Note that there is some added CPU cost if this is True. (Approx. 2x performance hit.) |
| `debugScoreAsQuads` | `bool`, default `False` | Normally, several languages are detected solely by their Unicode script. Combined with appropritate lookup tables, this flag forces them instead to be detected via quadgrams. This can be a useful refinement when looking for meaningful text in these languages, instead of just character sets. The default tables do not support this use. |
| `debugHTML` | `bool`, default `False` | For each detection call, write an HTML file to stderr, showing the text chunks and their detected languages. See `cld2/docs/InterpretingCLD2UnitTestOutput.pdf` to interpret this output. |
| `debugCR` | `bool`, default `False` | In that HTML file, force a new line for each chunk. |
| `debugVerbose` | `bool`, default `False` | In that HTML file, show every lookup entry. |
| `debugQuiet` | `bool`, default `False` | In that HTML file, suppress most of the output detail. |
| `debugEcho` | `bool`, default `False` | Echo every input buffer to stderr. |
| `bestEffort` | `bool`, default `False` | If `True`, then allow low-quality results for short text, rather than forcing the result to `"UNKNOWN_LANGUAGE"`. This may be of use for those desiring approximate results on short input text, but there is no claim that these result are very good. |
<sup>\*If `bytes`, must be UTF-8 encoded bytes.</sup>
## Constants
This package exports these global constants:
| Constant | Description |
| -------- | ----------- |
| `pycld2.ENCODINGS` | list of the encoding names CLD recognizes (if you provide `hintEncoding`, it must be one of these names). |
| `pycld2.LANGUAGES` | list of languages and their codes (if you provide `hintLanguageCode`, it must be one of the codes from these codes). |
| `pycld2.EXTERNAL_LANGUAGES` | list of external languages and their codes. |
| `pycld2.DETECTED_LANGUAGES` | list of all detectable languages. |
## What About CLD3?
Python bindings for [CLD3](https://github.com/google/cld3/) are available as a separate project, [`pycld3`](https://github.com/bsolomon1124/pycld3).
Raw data
{
"_id": null,
"home_page": "https://github.com/aboSamoor/pycld2",
"name": "pycld2",
"maintainer": "Brad Solomon",
"docs_url": null,
"requires_python": "",
"maintainer_email": "brad.solomon.1124@gmail.com",
"keywords": "",
"author": "Rami Al-Rfou",
"author_email": "rmyeid@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/21/d2/8b0def84a53c88d0eb27c67b05269fbd16ad68df8c78849e7b5d65e6aec3/pycld2-0.41.tar.gz",
"platform": "",
"description": "# PYCLD2 - Python Bindings to CLD2\n\nPython bindings for the Compact Langauge Detect 2 (CLD2).\n\n[](https://pypi.python.org/pypi/pycld2)\n[](https://pypi.python.org/pypi/pycld2)\n[](https://pypi.python.org/pypi/pycld2)\n[](https://pypi.python.org/pypi/pycld2)\n[](https://pypi.python.org/pypi/pycld2)\n[](https://travis-ci.org/aboSamoor/pycld2)\n\nThis package contains forks of:\n\n- The [`cld2` C++ library](https://github.com/CLD2Owners/cld2), developed by Dick Sites\n- The [`chromium-compact-language-detector` C++ extension module](https://github.com/mikemccand/chromium-compact-language-detector),\n originally created by Mike McCandless, which has been modified post-fork.\n These bindings, among other changes, make the support of over 165 languages\n the default.\n\nThe goal of this project is to consolidate the upstream library with its bindings, so the user can `pip install` one package instead of two.\n\nThe LICENSE is the same as Chromium's LICENSE and is included in the\nLICENSE file for reference.\n\n## Installing\n\n```bash\n$ python -m pip install -U pycld2\n```\n\n## Example\n\n```python\nimport pycld2 as cld2\n\nisReliable, textBytesFound, details = cld2.detect(\n \"\u0430 \u043d\u0435\u043f\u0440\u0430\u0432\u0438\u043b\u044c\u043d\u044b\u0439 \u0444\u043e\u0440\u043c\u0430\u0442 \u0438\u0434\u0435\u043d\u0442\u0438\u0444\u0438\u043a\u0430\u0442\u043e\u0440\u0430 \u0434\u043d \u043d\u0430\u0437\u0430\u0434\"\n)\n\nprint(isReliable)\n# True\ndetails[0]\n# ('RUSSIAN', 'ru', 98, 404.0)\n\nfr_en_Latn = \"\"\"\\\nFrance is the largest country in Western Europe and the third-largest in Europe as a whole.\nA acc\u00e8s aux chiens et aux frontaux qui lui ont \u00e9t\u00e9 il peut consulter et modifier ses collections\net exporter Cet article concerne le pays europ\u00e9en aujourd\u2019hui appel\u00e9 R\u00e9publique fran\u00e7aise.\nPour d\u2019autres usages du nom France, Pour une aide rapide et effective, veuiller trouver votre aide\ndans le menu ci-dessus.\nMotoring events began soon after the construction of the first successful gasoline-fueled automobiles.\nThe quick brown fox jumped over the lazy dog.\"\"\"\n\nisReliable, textBytesFound, details, vectors = cld2.detect(\n fr_en_Latn, returnVectors=True\n)\nprint(vectors)\n# ((0, 94, 'ENGLISH', 'en'), (94, 329, 'FRENCH', 'fr'), (423, 139, 'ENGLISH', 'en'))\n```\n\n## API\n\nThis package exports one function, `detect()`. See `help(detect)` for the full docstring.\n\nThe first parameter (`utf8Bytes`) is the text for which you want to detect language.\n\n`utf8Bytes` may be either:\n\n- `str` (example: `\"\u00bc cup of flour\"`)\n- `bytes` that have been encoded using UTF-8 (example: `\"\u00bc cup of flour\".encode(\"utf-8\")`)\n\nBytes that are *not* UTF-8 encoded will raise a `pycld2.error`. For example, passing\nb\"\\xbc cup of flour\" (which is `\"\u00bc cup of flour\".encode(\"latin-1\")`) will raise.\n\nAll other parameters are optional:\n\n| Parameter | Type/Default | Use |\n| --------- | ------------ | --- |\n| `utf8Bytes` | `str` or `bytes`\\* | The text to detect language for. |\n| `isPlainText` | `bool`, default `False` | If `False`, then the input is HTML and CLD will skip HTML tags, expand HTML entities, detect HTML `<lang ...>` tags, etc. |\n| `hintTopLevelDomain` | `str` | E.g., `'id'` boosts Indonesian. |\n| `hintLanguage` | `str` | E.g., `'ITALIAN'` or `'it'` boosts Italian; see `cld.LANGUAGES` for all known languages. |\n| `hintLanguageHTTPHeaders` | `str` | E.g., `'mi,en'` boosts Maori and English. |\n| `hintEncoding` | `str` | E.g, `'SJS'` boosts Japanese; see `cld.ENCODINGS` for all known encodings. |\n| `returnVectors` | `bool`, default `False` | If `True`, then the vectors indicating which language was detected in which byte range are returned in addition to details. The vectors are a sequence of `(bytesOffset, bytesLength, languageName, languageCode)`, in order. `bytesOffset` is the start of the vector, `bytesLength `is the length of the vector. Note that there is some added CPU cost if this is True. (Approx. 2x performance hit.) |\n| `debugScoreAsQuads` | `bool`, default `False` | Normally, several languages are detected solely by their Unicode script. Combined with appropritate lookup tables, this flag forces them instead to be detected via quadgrams. This can be a useful refinement when looking for meaningful text in these languages, instead of just character sets. The default tables do not support this use. |\n| `debugHTML` | `bool`, default `False` | For each detection call, write an HTML file to stderr, showing the text chunks and their detected languages. See `cld2/docs/InterpretingCLD2UnitTestOutput.pdf` to interpret this output. |\n| `debugCR` | `bool`, default `False` | In that HTML file, force a new line for each chunk. |\n| `debugVerbose` | `bool`, default `False` | In that HTML file, show every lookup entry. |\n| `debugQuiet` | `bool`, default `False` | In that HTML file, suppress most of the output detail. |\n| `debugEcho` | `bool`, default `False` | Echo every input buffer to stderr. |\n| `bestEffort` | `bool`, default `False` | If `True`, then allow low-quality results for short text, rather than forcing the result to `\"UNKNOWN_LANGUAGE\"`. This may be of use for those desiring approximate results on short input text, but there is no claim that these result are very good. |\n\n<sup>\\*If `bytes`, must be UTF-8 encoded bytes.</sup>\n\n## Constants\n\nThis package exports these global constants:\n\n| Constant | Description |\n| -------- | ----------- |\n| `pycld2.ENCODINGS` | list of the encoding names CLD recognizes (if you provide `hintEncoding`, it must be one of these names). |\n| `pycld2.LANGUAGES` | list of languages and their codes (if you provide `hintLanguageCode`, it must be one of the codes from these codes). |\n| `pycld2.EXTERNAL_LANGUAGES` | list of external languages and their codes. |\n| `pycld2.DETECTED_LANGUAGES` | list of all detectable languages. |\n\n## What About CLD3?\n\nPython bindings for [CLD3](https://github.com/google/cld3/) are available as a separate project, [`pycld3`](https://github.com/bsolomon1124/pycld3).",
"bugtrack_url": null,
"license": "Apache2",
"summary": "Python bindings around Google Chromium's embedded compact language detection library (CLD2)",
"version": "0.41",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "cff427c2cfa50bb9d11055a03a291042",
"sha256": "a42f6e974df8fdd70685c2baa8a9f523069a260e1140ce604fb9f1fb6c3064df"
},
"downloads": -1,
"filename": "pycld2-0.41.tar.gz",
"has_sig": false,
"md5_digest": "cff427c2cfa50bb9d11055a03a291042",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 41405351,
"upload_time": "2019-10-14T15:23:39",
"upload_time_iso_8601": "2019-10-14T15:23:39.130781Z",
"url": "https://files.pythonhosted.org/packages/21/d2/8b0def84a53c88d0eb27c67b05269fbd16ad68df8c78849e7b5d65e6aec3/pycld2-0.41.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-10-14 15:23:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "aboSamoor",
"github_project": "pycld2",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "wheel",
"specs": [
[
"==",
"0.23.0"
]
]
}
],
"lcname": "pycld2"
}
JSON
