{"id":15035628,"url":"https://github.com/deeplcom/deepl-python","last_synced_at":"2025-05-13T21:11:59.447Z","repository":{"id":38109315,"uuid":"387469387","full_name":"DeepLcom/deepl-python","owner":"DeepLcom","description":"Official Python library for the DeepL language translation API.","archived":false,"fork":false,"pushed_at":"2025-04-10T10:13:04.000Z","size":646,"stargazers_count":1221,"open_issues_count":41,"forks_count":84,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-04-28T17:05:12.006Z","etag":null,"topics":["api","deepl","i18n","language","official","python","translation","translator"],"latest_commit_sha":null,"homepage":"https://www.deepl.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeepLcom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-19T13:12:53.000Z","updated_at":"2025-04-27T22:59:57.000Z","dependencies_parsed_at":"2024-02-12T11:31:46.931Z","dependency_job_id":"1c74e1c3-2933-4f74-921b-6dc1037d3724","html_url":"https://github.com/DeepLcom/deepl-python","commit_stats":{"total_commits":172,"total_committers":7,"mean_commits":"24.571428571428573","dds":0.09302325581395354,"last_synced_commit":"43a4538afa1764a402f051c05b66caa7b3b53752"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeepLcom","download_url":"https://codeload.github.com/DeepLcom/deepl-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254029004,"owners_count":22002283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","deepl","i18n","language","official","python","translation","translator"],"created_at":"2024-09-24T20:29:05.231Z","updated_at":"2025-05-13T21:11:54.425Z","avatar_url":"https://github.com/DeepLcom.png","language":"Python","readme":"# DeepL Python Library\n\n[![PyPI version](https://img.shields.io/pypi/v/deepl.svg)](https://pypi.org/project/deepl/)\n[![Supported Python versions](https://img.shields.io/pypi/pyversions/deepl.svg)](https://pypi.org/project/deepl/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blueviolet.svg)](https://github.com/DeepLcom/deepl-python/blob/main/LICENSE)\n\nThe [DeepL API][api-docs] is a language AI API that allows other computer programs\nto send texts and documents to DeepL's servers and receive high-quality\ntranslations and improvements to the text. This opens a whole universe of\nopportunities for developers: any translation product you can imagine can now\nbe built on top of DeepL's best-in-class translation technology.\n\nThe DeepL Python library offers a convenient way for applications written in\nPython to interact with the DeepL API. We intend to support all API functions\nwith the library, though support for new features may be added to the library\nafter they’re added to the API.\n\n## Getting an authentication key\n\nTo use the DeepL Python Library, you'll need an API authentication key. To get a\nkey, [please create an account here][create-account]. With a DeepL API Free\naccount you can consume up to 500,000 characters/month for free.\n\n## Installation\n\nThe library can be installed from [PyPI][pypi-project] using pip:\n\n```shell\npip install --upgrade deepl\n```\n\nIf you need to modify this source code, install the dependencies using poetry:\n\n```shell\npoetry install\n```\n\nOn Ubuntu 22.04 an error might occur: `ModuleNotFoundError: No module named \n'cachecontrol'`. Use the workaround `sudo apt install python3-cachecontrol` as\nexplained in this [bug report][bug-report-ubuntu-2204].\n\n### Requirements\n\nThe library is tested with Python versions 3.6 to 3.11.\n\nThe `requests` module is used to perform HTTP requests; the minimum is version\n2.0.\n\nStarting in 2024, we will drop support for older Python versions that have\nreached official end-of-life. You can find the Python versions and support\ntimelines [here][python-version-list].\nTo continue using this library, you should update to Python 3.8+.\n\n## Usage\n\nImport the package and construct a `DeepLClient`. The first argument is a string\ncontaining your API authentication key as found in your\n[DeepL Pro Account][pro-account].\n\nBe careful not to expose your key, for example when sharing source code.\n\n```python\nimport deepl\n\nauth_key = \"f63c02c5-f056-...\"  # Replace with your key\ndeepl_client = deepl.DeepLClient(auth_key)\n\nresult = deepl_client.translate_text(\"Hello, world!\", target_lang=\"FR\")\nprint(result.text)  # \"Bonjour, le monde !\"\n```\n\nThis example is for demonstration purposes only. In production code, the\nauthentication key should not be hard-coded, but instead fetched from a\nconfiguration file or environment variable.\n\n`DeepLClient` accepts additional options, see [Configuration](#configuration)\nfor more information.\n\n### Translating text\n\nTo translate text, call `translate_text()`. The first argument is a string\ncontaining the text you want to translate, or a list of strings if you want to\ntranslate multiple texts.\n\n`source_lang` and `target_lang` specify the source and target language codes\nrespectively. The `source_lang` is optional, if it is unspecified the source\nlanguage will be auto-detected.\n\nLanguage codes are **case-insensitive** strings according to ISO 639-1, for\nexample `'DE'`, `'FR'`, `'JA''`. Some target languages also include the regional\nvariant according to ISO 3166-1, for example `'EN-US'`, or `'PT-BR'`. The full\nlist of supported languages is in the\n[API documentation][api-docs-lang-list].\n\nThere are additional optional arguments to control translation, see\n[Text translation options](#text-translation-options) below.\n\n`translate_text()` returns a `TextResult`, or a list of `TextResult`s\ncorresponding to your input text(s). `TextResult` has the following properties:\n- `text` is the translated text,\n- `detected_source_lang` is the detected source language code,\n- `billed_characters` is the number of characters billed for the translation.\n- `model_type_used` indicates the translation model used, but is `None` unless\n  the `model_type` option is specified. \n\n```python\n# Translate text into a target language, in this case, French:\nresult = deepl_client.translate_text(\"Hello, world!\", target_lang=\"FR\")\nprint(result.text)  # \"Bonjour, le monde !\"\n\n# Translate multiple texts into British English\nresult = deepl_client.translate_text(\n    [\"お元気ですか？\", \"¿Cómo estás?\"],\n    target_lang=\"EN-GB\",\n)\nprint(result[0].text)  # \"How are you?\"\nprint(result[0].detected_source_lang)  # \"JA\" the language code for Japanese\nprint(result[0].billed_characters)  # 7 - the number of characters in the source text \"お元気ですか？\"\nprint(result[1].text)  # \"How are you?\"\nprint(result[1].detected_source_lang)  # \"ES\" the language code for Spanish\nprint(result[1].billed_characters)  # 12 - the number of characters in the source text \"¿Cómo estás?\"\n\n# Translate into German with less and more Formality:\nprint(\n    deepl_client.translate_text(\n        \"How are you?\", target_lang=\"DE\", formality=\"less\"\n    )\n)  # 'Wie geht es dir?'\nprint(\n    deepl_client.translate_text(\n        \"How are you?\", target_lang=\"DE\", formality=\"more\"\n    )\n)  # 'Wie geht es Ihnen?'\n```\n\n#### Text translation options\n\nIn addition to the input text(s) argument, the available `translate_text()`\narguments are:\n\n- `source_lang`: Specifies the source language code, but may be omitted to\n  auto-detect the source language.\n- `target_lang`: Required. Specifies the target language code.\n- `split_sentences`: specify how input text should be split into sentences,\n  default: `'on'`.\n    - `'on''` (`SplitSentences.ON`): input text will be split into sentences\n      using both newlines and punctuation.\n    - `'off'` (`SplitSentences.OFF`): input text will not be split into\n      sentences. Use this for applications where each input text contains only\n      one sentence.\n    - `'nonewlines'` (`SplitSentences.NO_NEWLINES`): input text will be split\n      into sentences using punctuation but not newlines.\n- `preserve_formatting`: controls automatic-formatting-correction. Set to `True`\n  to prevent automatic-correction of formatting, default: `False`.\n- `formality`: controls whether translations should lean toward informal or\n  formal language. This option is only available for some target languages, see\n  [Listing available languages](#listing-available-languages).\n    - `'less'` (`Formality.LESS`): use informal language.\n    - `'more'` (`Formality.MORE`): use formal, more polite language.\n- `glossary`: specifies a glossary to use with translation, either as a string\n  containing the glossary ID, or a `GlossaryInfo` as returned by\n  `get_glossary()`.\n- `context`: specifies additional context to influence translations, that is not\n  translated itself. Characters in the `context` parameter are not counted toward billing.\n  See the [API documentation][api-docs-context-param] for more information and \n  example usage.\n- `model_type`: specifies the type of translation model to use, options are:\n  - `'quality_optimized'` (`ModelType.QUALITY_OPTIMIZED`): use a translation\n    model that maximizes translation quality, at the cost of response time. \n    This option may be unavailable for some language pairs.\n  - `'prefer_quality_optimized'` (`ModelType.PREFER_QUALITY_OPTIMIZED`): use \n    the highest-quality translation model for the given language pair.\n  - `'latency_optimized'` (`ModelType.LATENCY_OPTIMIZED`): use a translation\n    model that minimizes response time, at the cost of translation quality.\n- `tag_handling`: type of tags to parse before translation, options are `'html'`\n  and `'xml'`.\n\nThe following options are only used if `tag_handling` is `'xml'`:\n\n- `outline_detection`: specify `False` to disable automatic tag detection,\n  default is `True`.\n- `splitting_tags`: list of XML tags that should be used to split text into\n  sentences. Tags may be specified as an array of strings (`['tag1', 'tag2']`),\n  or a comma-separated list of strings (`'tag1,tag2'`). The default is an empty\n  list.\n- `non_splitting_tags`: list of XML tags that should not be used to split text\n  into sentences. Format and default are the same as for `splitting_tags`.\n- `ignore_tags`: list of XML tags that containing content that should not be\n  translated. Format and default are the same as for `splitting_tags`.\n\nFor a detailed explanation of the XML handling options, see the\n[API documentation][api-docs-xml-handling].\n\n### Improving text (Write API)\n\nYou can use the Write API to improve or rephrase text. This is implemented in\nthe `rephrase_text()` method. The first argument is a string containing the text\nyou want to translate, or a list of strings if you want to translate multiple texts.\n\n`target_lang` optionally specifies the target language, e.g. when you want to change\nthe variant of a text (for example, you can send an english text to the write API and\nuse `target_lang` to turn it into British or American English). Please note that the\nWrite API itself does NOT translate. If you wish to translate and improve a text, you\nwill need to make multiple calls in a chain.\n\nLanguage codes are the same as for translating text.\n\nExample call:\n\n```python\nresult = deepl_client.rephrase_text(\"A rainbouw has seven colours.\", target_lang=\"EN-US\")\nprint(result.text)\n```\n\nAdditionally, you can optionally specify a style OR a tone (not both at once) that the\nimprovement should be in. The following styles are supported (`default` will be used if\nnothing is selected):\n\n- `academic`\n- `business`\n- `casual`\n- `default`\n- `simple`\n\nThe following tones are supported (`default` will be used if nothing is selected):\n\n- `confident`\n- `default`\n- `diplomatic`\n- `enthusiastic`\n- `friendly`\n\nYou can also prefix any non-default style or tone with `prefer_` (`prefer_academic`, etc.),\nin which case the style/tone will only be applied if the language supports it. If you do not\nuse `prefer_`, requests with `target_lang`s or detected languages that do not support\nstyles and tones will fail. The current list of supported languages can be found in our\n[API documentation][api-docs]. We plan to also expose this information via an API endpoint\nin the future.\n\nYou can use the predefined constants in the library to use a style:\n\n```python\nresult = deepl_client.rephrase_text(\n    \"A rainbouw has seven colours.\", target_lang=\"EN-US\", style=WritingStyle.BUSINESS.value\n)\nprint(result.text)\n```\n\n### Translating documents\n\nTo translate documents, you may call either `translate_document()` using file IO\nobjects, or `translate_document_from_filepath()` using file paths. For both\nfunctions, the first and second arguments correspond to the input and output\nfiles respectively.\n\nJust as for the `translate_text()` function, the `source_lang` and\n`target_lang` arguments specify the source and target language codes.\n\nThere are additional optional arguments to control translation, see\n[Document translation options](#document-translation-options) below.\n\n```python\n# Translate a formal document from English to German\ninput_path = \"/path/to/Instruction Manual.docx\"\noutput_path = \"/path/to/Bedienungsanleitung.docx\"\ntry:\n    # Using translate_document_from_filepath() with file paths \n    deepl_client.translate_document_from_filepath(\n        input_path,\n        output_path,\n        target_lang=\"DE\",\n        formality=\"more\"\n    )\n\n    # Alternatively you can use translate_document() with file IO objects\n    with open(input_path, \"rb\") as in_file, open(output_path, \"wb\") as out_file:\n        deepl_client.translate_document(\n            in_file,\n            out_file,\n            target_lang=\"DE\",\n            formality=\"more\"\n        )\n\nexcept deepl.DocumentTranslationException as error:\n    # If an error occurs during document translation after the document was\n    # already uploaded, a DocumentTranslationException is raised. The\n    # document_handle property contains the document handle that may be used to\n    # later retrieve the document from the server, or contact DeepL support.\n    doc_id = error.document_handle.id\n    doc_key = error.document_handle.key\n    print(f\"Error after uploading ${error}, id: ${doc_id} key: ${doc_key}\")\nexcept deepl.DeepLException as error:\n    # Errors during upload raise a DeepLException\n    print(error)\n```\n\n`translate_document()` and `translate_document_from_filepath()` are convenience\nfunctions that wrap multiple API calls: uploading, polling status until the\ntranslation is complete, and downloading. If your application needs to execute\nthese steps individually, you can instead use the following functions directly:\n\n- `translate_document_upload()`,\n- `translate_document_get_status()` (or\n  `translate_document_wait_until_done()`), and\n- `translate_document_download()`\n\n#### Document translation options\n\nIn addition to the input file, output file, `source_lang` and `target_lang`\narguments, the available `translate_document()` and\n`translate_document_from_filepath()` arguments are:\n\n- `formality`: same as in [Text translation options](#text-translation-options).\n- `glossary`: same as in [Text translation options](#text-translation-options).\n- `output_format`: (`translate_document()` only)\n  file extension of desired format of translated file, for example: `'pdf'`. If\n  unspecified, by default the translated file will be in the same format as the\n  input file. \n\n### Glossaries\n\nGlossaries allow you to customize your translations using user-defined terms.\nMultiple glossaries can be stored with your account, each with a user-specified\nname and a uniquely-assigned ID.\n\n#### Creating a glossary\n\nYou can create a glossary with your desired terms and name using\n`create_glossary()`. Each glossary applies to a single source-target language\npair. Note: Glossaries are only supported for some language pairs, see\n[Listing available glossary languages](#listing-available-glossary-languages)\nfor more information. The entries should be specified as a dictionary.\n\nIf successful, the glossary is created and stored with your DeepL account, and\na `GlossaryInfo` object is returned including the ID, name, languages and entry\ncount.\n\n```python\n# Create an English to German glossary with two terms:\nentries = {\"artist\": \"Maler\", \"prize\": \"Gewinn\"}\nmy_glossary = deepl_client.create_glossary(\n    \"My glossary\",\n    source_lang=\"EN\",\n    target_lang=\"DE\",\n    entries=entries,\n)\nprint(\n    f\"Created '{my_glossary.name}' ({my_glossary.glossary_id}) \"\n    f\"{my_glossary.source_lang}-\u003e{my_glossary.target_lang} \"\n    f\"containing {my_glossary.entry_count} entries\"\n)\n# Example: Created 'My glossary' (559192ed-8e23-...) EN-\u003eDE containing 2 entries\n```\n\nYou can also upload a glossary downloaded from the DeepL website using\n`create_glossary_from_csv()`. Instead of supplying the entries as a dictionary,\nspecify the CSV data as `csv_data` either as a file-like object or string or\nbytes containing file content:\n\n```python\n# Open the CSV file assuming UTF-8 encoding. If your file contains a BOM,\n# consider using encoding='utf-8-sig' instead.\nwith open('/path/to/glossary_file.csv', 'r',  encoding='utf-8') as csv_file:\n    csv_data = csv_file.read()  # Read the file contents as a string\n    my_csv_glossary = deepl_client.create_glossary_from_csv(\n        \"CSV glossary\",\n        source_lang=\"EN\",\n        target_lang=\"DE\",\n        csv_data=csv_data,\n    )\n```\n\nThe [API documentation][api-docs-csv-format] explains the expected CSV format in\ndetail.\n\n#### Getting, listing and deleting stored glossaries\n\nFunctions to get, list, and delete stored glossaries are also provided:\n\n- `get_glossary()` takes a glossary ID and returns a `GlossaryInfo` object for a\n  stored glossary, or raises an exception if no such glossary is found.\n- `list_glossaries()` returns a list of `GlossaryInfo` objects corresponding to\n  all of your stored glossaries.\n- `delete_glossary()` takes a glossary ID or `GlossaryInfo` object and deletes\n  the stored glossary from the server, or raises an exception if no such\n  glossary is found.\n\n```python\n# Retrieve a stored glossary using the ID\nglossary_id = \"559192ed-8e23-...\"\nmy_glossary = deepl_client.get_glossary(glossary_id)\n\n# Find and delete glossaries named 'Old glossary'\nglossaries = deepl_client.list_glossaries()\nfor glossary in glossaries:\n    if glossary.name == \"Old glossary\":\n        deepl_client.delete_glossary(glossary)\n```\n\n#### Listing entries in a stored glossary\n\nThe `GlossaryInfo` object does not contain the glossary entries, but instead\nonly the number of entries in the `entry_count` property.\n\nTo list the entries contained within a stored glossary, use\n`get_glossary_entries()` providing either the `GlossaryInfo` object or glossary\nID:\n\n```python\nentries = deepl_client.get_glossary_entries(my_glossary)\nprint(entries)  # \"{'artist': 'Maler', 'prize': 'Gewinn'}\"\n```\n\n#### Using a stored glossary\n\nYou can use a stored glossary for text translation by setting the `glossary`\nargument to either the glossary ID or `GlossaryInfo` object. You must also\nspecify the `source_lang` argument (it is required when using a glossary):\n\n```python\ntext = \"The artist was awarded a prize.\"\nwith_glossary = deepl_client.translate_text(\n    text, source_lang=\"EN\", target_lang=\"DE\", glossary=my_glossary,\n)\nprint(with_glossary)  # \"Der Maler wurde mit einem Gewinn ausgezeichnet.\"\n\n# For comparison, the result without a glossary:\nwithout_glossary = deepl_client.translate_text(text, target_lang=\"DE\")\nprint(without_glossary)  # \"Der Künstler wurde mit einem Preis ausgezeichnet.\"\n```\n\nUsing a stored glossary for document translation is the same: set the `glossary`\nargument and specify the `source_lang` argument:\n\n```python\ndeepl_client.translate_document(\n    in_file, out_file, source_lang=\"EN\", target_lang=\"DE\", glossary=my_glossary,\n)\n```\n\nThe `translate_document()`, `translate_document_from_filepath()` and\n`translate_document_upload()` functions all support the `glossary` argument.\n\n### Checking account usage\n\nTo check account usage, use the `get_usage()` function.\n\nThe returned `Usage` object contains three usage subtypes: `character`,\n`document` and `team_document`. Depending on your account type, some usage\nsubtypes may be invalid; this can be checked using the `valid` property. For API\naccounts:\n\n- `usage.character.valid` is `True`,\n- `usage.document.valid` and `usage.team_document.valid` are `False`.\n\nEach usage subtype (if valid) has `count` and `limit` properties giving the\namount used and maximum amount respectively, and the `limit_reached` property\nthat checks if the usage has reached the limit. The top level `Usage` object has\nthe `any_limit_reached` property to check all usage subtypes.\n\n```python\nusage = deepl_client.get_usage()\nif usage.any_limit_reached:\n    print('Translation limit reached.')\nif usage.character.valid:\n    print(\n        f\"Character usage: {usage.character.count} of {usage.character.limit}\")\nif usage.document.valid:\n    print(f\"Document usage: {usage.document.count} of {usage.document.limit}\")\n```\n\n### Listing available languages\n\nYou can request the list of languages supported by DeepL for text and documents\nusing the `get_source_languages()` and `get_target_languages()` functions. They\nboth return a list of `Language` objects.\n\nThe `name` property gives the name of the language in English, and the `code`\nproperty gives the language code. The `supports_formality` property only appears\nfor target languages, and indicates whether the target language supports the\noptional `formality` parameter.\n\n```python\nprint(\"Source languages:\")\nfor language in deepl_client.get_source_languages():\n    print(f\"{language.name} ({language.code})\")  # Example: \"German (DE)\"\n\nprint(\"Target languages:\")\nfor language in deepl_client.get_target_languages():\n    if language.supports_formality:\n        print(f\"{language.name} ({language.code}) supports formality\")\n        # Example: \"Italian (IT) supports formality\"\n    else:\n        print(f\"{language.name} ({language.code})\")\n        # Example: \"Lithuanian (LT)\"\n```\n\n#### Listing available glossary languages\n\nGlossaries are supported for a subset of language pairs. To retrieve those\nlanguages use the `get_glossary_languages()` function, which returns an array\nof `GlossaryLanguagePair` objects. Each has `source_lang` and `target_lang`\nproperties indicating that that pair of language codes is supported.\n\n```python\nglossary_languages = deepl_client.get_glossary_languages()\nfor language_pair in glossary_languages:\n    print(f\"{language_pair.source_lang} to {language_pair.target_lang}\")\n    # Example: \"EN to DE\", \"DE to EN\", etc.\n```\n\nYou can also find the list of supported glossary language pairs in the\n[API documentation][api-docs-glossary-lang-list].\n\nNote that glossaries work for all target regional-variants: a glossary for the\ntarget language English (`\"EN\"`) supports translations to both American English\n(`\"EN-US\"`) and British English (`\"EN-GB\"`).\n\n### Writing a Plugin\n\nIf you use this library in an application, please identify the application with\n`deepl.DeepLClient.set_app_info`, which needs the name and version of the app:\n\n```python\ndeepl_client = deepl.DeepLClient(...).set_app_info(\"sample_python_plugin\", \"1.0.2\")\n```\n\nThis information is passed along when the library makes calls to the DeepL API.\nBoth name and version are required. Please note that setting the `User-Agent` header\nvia `deepl.http_client.user_agent` will override this setting, if you need to use this,\nplease manually identify your Application in the `User-Agent` header.\n\n### Exceptions\n\nAll module functions may raise `deepl.DeepLException` or one of its subclasses.\nIf invalid arguments are provided, they may raise the standard exceptions\n`ValueError` and `TypeError`.\n\n### Configuration\n\n#### Logging\n\nLogging can be enabled to see the HTTP requests sent and responses received by\nthe library. Enable and control logging using Python's `logging` module, for\nexample:\n\n```python\nimport logging\n\nlogging.basicConfig()\nlogging.getLogger('deepl').setLevel(logging.DEBUG)\n```\n\n#### Server URL configuration\n\nYou can override the URL of the DeepL API by specifying the `server_url`\nargument when constructing a `deepl.DeepLClient`. This may be useful for testing\npurposes. You **do not** need to specify the URL to distinguish API Free and API\nPro accounts, the library selects the correct URL automatically.\n\n```python\nserver_url = \"http://user:pass@localhost:3000\"\ndeepl_client = deepl.DeepLClient(..., server_url=server_url)\n```\n\n#### Proxy configuration\n\nYou can configure a proxy by specifying the `proxy` argument when constructing a\n`deepl.DeepLClient`:\n\n```python\nproxy = \"http://user:pass@10.10.1.10:3128\"\ndeepl_client = deepl.DeepLClient(..., proxy=proxy)\n```\n\nThe proxy argument is passed to the underlying `requests` session, see the\n[documentation for requests][requests-proxy-docs]; a dictionary of schemes to\nproxy URLs is also accepted.\n\n#### Override SSL verification\n\nYou can control how `requests` performs SSL verification by specifying the \n`verify_ssl` option when constructing a `deepl.DeepLClient`, for example to\ndisable SSL certificate verification:\n\n```python\ndeepl_client = deepl.DeepLClient(..., verify_ssl=False)\n```\n\nThis option is passed to the underlying `requests` session as the `verify`\noption, see the [documentation for requests][requests-verify-ssl-docs].\n\n#### Configure automatic retries\n\nThis SDK will automatically retry failed HTTP requests (if the failures could\nbe transient, e.g. a HTTP 429 status code). This behaviour can be configured\nin `http_client.py`, for example by default the number of retries is 5. This\ncan be changed to 3 as follows:\n\n```python\nimport deepl\n\ndeepl.http_client.max_network_retries = 3\nc = deepl.DeepLClient(...)\nc.translate_text(...)\n```\n\nYou can configure the timeout `min_connection_timeout` the same way, as well\nas set a custom `user_agent`, see the next section.\n\n#### Anonymous platform information\n\nBy default, we send some basic information about the platform the client library is running on with each request, see [here for an explanation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). This data is completely anonymous and only used to improve our product, not track any individual users. If you do not wish to send this data, you can opt-out when creating your `deepl.DeepLClient` object by setting the `send_platform_info` flag like so:\n\n```python\ndeepl_client = deepl.DeepLClient(..., send_platform_info=False)\n```\n\nYou can also customize the `user_agent` by setting its value explicitly before constructing your `deepl.DeepLClient` object.\n\n```python\ndeepl.http_client.user_agent = 'my custom user agent'\ndeepl_client = deepl.DeepLClient(os.environ[\"DEEPL_AUTH_KEY\"])\n```\n\n## Command Line Interface\n\nThe library can be run on the command line supporting all API functions. Use the\n`--help` option for usage information:\n\n```shell\npython3 -m deepl --help\n```\n\nThe CLI requires your DeepL authentication key specified either as the\n`DEEPL_AUTH_KEY` environment variable, through the `keyring` module, or\nusing the `--auth-key` option, for example:\n\n```shell\npython3 -m deepl --auth-key=YOUR_AUTH_KEY usage\n```\n\nNote that the `--auth-key` argument must appear *before* the command argument.\nTo use the [keyring](https://pypi.org/project/keyring/) module, set the \n*DEEPL_AUTH_KEY* field in the service *deepl* to your API key.\nThe recognized commands are:\n\n| Command   | Description                                            |\n| :-------- | :----------------------------------------------------- |\n| text      | translate text(s)                                      |\n| document  | translate document(s)                                  |\n| usage     | print usage information for the current billing period |\n| languages | print available languages                              |\n| glossary  | create, list, and remove glossaries                    |\n\nFor example, to translate text:\n\n```shell\npython3 -m deepl --auth-key=YOUR_AUTH_KEY text --to=DE \"Text to be translated.\"\n```\n\nWrap text arguments in quotes to prevent the shell from splitting sentences into\nwords.\n\n## Issues\n\nIf you experience problems using the library, or would like to request a new\nfeature, please open an [issue][issues].\n\n## Development\n\nWe welcome Pull Requests, please read the\n[contributing guidelines](CONTRIBUTING.md).\n\n### Tests\n\nExecute the tests using `pytest`. The tests communicate with the DeepL API using\nthe auth key defined by the `DEEPL_AUTH_KEY` environment variable.\n\nBe aware that the tests make DeepL API requests that contribute toward your API\nusage.\n\nThe test suite may instead be configured to communicate with the mock-server\nprovided by [deepl-mock][deepl-mock]. Although most test cases work for either,\nsome test cases work only with the DeepL API or the mock-server and will be\notherwise skipped. The test cases that require the mock-server trigger server\nerrors and test the client error-handling. To execute the tests using\ndeepl-mock, run it in another terminal while executing the tests. Execute the\ntests using `pytest` with the `DEEPL_MOCK_SERVER_PORT` and `DEEPL_SERVER_URL`\nenvironment variables defined referring to the mock-server.\n\n[api-docs]: https://www.deepl.com/docs-api?utm_source=github\u0026utm_medium=github-python-readme\n\n[api-docs-csv-format]: https://www.deepl.com/docs-api/managing-glossaries/supported-glossary-formats/?utm_source=github\u0026utm_medium=github-python-readme\n\n[api-docs-xml-handling]: https://www.deepl.com/docs-api/handling-xml/?utm_source=github\u0026utm_medium=github-python-readme\n\n[api-docs-context-param]: https://www.deepl.com/docs-api/translating-text/?utm_source=github\u0026utm_medium=github-python-readme\n\n[api-docs-lang-list]: https://www.deepl.com/docs-api/translating-text/?utm_source=github\u0026utm_medium=github-python-readme\n\n[api-docs-glossary-lang-list]: https://www.deepl.com/docs-api/managing-glossaries/?utm_source=github\u0026utm_medium=github-python-readme\n\n[bug-report-ubuntu-2204]: https://bugs.launchpad.net/ubuntu/+source/poetry/+bug/1958227\n\n[create-account]: https://www.deepl.com/pro?utm_source=github\u0026utm_medium=github-python-readme#developer\n\n[deepl-mock]: https://www.github.com/DeepLcom/deepl-mock\n\n[issues]: https://www.github.com/DeepLcom/deepl-python/issues\n\n[pypi-project]: https://pypi.org/project/deepl/\n\n[pro-account]: https://www.deepl.com/pro-account/?utm_source=github\u0026utm_medium=github-python-readme\n\n[python-version-list]: https://devguide.python.org/versions/\n\n[requests-proxy-docs]: https://docs.python-requests.org/en/latest/user/advanced/#proxies\n\n[requests-verify-ssl-docs]: https://docs.python-requests.org/en/latest/user/advanced/#ssl-cert-verification\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeeplcom%2Fdeepl-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeeplcom%2Fdeepl-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeeplcom%2Fdeepl-python/lists"}