feat: Add DeepLClient class for write implementation

Author: daniel-jones-dev

deepl/__init__.py

@@ -6,6 +6,8 @@
 
 __author__ = "DeepL SE <python-api@deepl.com>"
 
+from .deepl_client import DeepLClient
+
 from .exceptions import (  # noqa
     AuthorizationException,
     ConnectionException,
@@ -42,6 +44,7 @@
 __all__ = [
     "__version__",
     "__author__",
+    "DeepLClient",
     "DocumentHandle",
     "DocumentStatus",
     "Formality",

deepl/__main__.py

@@ -113,6 +113,19 @@ def action_text(
         print(output.text)
 
 
+def action_rephrase(
+    translator: deepl.Translator,
+    **kwargs,
+):
+    """Action function for the rephrase command."""
+    improvement = translator.rephrase_text(**kwargs)
+    output_list = (
+        improvement if isinstance(improvement, List) else [improvement]
+    )
+    for output in output_list:
+        print(output.text)
+
+
 def action_glossary(
     translator: deepl.Translator,
     subcommand: str,
@@ -311,7 +324,10 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
 
     # create the parser for the "text" command
     parser_text = subparsers.add_parser(
-        "text", help="translate text(s)", description="translate text(s)"
+        "text",
+        help="translate text(s)",
+        description="translate text(s)",
+        aliases=["translate"],
     )
     add_common_arguments(parser_text)
     parser_text.add_argument(
@@ -410,6 +426,31 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
         help="specify tags containing text that should not be translated",
     )
 
+    # create the parser for the "rephrase" command
+    parser_rephrase = subparsers.add_parser(
+        "rephrase", help="rephrase text(s)", description="rephrase text(s)"
+    )
+    parser_rephrase.add_argument(
+        "--to",
+        "--target-lang",
+        dest="target_lang",
+        required=True,
+        help="language into which the text should be rewritten",
+    )
+    parser_rephrase.add_argument(
+        "text",
+        nargs="+",
+        type=str,
+        help="text to be rewritten. Wrap text in quotes to prevent the shell "
+        'from splitting sentences into words. Alternatively, use "-" to read '
+        "from standard-input.",
+    )
+    parser_rephrase.add_argument(
+        "--show-detected-source",
+        action="store_true",
+        help="print detected source language for each text",
+    )
+
     # create the parser for the "document" command
     parser_document = subparsers.add_parser(
         "document",
@@ -608,7 +649,7 @@ def main(args=None, prog_name=None):
             send_platform_info=not args.noplatforminfo,
         )
 
-        if args.command == "text":
+        if args.command in ["text", "translate", "rephrase"]:
             if len(args.text) == 1 and args.text[0] == "-":
                 args.text = [sys.stdin.read()]
 

deepl/api_data.py

@@ -28,6 +28,20 @@ def __str__(self):
         return self.text
 
 
+class WriteResult:
+    """Holds the result of a text improvement request."""
+
+    def __init__(
+        self, text: str, detected_source_language: str, target_language: str
+    ):
+        self.text = text
+        self.detected_source_language = detected_source_language
+        self.target_language = target_language
+
+    def __str__(self):
+        return self.text
+
+
 class DocumentHandle:
     """Handle to an in-progress document translation.
 

deepl/deepl_client.py

@@ -0,0 +1,99 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+
+from deepl.api_data import (
+    Language,
+    WriteResult,
+)
+from deepl.translator import Translator
+from typing import (
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Union,
+)
+
+
+class DeepLClient(Translator):
+    def __init__(
+        self,
+        auth_key: str,
+        *,
+        server_url: Optional[str] = None,
+        proxy: Union[Dict, str, None] = None,
+        send_platform_info: bool = True,
+        verify_ssl: Union[bool, str, None] = None,
+        skip_language_check: bool = False,
+    ):
+        super().__init__(
+            auth_key,
+            server_url=server_url,
+            proxy=proxy,
+            send_platform_info=send_platform_info,
+            verify_ssl=verify_ssl,
+            skip_language_check=skip_language_check,
+        )
+
+    def rephrase_text(
+        self,
+        text: Union[str, Iterable[str]],
+        *,
+        target_lang: Union[str, Language],
+    ) -> Union[WriteResult, List[WriteResult]]:
+        """Improve the text(s) and optionally convert them to the variant of
+        the `target_lang` (requires source lang to match target_lang, excluding
+        variants).
+
+        :param text: Text to improve.
+        :type text: UTF-8 :class:`str`; string sequence (list, tuple, iterator,
+            generator)
+        :param target_lang: language code the final text should be in, for
+            example "DE", "EN-US", "FR".
+        :return: List of WriteResult objects containing results, unless input
+            text was one string, then a single WriteResult object is returned.
+        """
+
+        if isinstance(text, str):
+            if len(text) == 0:
+                raise ValueError("text must not be empty")
+            text = [text]
+            multi_input = False
+        elif hasattr(text, "__iter__"):
+            multi_input = True
+            text = list(text)
+        else:
+            raise TypeError(
+                "text parameter must be a string or an iterable of strings"
+            )
+
+        request_data = {"target_lang": target_lang, "text": text}
+
+        status, content, json = self._api_call(
+            "v2/write/rephrase", json=request_data
+        )
+
+        self._raise_for_status(status, content, json)
+
+        improvements = (
+            json.get("improvements", [])
+            if (json and isinstance(json, dict))
+            else []
+        )
+        output = []
+        for improvement in improvements:
+            text = improvement.get("text", "") if improvement else ""
+            detected_source_language = (
+                improvement.get("detected_source_language", "")
+                if improvement
+                else ""
+            )
+            target_language = (
+                improvement.get("target_language", "") if improvement else ""
+            )
+            output.append(
+                WriteResult(text, detected_source_language, target_language)
+            )
+
+        return output if multi_input else output[0]