Added transaction support for eval, invoke, and rows

Author: rjrudin

CONTRIBUTING.md

@@ -35,7 +35,8 @@ To run an individual test method:
 
 Note that due to the pytest config in the `pyproject.toml` file, all 
 [Python logging](https://docs.python.org/3/howto/logging.html) should appear immediately
-as tests are executed.
+as tests are executed. If you are using VSCode, you can see the logging by selecting 
+"Python Test Log" in the "Output" panel.
 
 ## Testing the client in a Python shell
 

marklogic/client.py

@@ -5,7 +5,7 @@
 from marklogic.documents import DocumentManager
 from marklogic.internal.eval import process_multipart_mixed_response
 from marklogic.rows import RowManager
-from marklogic.transactions import TransactionManager
+from marklogic.transactions import TransactionManager, Transaction
 from requests.auth import HTTPDigestAuth
 from urllib.parse import urljoin
 
@@ -93,6 +93,7 @@ def eval(
         javascript: str = None,
         xquery: str = None,
         vars: dict = None,
+        tx: Transaction = None,
         return_response: bool = False,
         **kwargs,
     ):
@@ -104,6 +105,7 @@ def eval(
         :param javascript: a JavaScript script
         :param xquery: an XQuery script
         :param vars: a dict containing variables to include
+        :param tx: optional REST transaction in which to service this request.
         :param return_response: boolean specifying if the entire original response
         object should be returned (True) or if only the data should be returned (False)
         upon a success (2xx) response. Note that if the status code of the response is
@@ -118,15 +120,23 @@ def eval(
             raise ValueError("Must define either 'javascript' or 'xquery' argument.")
         if vars:
             data["vars"] = json.dumps(vars)
-        response = self.post("v1/eval", data=data, **kwargs)
+        params = kwargs.pop("params", {})
+        if tx:
+            params["txid"] = tx.id
+        response = self.post("v1/eval", data=data, params=params, **kwargs)
         return (
             process_multipart_mixed_response(response)
             if response.status_code == 200 and not return_response
             else response
         )
 
     def invoke(
-        self, module: str, vars: dict = None, return_response: bool = False, **kwargs
+        self,
+        module: str,
+        vars: dict = None,
+        tx: Transaction = None,
+        return_response: bool = False,
+        **kwargs,
     ):
         """
         Send a script (XQuery or JavaScript) and possibly a dict of vars
@@ -135,6 +145,7 @@ def invoke(
 
         :param module: The URI of a module in the modules database of the app server
         :param vars: a dict containing variables to include
+        :param tx: optional REST transaction in which to service this request.
         :param return_response: boolean specifying if the entire original response
         object should be returned (True) or if only the data should be returned (False)
         upon a success (2xx) response. Note that if the status code of the response is
@@ -143,7 +154,10 @@ def invoke(
         data = {"module": module}
         if vars:
             data["vars"] = json.dumps(vars)
-        response = self.post("v1/invoke", data=data, **kwargs)
+        params = kwargs.pop("params", {})
+        if tx:
+            params["txid"] = tx.id
+        response = self.post("v1/invoke", data=data, params=params, **kwargs)
         return (
             process_multipart_mixed_response(response)
             if response.status_code == 200 and not return_response

marklogic/rows.py

@@ -1,5 +1,6 @@
 import json
 from requests import Session
+from marklogic.transactions import Transaction
 from marklogic.internal.util import response_has_no_content
 
 
@@ -35,6 +36,7 @@ def query(
         sparql: str = None,
         graphql: str = None,
         format: str = "json",
+        tx: Transaction = None,
         return_response: bool = False,
         **kwargs,
     ):
@@ -58,6 +60,7 @@ def query(
         :param format: defines the format of the response. Valid values are "json",
         "xml", "csv", and "json-seq". If a GraphQL query is submitted, this parameter
         is ignored and a JSON response is always returned.
+        :param tx: optional REST transaction in which to service this request.
         :param return_response: boolean specifying if the entire original response
         object should be returned (True) or if only the data should be returned (False)
         upon a success (2xx) response. Note that if the status code of the response is
@@ -82,7 +85,13 @@ def query(
                 else:
                     headers["Accept"] = value
 
-        response = self._session.post(path, headers=headers, data=data, **kwargs)
+        params = kwargs.pop("params", {})
+        if tx:
+            params["txid"] = tx.id
+
+        response = self._session.post(
+            path, headers=headers, data=data, params=params, **kwargs
+        )
         if response.ok and not return_response:
             if response_has_no_content(response):
                 return []

test-app/src/main/ml-modules/invoke/read_doc1.sjs

@@ -0,0 +1 @@
+cts.doc("/doc1.json")

test-app/src/main/ml-modules/invoke/read_doc2.xqy

@@ -0,0 +1 @@
+fn:doc("/doc2.xml")

tests/test_eval.py

@@ -140,6 +140,18 @@ def test_no_script(client):
         client.eval(vars={})
 
 
+def test_transaction(client):
+    locks = None
+    with client.transactions.create() as tx:
+        client.eval(javascript="cts.doc('/doc1.json')", tx=tx)
+        client.eval(javascript="cts.doc('/doc2.xml')", tx=tx)
+        locks = client.eval(javascript="xdmp.transactionLocks()", tx=tx)
+
+    read_locks = locks[0]["read"]
+    assert "/doc1.json" in read_locks
+    assert "/doc2.xml" in read_locks
+
+
 def __verify_common_primitives(parts):
     assert type(parts[0]) is str
     assert "A" == parts[0]

tests/test_invoke.py

@@ -33,6 +33,18 @@ def test_invoke_with_return_response(client):
     assert 5 == len(parts)
 
 
+def test_transaction(client):
+    locks = None
+    with client.transactions.create() as tx:
+        client.invoke("/read_doc1.sjs", tx=tx)
+        client.invoke("/read_doc2.xqy", tx=tx)
+        locks = client.eval(javascript="xdmp.transactionLocks()", tx=tx)
+
+    read_locks = locks[0]["read"]
+    assert "/doc1.json" in read_locks
+    assert "/doc2.xml" in read_locks
+
+
 def __verify_invoke_with_vars(parts):
     assert "hello" == parts[0]
     assert "world" == parts[1]

tests/test_rows.py

@@ -1,4 +1,7 @@
 from pytest import raises
+from marklogic.documents import Document
+import uuid
+
 
 dsl_query = 'op.fromView("test","musician").orderBy(op.col("lastName"))'
 serialized_query = '{"$optic":{"ns":"op", "fn":"operators", "args":[{"ns":"op", "fn":"from-view", "args":["test", "musician"]}, {"ns":"op", "fn":"order-by", "args":[{"ns":"op", "fn":"col", "args":["lastName"]}]}]}}'
@@ -80,6 +83,35 @@ def test_no_query_parameter_provided(client):
         client.rows.query()
 
 
+def test_transaction(client):
+    lastName = str(uuid.uuid4())
+    content = {
+        "musician": {
+            "lastName": lastName,
+            "firstName": "DoesntMatter",
+            "dob": "2000-01-01",
+        }
+    }
+    uri = "/temp/musician5.json"
+
+    with client.transactions.create() as tx:
+        query = f'op.fromView("test", "musician")'
+        query = f'{query}.where(op.eq(op.col("lastName"), "{lastName}"))'
+        results = client.rows.query(query, tx=tx)
+        assert len(results) == 0
+
+        perms = {"python-tester": ["read", "update"]}
+        doc = Document(uri, content, permissions=perms)
+        client.documents.write(doc, tx=tx)
+
+        results = client.rows.query(query, tx=tx)
+        assert len(results["rows"]) == 1
+
+        client.delete("/v1/documents", params={"uri": uri, "txid": tx.id})
+        results = client.rows.query(query, tx=tx)
+        assert len(results) == 0
+
+
 def verify_four_musicians_are_returned_in_json(data, column_name):
     assert type(data) is dict
     assert 4 == len(data["rows"])