From 0ab132ef157a92594b2b29e7ecfe2b0d58c67cf2 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Mon, 31 Aug 2026 21:54:11 +0200
Subject: [PATCH] Document DataverseClient._request and test its success path

_request now carries the parameters, return value, and error
conditions of the Dataverse native-API contract every public method
relies on.

A new unit test confirms _request returns a non-empty 2xx JSON-object
body unchanged, the one behavior no existing test observes directly
since every public method discards part of the body.
---
 src/fwl_io/mirror.py | 26 ++++++++++++++++++++++++++
 tests/test_mirror.py | 16 ++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/src/fwl_io/mirror.py b/src/fwl_io/mirror.py
index 3079d56..811e3b0 100644
--- a/src/fwl_io/mirror.py
+++ b/src/fwl_io/mirror.py
@@ -143,6 +143,32 @@ def _headers(self) -> dict:
         return {'X-Dataverse-key': self.token}
 
     def _request(self, method: str, path: str, **kwargs) -> dict:
+        """Call one Dataverse native-API endpoint and return its decoded body.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method, e.g. ``'POST'`` or ``'DELETE'``.
+        path : str
+            API path relative to ``self.base_url``, e.g.
+            ``'/api/datasets/:persistentId'``.
+        **kwargs
+            Passed through to :func:`requests.request` (``params``, ``json``,
+            ``files``, and so on).
+
+        Returns
+        -------
+        dict
+            The decoded JSON body, or ``{}`` for a 2xx response with an empty
+            body (routine for a DELETE call).
+
+        Raises
+        ------
+        DataverseError
+            If the HTTP transport fails, the response status is 400 or
+            higher, or a non-empty successful body fails to parse as JSON or
+            parses to something other than a JSON object.
+        """
         try:
             response = requests.request(
                 method,
diff --git a/tests/test_mirror.py b/tests/test_mirror.py
index dc4e0a7..f2c71c0 100644
--- a/tests/test_mirror.py
+++ b/tests/test_mirror.py
@@ -418,6 +418,22 @@ def test_create_with_a_non_object_json_body_raises_with_the_status_and_body():
         requests.request = orig
 
 
+@pytest.mark.unit
+def test_request_returns_the_decoded_body_on_a_valid_success_response():
+    """A 2xx response with a non-empty JSON-object body decodes and returns as-is."""
+    import requests
+
+    client = DataverseClient('http://unused', 'tok')
+    orig = requests.request
+    body_bytes = b'{"status": "OK", "data": {"id": 7}}'
+    requests.request = lambda *args, **kwargs: _fake_response(200, body_bytes)
+    try:
+        body = client._request('POST', '/api/datasets/:persistentId/add')
+        assert body == {'status': 'OK', 'data': {'id': 7}}
+    finally:
+        requests.request = orig
+
+
 @pytest.mark.unit
 def test_add_file_accepts_an_empty_success_body(tmp_path):
     """add_file does not raise when Dataverse returns 2xx with an empty body."""