feat: take CustomInstruction and extra_body_parameters in style rules

get_style_rule_custom_instruction(), update_style_rule_custom_instruction()
and delete_style_rule_custom_instruction() take a CustomInstruction as
instruction_id. The five style rule functions that send a JSON body take
extra_body_parameters, merged into the body last.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -16,6 +16,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.

README.md

@@ -969,7 +969,10 @@ updated = deepl_client.update_style_rule_configured_rules(
 Custom instructions allow you to add free-text prompts to a style rule. Use
 `create_style_rule_custom_instruction()`, `get_style_rule_custom_instruction()`,
 `update_style_rule_custom_instruction()`, and
-`delete_style_rule_custom_instruction()` to manage them.
+`delete_style_rule_custom_instruction()` to manage them. The `style_rule`
+argument of every style rule function takes a style rule ID or a
+`StyleRuleInfo` object, and `instruction_id` takes a custom instruction ID or a
+`CustomInstruction` object.
 
 ```python
 # Create a custom instruction
@@ -993,9 +996,20 @@ updated = deepl_client.update_style_rule_custom_instruction(
     prompt="Use very formal language",
 )
 
-# Delete a custom instruction
-deepl_client.delete_style_rule_custom_instruction(
-    "YOUR_STYLE_ID", instruction.id
+# Delete a custom instruction (by ID or CustomInstruction object)
+deepl_client.delete_style_rule_custom_instruction("YOUR_STYLE_ID", instruction)
+```
+
+`create_style_rule()`, `update_style_rule_name()`,
+`update_style_rule_configured_rules()`, `create_style_rule_custom_instruction()`
+and `update_style_rule_custom_instruction()` also accept
+`extra_body_parameters`: a dictionary of extra parameters to pass in the JSON
+request body, which replace request fields of the same name. See the
+`extra_body_parameters` [text translation option](#text-translation-options).
+
+```python
+deepl_client.update_style_rule_name(
+    "YOUR_STYLE_ID", "New Name", extra_body_parameters={"beta_param": "value"}
 )
 ```
 

deepl/deepl_client.py

@@ -1329,13 +1329,19 @@ def create_style_rule(
         language: str,
         configured_rules: Optional[dict] = None,
         custom_instructions: Optional[List[dict]] = None,
+        *,
+        extra_body_parameters: Optional[dict] = None,
     ) -> StyleRuleInfo:
         """Creates a new style rule.
 
         :param name: Name for the style rule.
         :param language: Language code for the style rule.
         :param configured_rules: Optional dict of configured rules.
         :param custom_instructions: Optional list of custom instruction dicts.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. If provided,
+            keys in this dict will be added to the request body, and replace
+            keys of the same name that the client sets.
         :return: StyleRuleInfo for the created style rule.
         """
         if not name:
@@ -1350,7 +1356,8 @@ def create_style_rule(
             request_data["custom_instructions"] = custom_instructions
 
         status, content, json = self._api_call(
-            "v3/style_rules", json=request_data
+            "v3/style_rules",
+            json=self._with_extra_body(request_data, extra_body_parameters),
         )
         self._raise_for_status(status, content, json)
         return self._parse_style_rule_response(StyleRuleInfo.from_json, json)
@@ -1375,19 +1382,27 @@ def update_style_rule_name(
         self,
         style_rule: Union[str, StyleRuleInfo],
         name: str,
+        *,
+        extra_body_parameters: Optional[dict] = None,
     ) -> StyleRuleInfo:
         """Updates the name of a style rule.
 
         :param style_rule: Style rule ID string or StyleRuleInfo object.
         :param name: New name for the style rule.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. If provided,
+            keys in this dict will be added to the request body, and replace
+            keys of the same name that the client sets.
         :return: Updated StyleRuleInfo.
         """
         style_id = self._style_rule_id(style_rule)
         if not name:
             raise ValueError("name must not be empty")
         request_data = {"name": name}
         status, content, json = self._api_call(
-            f"v3/style_rules/{style_id}", method="PATCH", json=request_data
+            f"v3/style_rules/{style_id}",
+            method="PATCH",
+            json=self._with_extra_body(request_data, extra_body_parameters),
         )
         self._raise_for_status(status, content, json)
         return self._parse_style_rule_response(StyleRuleInfo.from_json, json)
@@ -1410,18 +1425,26 @@ def update_style_rule_configured_rules(
         self,
         style_rule: Union[str, StyleRuleInfo],
         configured_rules: dict,
+        *,
+        extra_body_parameters: Optional[dict] = None,
     ) -> StyleRuleInfo:
         """Updates the configured rules of a style rule.
 
         :param style_rule: Style rule ID string or StyleRuleInfo object.
         :param configured_rules: Dict of configured rules to set.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. If provided,
+            keys in this dict will be added to the request body, and replace
+            keys of the same name that the client sets.
         :return: Updated StyleRuleInfo.
         """
         style_id = self._style_rule_id(style_rule)
         status, content, json = self._api_call(
             f"v3/style_rules/{style_id}/configured_rules",
             method="PUT",
-            json=configured_rules,
+            json=self._with_extra_body(
+                configured_rules, extra_body_parameters
+            ),
         )
         self._raise_for_status(status, content, json)
         return self._parse_style_rule_response(StyleRuleInfo.from_json, json)
@@ -1432,13 +1455,19 @@ def create_style_rule_custom_instruction(
         label: str,
         prompt: str,
         source_language: Optional[str] = None,
+        *,
+        extra_body_parameters: Optional[dict] = None,
     ) -> CustomInstruction:
         """Creates a custom instruction for a style rule.
 
         :param style_rule: Style rule ID string or StyleRuleInfo object.
         :param label: Label for the custom instruction.
         :param prompt: Prompt text for the custom instruction.
         :param source_language: Optional source language code.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. If provided,
+            keys in this dict will be added to the request body, and replace
+            keys of the same name that the client sets.
         :return: Created CustomInstruction.
         """
         style_id = self._style_rule_id(style_rule)
@@ -1451,7 +1480,7 @@ def create_style_rule_custom_instruction(
             request_data["source_language"] = source_language
         status, content, json = self._api_call(
             f"v3/style_rules/{style_id}/custom_instructions",
-            json=request_data,
+            json=self._with_extra_body(request_data, extra_body_parameters),
         )
         self._raise_for_status(status, content, json)
         return self._parse_style_rule_response(
@@ -1461,19 +1490,18 @@ def create_style_rule_custom_instruction(
     def get_style_rule_custom_instruction(
         self,
         style_rule: Union[str, StyleRuleInfo],
-        instruction_id: str,
+        instruction_id: Union[str, CustomInstruction],
     ) -> CustomInstruction:
         """Retrieves a custom instruction by ID.
 
         :param style_rule: Style rule ID string or StyleRuleInfo object.
-        :param instruction_id: ID of the custom instruction.
+        :param instruction_id: ID of the custom instruction, or a
+            CustomInstruction object.
         :return: CustomInstruction.
         """
         style_id = self._style_rule_id(style_rule)
         instruction = self._custom_instruction_id(instruction_id)
-        url = (
-            f"v3/style_rules/{style_id}" f"/custom_instructions/{instruction}"
-        )
+        url = f"v3/style_rules/{style_id}/custom_instructions/{instruction}"
         status, content, json = self._api_call(
             url,
             method="GET",
@@ -1486,18 +1514,25 @@ def get_style_rule_custom_instruction(
     def update_style_rule_custom_instruction(
         self,
         style_rule: Union[str, StyleRuleInfo],
-        instruction_id: str,
+        instruction_id: Union[str, CustomInstruction],
         label: str,
         prompt: str,
         source_language: Optional[str] = None,
+        *,
+        extra_body_parameters: Optional[dict] = None,
     ) -> CustomInstruction:
         """Updates a custom instruction.
 
         :param style_rule: Style rule ID string or StyleRuleInfo object.
-        :param instruction_id: ID of the custom instruction.
+        :param instruction_id: ID of the custom instruction, or a
+            CustomInstruction object.
         :param label: New label for the custom instruction.
         :param prompt: New prompt text for the custom instruction.
         :param source_language: Optional source language code.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. If provided,
+            keys in this dict will be added to the request body, and replace
+            keys of the same name that the client sets.
         :return: Updated CustomInstruction.
         """
         style_id = self._style_rule_id(style_rule)
@@ -1509,13 +1544,11 @@ def update_style_rule_custom_instruction(
         request_data = {"label": label, "prompt": prompt}
         if source_language is not None:
             request_data["source_language"] = source_language
-        url = (
-            f"v3/style_rules/{style_id}" f"/custom_instructions/{instruction}"
-        )
+        url = f"v3/style_rules/{style_id}/custom_instructions/{instruction}"
         status, content, json = self._api_call(
             url,
             method="PUT",
-            json=request_data,
+            json=self._with_extra_body(request_data, extra_body_parameters),
         )
         self._raise_for_status(status, content, json)
         return self._parse_style_rule_response(
@@ -1525,18 +1558,17 @@ def update_style_rule_custom_instruction(
     def delete_style_rule_custom_instruction(
         self,
         style_rule: Union[str, StyleRuleInfo],
-        instruction_id: str,
+        instruction_id: Union[str, CustomInstruction],
     ) -> None:
         """Deletes a custom instruction from a style rule.
 
         :param style_rule: Style rule ID string or StyleRuleInfo object.
-        :param instruction_id: ID of the custom instruction to delete.
+        :param instruction_id: ID of the custom instruction to delete, or a
+            CustomInstruction object.
         """
         style_id = self._style_rule_id(style_rule)
         instruction = self._custom_instruction_id(instruction_id)
-        url = (
-            f"v3/style_rules/{style_id}" f"/custom_instructions/{instruction}"
-        )
+        url = f"v3/style_rules/{style_id}/custom_instructions/{instruction}"
         status, content, json = self._api_call(
             url,
             method="DELETE",
@@ -1774,6 +1806,11 @@ def _style_profile_json(
             request_data.update(extra_body_parameters)
         return request_data
 
+    @staticmethod
+    def _with_extra_body(body: dict, extra: Optional[dict]) -> dict:
+        # Entries replace keys of the same name set by the client.
+        return {**body, **extra} if extra else body
+
     @staticmethod
     def _parse_style_rule_response(
         parse: Callable[[Any], _T], json: Any
@@ -1794,7 +1831,11 @@ def _style_rule_id(style_rule: Union[str, StyleRuleInfo]) -> str:
         return urllib.parse.quote(style_rule, safe="")
 
     @staticmethod
-    def _custom_instruction_id(instruction_id: str) -> str:
+    def _custom_instruction_id(
+        instruction_id: Union[str, CustomInstruction, None],
+    ) -> str:
+        if isinstance(instruction_id, CustomInstruction):
+            instruction_id = instruction_id.id
         if not instruction_id:
             raise ValueError("instruction_id must not be empty")
         return urllib.parse.quote(instruction_id, safe="")

tests/offline/test_style_rules.py

@@ -418,3 +418,96 @@ def test_raises_deepl_exception_for_malformed_response(
 
     with pytest.raises(DeepLException, match="Unexpected style rule response"):
         call(make_deepl_client())
+
+
+@pytest.mark.parametrize(
+    "instruction",
+    ["instruction-1", CustomInstruction.from_json(INSTRUCTION_JSON)],
+)
+def test_accepts_instruction_id_or_object(mocked, instruction):
+    path = url("v3/style_rules/style-1/custom_instructions/instruction-1")
+    mocked.get(path, json=INSTRUCTION_JSON, match=bodyless_request())
+    mocked.put(path, json=INSTRUCTION_JSON)
+    mocked.delete(path, status=204, match=bodyless_request())
+    client = make_deepl_client()
+
+    client.get_style_rule_custom_instruction("style-1", instruction)
+    client.update_style_rule_custom_instruction(
+        "style-1", instruction, "L", "P"
+    )
+    client.delete_style_rule_custom_instruction("style-1", instruction)
+
+
+def test_rejects_instruction_object_without_id():
+    with pytest.raises(ValueError, match="instruction_id must not be empty"):
+        make_deepl_client().get_style_rule_custom_instruction(
+            "style-1", CustomInstruction("L", "P")
+        )
+
+
+EXTRA = {"name": "replaced", "extra": True}
+
+
+@pytest.mark.parametrize(
+    "method, path, body, response, call",
+    [
+        (
+            "POST",
+            "v3/style_rules",
+            {"name": "replaced", "language": "en", "extra": True},
+            STYLE_RULE_JSON,
+            lambda c: c.create_style_rule(
+                "style", "en", extra_body_parameters=EXTRA
+            ),
+        ),
+        (
+            "PATCH",
+            "v3/style_rules/style-1",
+            {"name": "replaced", "extra": True},
+            STYLE_RULE_JSON,
+            lambda c: c.update_style_rule_name(
+                "style-1", "new", extra_body_parameters=EXTRA
+            ),
+        ),
+        (
+            "PUT",
+            "v3/style_rules/style-1/configured_rules",
+            {**CONFIGURED_RULES, "name": "replaced", "extra": True},
+            STYLE_RULE_JSON,
+            lambda c: c.update_style_rule_configured_rules(
+                "style-1", CONFIGURED_RULES, extra_body_parameters=EXTRA
+            ),
+        ),
+        (
+            "POST",
+            "v3/style_rules/style-1/custom_instructions",
+            {"label": "replaced", "prompt": "P", "extra": True},
+            INSTRUCTION_JSON,
+            lambda c: c.create_style_rule_custom_instruction(
+                "style-1",
+                "L",
+                "P",
+                extra_body_parameters={"label": "replaced", "extra": True},
+            ),
+        ),
+        (
+            "PUT",
+            "v3/style_rules/style-1/custom_instructions/instruction-1",
+            {"label": "replaced", "prompt": "P", "extra": True},
+            INSTRUCTION_JSON,
+            lambda c: c.update_style_rule_custom_instruction(
+                "style-1",
+                "instruction-1",
+                "L",
+                "P",
+                extra_body_parameters={"label": "replaced", "extra": True},
+            ),
+        ),
+    ],
+)
+def test_merges_extra_body_parameters_last(
+    mocked, method, path, body, response, call
+):
+    mocked.add(method, url(path), json=response, match=json_request(body))
+
+    call(make_deepl_client())