v1.33.0

TL;DR: new APIs in this release: the Admin API, spoken terms and style profiles.
Translation memories, style rules and multilingual glossaries gained many options and fixes.
Read Changed and Deprecated before upgrading; no public API is removed in this release.

Added

• Added the headers option to the Translator, DeepLClient and
  DeepLAdminClient constructors: extra HTTP headers sent with every request
  to the DeepL API. A header replaces the library's header of the same name,
  including User-Agent and Authorization; Content-Type,
  Content-Length, Transfer-Encoding, Host and an Accept the library
  sets for a call keep the library's value. Translation memory storage URLs
  get only the User-Agent.
• Added the app_info option, an AppInfo(app_name, app_version), to the
  Translator, DeepLClient and DeepLAdminClient constructors, the same as
  calling set_app_info().
• Added NotFoundException, raised for HTTP 404 on every endpoint.
  GlossaryNotFoundException is now its subclass.
• Added is_free_account_auth_key(), which replaces auth_key_is_free_account().
• Added the extra_body_parameters option to create_style_rule(),
  update_style_rule_name(), update_style_rule_configured_rules(),
  create_style_rule_custom_instruction() and
  update_style_rule_custom_instruction().
• get_style_rule_custom_instruction(),
  update_style_rule_custom_instruction() and
  delete_style_rule_custom_instruction() accept a CustomInstruction object
  as instruction_id, as well as an ID string.
• Added the max_retries and timeout_s options to the Translator,
  DeepLClient and DeepLAdminClient constructors, to set the maximum number
  of retries and the minimum per-attempt timeout in seconds for each client.
• Added the style_profile option to translate_text() and the document
  translation functions (translate_document(),
  translate_document_from_filepath(), translate_document_upload()) to
  translate with a style profile, as a style profile ID or StyleProfile
  object. The CLI accepts it as --style-profile-id.
• Added the DeepLAdminClient class for the Admin API. It must be created with
  an admin API key and supports managing developer keys
  (create_developer_key(), list_developer_keys(),
  deactivate_developer_key(), rename_developer_key(),
  set_developer_key_usage_limits()) and retrieving usage analytics
  (get_usage_analytics(), get_custom_tag_usage_analytics()) with
  the result types DeveloperKey, DeveloperKeyUsageLimits,
  AdminUsageReport, AdminUsageBreakdown, KeyUsage, CustomTagUsageReport,
  CustomTagUsage and CustomTagUsageBreakdown, and the request options
  DeveloperKeyUsageLimitsUpdate, AdminUsageGroupBy and
  CustomTagUsageAggregateBy.
  The developer key methods that send a request body accept
  extra_body_parameters.
  create_developer_key() is retried only when the request was not sent:
  after HTTP 429, a DNS resolution failure, a refused connection or a connect
  timeout. AdminUsageReport.total_usage,
  AdminUsageBreakdown.speech_to_speech_minutes and
  CustomTagUsageBreakdown.speech_to_speech_minutes are None when the
  report does not contain them, and a response without usage_report or
  custom_tag_usage_report raises DeepLException.
• Added get_languages_for_resource() method to the DeepLClient class to
  retrieve the languages supported by a resource, with per-feature support
  information, via the /v3/languages endpoint. Resources are given as
  LanguageResourceName values or strings; results are LanguageSupport
  objects. Malformed responses raise DeepLException.
• Added get_language_resources() method to the DeepLClient class to
  retrieve the API resources and their features via the
  /v3/languages/resources endpoint. Results are returned as
  LanguageResource and ResourceFeature objects; needs_source_support
  and needs_target_support are False when the API omits them.
• Added Language constants for the target variants de-CH, de-DE,
  es-ES, fr-CA, and fr-FR.
• Added the enable_watermark option to translate_document(),
  translate_document_upload() and translate_document_from_filepath(). Set
  it to True to add a "Translated by DeepL" watermark to docx and pdf
  output.
• Added the API Pro usage fields to Usage: api_key_character,
  speech_to_text_minutes and speech_to_speech_minutes (as
  Optional[Usage.Detail]), start_time and end_time (the billing period),
  and products, a list of Usage.Product objects with per-product usage.
  They are None when the response does not contain them; products entries
  that are not JSON objects are skipped.
• Added the Spoken Terms API (/v3/spoken-terms) to the DeepLClient class:
  create_spoken_terms(), list_spoken_terms(), get_spoken_terms(),
  update_spoken_terms(), get_spoken_terms_entries(),
  replace_spoken_terms_list(), delete_spoken_terms() and
  delete_spoken_terms_list(), with the SpokenTerms, SpokenTermsList and
  SpokenTermsEntries types. create_spoken_terms(), update_spoken_terms()
  and replace_spoken_terms_list() accept extra_body_parameters. Collection
  IDs are URL-encoded in the request path, terms are stripped of leading and
  trailing whitespace before they are validated and sent, and a malformed
  response raises DeepLException.
• Added the style profile API (/v3/style_profiles) to the DeepLClient
  class: list_style_profiles(), create_style_profile(),
  get_style_profile(), update_style_profile() and
  delete_style_profile(), with the StyleProfile type. The glossary_ids,
  style_rule_ids and translation_memory_ids options of
  create_style_profile() and update_style_profile() accept IDs or
  GlossaryInfo, MultilingualGlossaryInfo, StyleRuleInfo and
  TranslationMemoryInfo objects, and both functions accept
  extra_body_parameters. A style profile response that is not a JSON object,
  or lacks a valid style_profile_id, name, creation_time or
  updated_time, raises DeepLException.
• Added the TagHandlingMode (HTML, XML) and TagHandlingVersion (V1,
  V2) enums. The tag_handling and tag_handling_version options of
  translate_text() accept them as well as strings.
• Added tag_handling_version to TextResult: the tag handling version the
  API used, or None when the response does not contain it.
• translate_text() accepts source_lang and target_lang positionally after
  the text, for example translate_text("Hello", None, "DE"). Keyword use is
  unchanged; omitting target_lang still raises TypeError.
• Added the document_id property to DocumentStatus, read from the status
  response of translate_document_get_status() (falling back to the handle's
  document ID).
• translate_document(), translate_document_from_filepath() and
  translate_document_upload() now also accept source_lang and
  target_lang as positional arguments after the input (and output)
  arguments, for example translate_document_upload(file, "EN", "DE").
  Keyword use is unchanged.
• Added the writing_style and extra_body_parameters options to
  rephrase_text(), and the extra_body_parameters option to
  correct_text(). writing_style and tone accept a WritingStyle or
  WritingTone member or a string.
• Added update_multilingual_glossary() to the DeepLClient class to rename a
  multilingual glossary and/or merge dictionaries into it in one request,
  sending only the options that are set.
• Added get_multilingual_glossary_dictionary_entries() to the DeepLClient
  class, returning the MultilingualGlossaryDictionaryEntries of one dictionary
  and raising GlossaryNotFoundException if the glossary has none for the
  language pair.
• Added the extra_body_parameters option to create_multilingual_glossary(),
  create_multilingual_glossary_from_csv(),
  update_multilingual_glossary_name(),
  update_multilingual_glossary_dictionary(),
  update_multilingual_glossary_dictionary_from_csv(),
  replace_multilingual_glossary_dictionary() and
  replace_multilingual_glossary_dictionary_from_csv().
• get_multilingual_glossary() accepts a MultilingualGlossaryInfo object, as
  glossary, besides a glossary ID.
• Added the argument names dictionaries (create_multilingual_glossary()),
  dictionary (update_multilingual_glossary_dictionary(),
  replace_multilingual_glossary_dictionary()), csv (the
  *_multilingual_glossary*_from_csv() functions) and glossary
  (get_multilingual_glossary()).
• MultilingualGlossaryInfo, MultilingualGlossaryDictionaryInfo and
  MultilingualGlossaryDictionaryEntries are exported from the deepl package.
• Added MultilingualGlossaryDictionaryInfo.to_json().
• Added the content_type and extra_body_parameters options to
  import_translation_memory_from_filepath(), and the extra_body_parameters
  option to create_translation_memory_import(). content_type is declared
  when creating the import job and sent with the upload; extra body parameters
  are added to the request that creates the import job and replace keys of
  the same name.
• Added the TranslationMemoryJobStatus enum. TranslationMemoryJob.status
  and TranslationMemoryJobResult.status now return its members for the
  statuses awaiting_input, processing, completed, failed and
  expired, and the plain string for any other value. Members are strings
  that compare equal to the API value, so existing comparisons with strings
  and the TranslationMemoryJobResult.STATUS_* constants keep working.
• Added the content parameter name to upload_translation_memory_file()
  for the file content, replacing input_file. Positional calls are
  unaffected.
• DocumentTranslationException accepts should_retry and
  http_status_code. translate_document() and
  translate_document_from_filepath() copy both from the underlying
  DeepLException; before they were always False and None.

Changed

• With timeout_s, wait_until_translation_memory_job_done() now cuts its
  last sleep short; previously it could run up to 5 seconds past the timeout.
• import_translation_memory_from_filepath() now reads the file and
  export_translation_memory_to_filepath() now checks the output path before
  creating the job, so these OSErrors are raised without creating a job;
  previously the job was created first.
• translate_text() now accepts glossary and glossary_ids without
  source_lang, and DeepL uses the glossary dictionary for the detected
  language pair; previously it raised ValueError. Document translation with a
  glossary still requires source_lang.
• A path in server_url is now kept; previously the last path segment was
  dropped.
• HTTP 401 responses now raise AuthorizationException; previously
  DeepLException.
• Creating a Translator now emits a DeprecationWarning; previously it did
  not.
• HTTP 404 responses raise NotFoundException instead of DeepLException
  (glossary functions keep raising GlossaryNotFoundException, now a
  subclass of NotFoundException).
• The User-Agent platform information now ends with python/<version>;
  previously it also included the requests version.
• Target languages EN and PT are now sent to the API, which translates them
  into EN-US and PT-PT; previously they were rejected client-side.
• get_source_languages(), get_target_languages(), and
  get_glossary_languages() now use the /v3/languages endpoint
  internally instead of the deprecated /v2/languages and
  /v2/glossary-language-pairs endpoints. Public signatures and return
  types are unchanged, but the returned language lists may now include
  additional languages.
• The default chunk_size of translate_document_download() and
  download_translation_memory_export() is now 64 KiB instead of 1 byte, so
  downloads into output_file no longer write one byte per call. The written
  content is unchanged; an explicit chunk_size still applies.
• DocumentStatus.status is now typed Union[DocumentStatus.Status, str]: a
  status value the API returns that this version does not know is kept as a
  string instead of raising ValueError. Type-checked code that reads
  status.status.value may need an isinstance(..., DocumentStatus.Status)
  guard; str(status) returns the status string in both cases.

Deprecated

• Translator is deprecated in favour of DeepLClient, which supports all its
  functions, and will be removed in the next major version.
• GlossaryNotFoundException is deprecated, catch NotFoundException instead.
  It will be removed in the next major version.
• auth_key_is_free_account() is deprecated, use is_free_account_auth_key().
  Calling it emits a DeprecationWarning.
• The module-level setting deepl.http_client.user_agent is deprecated in
  favour of a User-Agent entry in the headers option, and will be removed in
  the next major version. Assigning it emits a DeprecationWarning.
• Calling translate_document_download() or
  download_translation_memory_export() without output_file now emits a
  DeprecationWarning. It still returns the streaming requests.Response; in
  the next major version output_file will be required and both methods will
  return None.
• Passing skip_language_check to Translator() or DeepLClient(), or
  skip_cache to get_source_languages() or get_target_languages(), now
  emits a DeprecationWarning. Both parameters have no effect and will be
  removed in the next major version. Their defaults changed from False to
  None; passing False explicitly also warns.
• The module-level settings deepl.http_client.max_network_retries and
  deepl.http_client.min_connection_timeout are deprecated in favour of the
  max_retries and timeout_s client options, and will be removed in the
  next major version. They still apply to clients created without these
  options. Assigning either setting emits a DeprecationWarning.
• The language code constants of Language (Language.GERMAN,
  Language.ENGLISH_AMERICAN, ...) are deprecated and will be removed in the
  next major version. Pass language codes as strings, for example "de", or
  use the codes returned by get_source_languages() and
  get_target_languages(). The constants keep working and emit no warning.
• The style keyword of rephrase_text() is deprecated in favour of
  writing_style and emits a DeprecationWarning. It keeps working; if both
  are given, writing_style is used.
• get_multilingual_glossary_entries() is deprecated, use
  get_multilingual_glossary_dictionary_entries().
• The argument names glossary_dicts, glossary_dict, csv_data and
  glossary_id of the multilingual glossary functions are deprecated, use
  dictionaries, dictionary, csv and glossary.
• The input_file keyword of upload_translation_memory_file() is
  deprecated in favour of content and will be removed in the next major
  version. Passing it emits a DeprecationWarning.
• SplitSentences.DEFAULT is deprecated, use SplitSentences.ALL, which it is
  an alias of.
• translate_text_with_glossary() is deprecated, use translate_text() with
  the glossary parameter. Calling it emits a DeprecationWarning.

Fixed

• A glossary CSV row without a target term now raises a ValueError naming
  the row; previously a bare IndexError (it is still an IndexError).
• A connection that is reset or breaks off while a non-streamed response body
  is read is now retried like other connection failures, and raises
  ConnectionException with should_retry True once retries are used up.
  create_developer_key() is still not retried after it.
• translate_document_download() now streams the translated document to
  output_file in chunks, instead of first reading the whole document into
  memory for the debug log.
• A connection reset or timeout while translate_document_download() or
  download_translation_memory_export() reads the downloaded file now raises
  ConnectionException, instead of a requests exception.
• HTTP 3xx responses that are not followed as redirects (e.g. 300, 304, or a
  redirect without Location) now raise DeepLException with
  http_status_code, instead of being parsed as a successful response.
• TLS and certificate failures, and proxy failures (including a failure to
  connect to the proxy), are no longer retried and raise ConnectionException
  with should_retry False.
• Query string values encode a space as %20 instead of +.
• Fixed errors from the pre-signed translation memory upload and download URLs
  reporting should_retry as [secure] for HTTP 429 and 5xx, and dropping the
  response body of a failed download from the message.
• A failed export_translation_memory_to_filepath() no longer leaves a
  partially written file behind.
• DeepLException.should_retry is now True for every HTTP 5xx error. It was
  False for all of them except 503, although they are retried.
• An error response whose message or detail is not a string (a number,
  object or null) no longer raises TypeError; the value is included as
  JSON, null is left out.
• Leading and trailing whitespace in the authentication key is removed before
  it is sent and before the :fx check that selects the API Free server. A
  key of only whitespace is rejected with ValueError.
• Fixed translate_text() raising TypeError when a translation in the
  response has no billed_characters. TextResult.billed_characters is now
  None in that case.
• Fixed translate_text() raising IndexError when the response holds fewer
  translations than texts sent. It now raises DeepLException.
• Fixed translate_document_get_status() raising ValueError and
  translate_document_wait_until_done() stopping when the API returns a
  document status this version does not know. DocumentStatus.status keeps
  such a status as a string, and polling continues.
• Fixed translate_document() and translate_document_from_filepath()
  sending formality=default when formality was not set. It is now sent
  only when given.
• Fixed translate_document_get_status() and translate_document_download()
  not URL-encoding the document ID in the request path.
• Fixed translate_document_upload() returning an empty DocumentHandle when
  the response lacks document_id or document_key, and raising
  AttributeError when the response body is not a JSON object. Both now
  raise DeepLException.
• Fixed the type annotation of DocumentStatus.error_message, which is a
  string, not an integer.
• Fixed the style rule functions inserting the style rule ID and custom
  instruction ID into the request path without escaping them, so an ID
  containing /, ? or # addressed a different resource.
• Fixed the style rule functions raising a raw KeyError, ValueError,
  TypeError or AttributeError on a malformed StyleRuleInfo or
  CustomInstruction response. They now raise DeepLException.
• Fixed the DeprecationWarning messages of Usage.Detail.limit_exceeded and
  Usage.any_limit_exceeded, which named the replacement instead of the
  deprecated property. They now read "limit_exceeded is deprecated, use
  limit_reached" and "any_limit_exceeded is deprecated, use any_limit_reached".
• Fixed the Language.ENGLISH and Language.PORTUGUESE comments that
  claimed they are only usable as source languages.
• Fixed create_glossary_from_csv() failing with "Object of type bytes is not
  JSON serializable" when the CSV data is given as bytes or as a file opened in
  binary mode.
• Fixed the rephrase CLI command always failing with an unexpected keyword
  argument error. --show-detected-source now prints the detected source
  language of each text.
• Fixed the translate CLI alias of the text command failing with
  'action_translate'.
• Fixed the extra_body_parameters documentation, which claimed that entries
  do not overwrite request fields set by the library. They do, since 1.24.0.
• Fixed MultilingualGlossaryInfo.to_json() raising TypeError when called on
  an instance.
• Fixed rephrase_text() and correct_text() failing with "Object of type
  ... is not JSON serializable" when target_lang is a Language object or
  the style or tone is a WritingStyle or WritingTone member. The value is
  now sent as its string code.
• rephrase_text() and correct_text() now raise DeepLException when the
  response has no improvements list, fewer improvements than input texts, or
  an improvement without text. Before, this raised IndexError or
  AttributeError, or silently returned a shorter list.
• get_source_languages() and get_target_languages() now raise
  DeepLException when the response is not a list (they returned an empty
  list before) or a language in it is missing its code or name (instead of a
  raw KeyError, AttributeError or TypeError). A null features field is
  treated as no features.
• Glossary IDs are URL-encoded in /v3/glossaries request paths, and the
  language pair in the query of get_multilingual_glossary_entries() and
  delete_multilingual_glossary_dictionary() is URL-encoded.
  delete_multilingual_glossary_dictionary() now also strips regional variants
  (EN-GB becomes EN), like the other multilingual glossary functions.
• A malformed multilingual glossary response raises DeepLException instead of
  a raw KeyError, TypeError or ValueError.
• MultilingualGlossaryInfo.to_json() returns a JSON-serialisable dictionary:
  creation_time as an ISO 8601 string and dictionaries as dictionaries.
• Fixed the translation memory functions sending translation memory and job
  IDs unencoded in the request path. IDs are now URL-encoded, so characters
  such as /, ? or spaces no longer change the requested URL.
• Fixed the translation memory functions raising a raw KeyError,
  TypeError or AttributeError when the API returns a malformed response.
  They now raise DeepLException. list_translation_memories() also raises
  DeepLException for a non-JSON response instead of returning an empty list.
• Fixed get_usage() returning a Usage with every value invalid when the
  response body is not a JSON object. It now raises DeepLException.
• translate_document_download() now raises errors with the API's error
  message. Before, a 400, 404 or 456 response raised without it, and other
  statuses reported content: <file>.
• translate_document_wait_until_done() (and translate_document() with
  timeout_s) shortens its last wait to the timeout, so it no longer runs up
  to 5 seconds past timeout_s.