Merge pull request #41 from BillFarber/feature/addResponseOption

DEVEXP-591: Return response when reading and searching documents

Author: BillFarber

docs/managing-documents/reading.md

@@ -114,6 +114,12 @@ print(docs)
 Please see [the application developer's guide](https://docs.marklogic.com/guide/rest-dev/documents#id_80116)
 for more information on reading documents.
 
+## Returning the original HTTP response
+
+The `client.documents.read` method also accepts a `return_response` argument. When that
+argument is set to `True`, the original response is returned. This can be useful for custom
+processing of the response or debugging requests.
+
 ## Error handling
 
 If the `client.documents.read` method receives an HTTP response with a status code of 200, then the client will return

docs/managing-documents/searching.md

@@ -155,6 +155,12 @@ assert len(docs) == 2
 Please see [the application developer's guide](https://docs.marklogic.com/guide/rest-dev/search#id_49329)
 for more information on searching documents.
 
+## Returning the original HTTP response
+
+The `client.documents.search` method also accepts a `return_response` argument. When
+that argument is set to `True`, the original response is returned. This can be useful for
+custom processing of the response or debugging requests.
+
 ## Error handling
 
 If the `client.documents.read` method receives an HTTP response with a status code of 200, then the client will return

marklogic/documents.py

@@ -399,6 +399,7 @@ def read(
         uris: Union[str, list[str]],
         categories: list[str] = None,
         tx: Transaction = None,
+        return_response: bool = False,
         **kwargs,
     ) -> Union[list[Document], Response]:
         """
@@ -428,7 +429,7 @@ def read(
 
         return (
             multipart_response_to_documents(response)
-            if response.status_code == 200
+            if response.status_code == 200 and not return_response
             else response
         )
 
@@ -442,6 +443,7 @@ def search(
         options: str = None,
         collections: list[str] = None,
         tx: Transaction = None,
+        return_response: bool = False,
         **kwargs,
     ) -> Union[list[Document], Response]:
         """
@@ -512,6 +514,6 @@ def search(
 
         return (
             multipart_response_to_documents(response)
-            if response.status_code == 200
+            if response.status_code == 200 and not return_response
             else response
         )

tests/test_read_documents.py

@@ -137,6 +137,13 @@ def test_read_with_basic_client(basic_client: Client):
     assert {"hello": "world"} == doc.content
 
 
+def test_read_with_original_response(basic_client: Client):
+    response = basic_client.documents.read("/doc1.json", return_response=True)
+    assert b'--ML_BOUNDARY' in response.content
+    assert b'filename="/doc1.json"' in response.content
+    assert b'{"hello":"world"}' in response.content
+
+
 def test_not_rest_user(not_rest_user_client: Client):
     response: Response = not_rest_user_client.documents.read(
         ["/doc1.json", "/doc2.xml"]

tests/test_search_docs.py

@@ -3,6 +3,7 @@
 from requests import Response
 
 from marklogic import Client
+from marklogic.documents import multipart_response_to_documents
 
 
 def test_structured_json_string_query(client: Client):
@@ -73,6 +74,15 @@ def test_search_options(client: Client):
     assert len(docs) == 0
 
 
+def test_search_with_original_response(client: Client):
+    response = client.documents.search(
+        q="hello:world", options="test-options", return_response=True
+    )
+    docs = multipart_response_to_documents(response)
+    assert len(docs) == 1
+    assert docs[0].uri == "/doc2.xml"
+
+
 def test_collection(client: Client):
     docs = client.documents.search(
         categories=["content", "collections"], collections=["search-test"]