feat: add extra_body_parameters to the developer key methods

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

Author: hive-bot

CHANGELOG.md

@@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `CustomTagUsage` and `CustomTagUsageBreakdown`, and the request options
   `DeveloperKeyUsageLimitsUpdate`, `AdminUsageGroupBy` and
   `CustomTagUsageAggregateBy`.
+  The developer key methods that send a request body accept
+  `extra_body_parameters`.
 - 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.

README.md

@@ -1296,6 +1296,12 @@ admin_client.deactivate_developer_key(key)
 `deactivate_developer_key()` accept either a key ID or a `DeveloperKey` object
 and return the updated `DeveloperKey`.
 
+`create_developer_key()`, `rename_developer_key()`,
+`set_developer_key_usage_limits()` and `deactivate_developer_key()` also accept
+`extra_body_parameters`, a dict of additional key/value pairs to include in the
+JSON request body. They are added last and replace keys of the same name that
+the client sets.
+
 #### Retrieving usage analytics
 
 `get_usage_analytics()` returns an `AdminUsageReport` for a date range. Dates

deepl/admin_client.py

@@ -166,7 +166,10 @@ def get_custom_tag_usage_analytics(
         return CustomTagUsageReport.from_json(json)
 
     def create_developer_key(
-        self, *, label: Optional[str] = None
+        self,
+        *,
+        label: Optional[str] = None,
+        extra_body_parameters: Optional[dict] = None,
     ) -> DeveloperKey:
         """Creates a developer key in the organization. The request is only
         retried if it cannot have been processed (HTTP 429 or a DNS
@@ -175,11 +178,15 @@ def create_developer_key(
 
         :param label: (Optional) Label for the new key. The API uses
             "DeepL API Key" if no label is given.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. They are added
+            last and replace keys of the same name that the client sets.
         :return: DeveloperKey describing the created key.
         """
         request_data = {}
         if label is not None:
             request_data["label"] = label
+        _add_extra_body_parameters(request_data, extra_body_parameters)
 
         status, content, json = self._api_call(
             "v2/admin/developer-keys",
@@ -208,36 +215,54 @@ def list_developer_keys(self) -> List[DeveloperKey]:
         ]
 
     def deactivate_developer_key(
-        self, key: Union[str, DeveloperKey]
+        self,
+        key: Union[str, DeveloperKey],
+        *,
+        extra_body_parameters: Optional[dict] = None,
     ) -> DeveloperKey:
         """Deactivates a developer key. Deactivation is permanent.
 
         :param key: Key ID or DeveloperKey to deactivate.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. They are added
+            last and replace keys of the same name that the client sets.
         :return: DeveloperKey describing the deactivated key.
         """
         return self._put_developer_key(
-            "v2/admin/developer-keys/deactivate", {"key_id": _key_id(key)}
+            "v2/admin/developer-keys/deactivate",
+            {"key_id": _key_id(key)},
+            extra_body_parameters,
         )
 
     def rename_developer_key(
-        self, key: Union[str, DeveloperKey], label: str
+        self,
+        key: Union[str, DeveloperKey],
+        label: str,
+        *,
+        extra_body_parameters: Optional[dict] = None,
     ) -> DeveloperKey:
         """Changes the label of a developer key.
 
         :param key: Key ID or DeveloperKey to rename.
         :param label: New label for the key.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. They are added
+            last and replace keys of the same name that the client sets.
         :return: DeveloperKey describing the renamed key.
         """
         key_id = _key_id(key)
         return self._put_developer_key(
             "v2/admin/developer-keys/label",
             {"key_id": key_id, "label": label},
+            extra_body_parameters,
         )
 
     def set_developer_key_usage_limits(
         self,
         key: Union[str, DeveloperKey],
         limits: DeveloperKeyUsageLimitsUpdate,
+        *,
+        extra_body_parameters: Optional[dict] = None,
     ) -> DeveloperKey:
         """Changes the monthly usage limits of a developer key. Only the
         limits set in `limits` are changed; the others keep their current
@@ -247,22 +272,40 @@ def set_developer_key_usage_limits(
         :param limits: DeveloperKeyUsageLimitsUpdate with the limits to
             change. None removes a limit (unlimited usage) and 0 blocks that
             usage.
+        :param extra_body_parameters: (Optional) Additional key/value pairs to
+            include in the JSON request body sent to the API. They are added
+            last and replace keys of the same name that the client sets.
         :return: DeveloperKey describing the modified key.
         """
         key_id = _key_id(key)
         return self._put_developer_key(
             "v2/admin/developer-keys/limits",
             {"key_id": key_id, **limits._to_request_dict()},
+            extra_body_parameters,
         )
 
-    def _put_developer_key(self, url: str, request_data: dict) -> DeveloperKey:
+    def _put_developer_key(
+        self,
+        url: str,
+        request_data: dict,
+        extra_body_parameters: Optional[dict],
+    ) -> DeveloperKey:
+        _add_extra_body_parameters(request_data, extra_body_parameters)
         status, content, json = self._api_call(
             url, method="PUT", json=request_data
         )
         self._raise_for_status(status, content, json)
         return _parse_key(json)
 
 
+def _add_extra_body_parameters(
+    request_data: dict, extra_body_parameters: Optional[dict]
+) -> None:
+    # Entries replace keys of the same name set by the client.
+    if extra_body_parameters:
+        request_data.update(extra_body_parameters)
+
+
 def _date_range_params(
     start_date: Union[datetime.date, str], end_date: Union[datetime.date, str]
 ) -> Dict[str, str]:

tests/offline/test_admin_client.py

@@ -505,3 +505,57 @@ def test_admin_client_applies_retry_and_timeout_options(mocked, no_retries):
 
     assert len(mocked.calls) == 2
     assert mocked.calls[1].request.req_kwargs["timeout"] == 42.0
+
+
+@pytest.mark.parametrize(
+    "method, path, call, body",
+    [
+        (
+            "POST",
+            "v2/admin/developer-keys",
+            lambda c, extra: c.create_developer_key(
+                label="a", extra_body_parameters=extra
+            ),
+            {"label": "replaced", "flag": True},
+        ),
+        (
+            "PUT",
+            "v2/admin/developer-keys/deactivate",
+            lambda c, extra: c.deactivate_developer_key(
+                KEY_ID, extra_body_parameters=extra
+            ),
+            {"key_id": KEY_ID, "label": "replaced", "flag": True},
+        ),
+        (
+            "PUT",
+            "v2/admin/developer-keys/label",
+            lambda c, extra: c.rename_developer_key(
+                KEY_ID, "a", extra_body_parameters=extra
+            ),
+            {"key_id": KEY_ID, "label": "replaced", "flag": True},
+        ),
+        (
+            "PUT",
+            "v2/admin/developer-keys/limits",
+            lambda c, extra: c.set_developer_key_usage_limits(
+                KEY_ID,
+                deepl.DeveloperKeyUsageLimitsUpdate(characters=1),
+                extra_body_parameters=extra,
+            ),
+            {
+                "key_id": KEY_ID,
+                "characters": 1,
+                "label": "replaced",
+                "flag": True,
+            },
+        ),
+    ],
+)
+def test_developer_key_methods_send_extra_body_parameters(
+    mocked, method, path, call, body
+):
+    mocked.add(
+        method, url(path), match=json_request(body), json=DEVELOPER_KEY_JSON
+    )
+
+    call(make_admin_client(), {"label": "replaced", "flag": True})