DEVEXP-590: Invoke module via Python client

Author: BillFarber

marklogic/client.py

@@ -1,10 +1,14 @@
+import json
 import requests
+
+from decimal import Decimal
 from marklogic.cloud_auth import MarkLogicCloudAuth
-from marklogic.documents import DocumentManager
+from marklogic.documents import Document, DocumentManager
+from marklogic.eval import EvalManager
 from marklogic.rows import RowManager
 from marklogic.transactions import TransactionManager
-from marklogic.eval import EvalManager
 from requests.auth import HTTPDigestAuth
+from requests_toolbelt.multipart.decoder import MultipartDecoder
 from urllib.parse import urljoin
 
 
@@ -68,6 +72,58 @@ def prepare_request(self, request, *args, **kwargs):
         request.url = urljoin(self.base_url, request.url)
         return super(Client, self).prepare_request(request, *args, **kwargs)
 
+    def invoke(
+        self, module: str, vars: dict = None, return_response: bool = False, **kwargs
+    ):
+        """
+        Send a script (XQuery or JavaScript) and possibly a dict of vars
+        to MarkLogic via a POST to the endpoint defined at
+        https://docs.marklogic.com/REST/POST/v1/eval.
+
+        :param module: The URI of a module in the modules database of the app server
+        :param vars: a dict containing variables to include
+        :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
+        not 2xx, then the entire response is always returned.
+        """
+        data = {"module": module}
+        if vars is not None:
+            data["vars"] = json.dumps(vars)
+        response = self.post("v1/invoke", data=data, **kwargs)
+        return (
+            self.process_multipart_mixed_response(response)
+            if response.status_code == 200 and not return_response
+            else response
+        )
+
+    def process_multipart_mixed_response(self, response):
+        """
+        Process a multipart REST response by putting them in a list and
+        transforming each part based on the "X-Primitive" header.
+
+        :param response: The original multipart/mixed response from a call to a
+        MarkLogic server.
+        """
+        if "Content-Length" in response.headers:
+            return None
+
+        parts = MultipartDecoder.from_response(response).parts
+        transformed_parts = []
+        for part in parts:
+            encoding = part.encoding
+            primitive_header = part.headers["X-Primitive".encode(encoding)].decode(
+                encoding
+            )
+            primitive_function = Client.__primitive_value_converters.get(
+                primitive_header
+            )
+            if primitive_function is not None:
+                transformed_parts.append(primitive_function(part))
+            else:
+                transformed_parts.append(part.text)
+        return transformed_parts
+
     @property
     def documents(self):
         if not hasattr(self, "_documents"):
@@ -91,3 +147,37 @@ def eval(self):
         if not hasattr(self, "_eval"):
             self._eval = EvalManager(self)
         return self._eval
+
+    __primitive_value_converters = {
+        "integer": lambda part: int(part.text),
+        "decimal": lambda part: Decimal(part.text),
+        "boolean": lambda part: ("False" == part.text),
+        "string": lambda part: part.text,
+        "map": lambda part: json.loads(part.text),
+        "element()": lambda part: part.text,
+        "array": lambda part: json.loads(part.text),
+        "array-node()": lambda part: json.loads(part.text),
+        "object-node()": lambda part: Client.__process_object_node_part(part),
+        "document-node()": lambda part: Client.__process_document_node_part(part),
+        "binary()": lambda part: Document(
+            Client.__get_decoded_uri_from_part(part), part.content
+        ),
+    }
+
+    def __get_decoded_uri_from_part(part):
+        encoding = part.encoding
+        return part.headers["X-URI".encode(encoding)].decode(encoding)
+
+    def __process_object_node_part(part):
+        if b"X-URI" in part.headers:
+            return Document(
+                Client.__get_decoded_uri_from_part(part), json.loads(part.text)
+            )
+        else:
+            return json.loads(part.text)
+
+    def __process_document_node_part(part):
+        if b"X-URI" in part.headers:
+            return Document(Client.__get_decoded_uri_from_part(part), part.text)
+        else:
+            return part.text

marklogic/eval.py

@@ -1,9 +1,6 @@
 import json
 
-from decimal import Decimal
-from marklogic.documents import Document
 from requests import Session
-from requests_toolbelt.multipart.decoder import MultipartDecoder
 
 """
 Defines an EvalManager class to simplify usage of the "/v1/eval" REST
@@ -34,8 +31,6 @@ def xquery(
         upon a success (2xx) response. Note that if the status code of the response is
         not 2xx, then the entire response is always returned.
         """
-        if xquery is None:
-            raise ValueError("No script found; must specify a xquery")
         return self.__send_request({"xquery": xquery}, vars, return_response, **kwargs)
 
     def javascript(
@@ -56,8 +51,6 @@ def javascript(
         upon a success (2xx) response. Note that if the status code of the response is
         not 2xx, then the entire response is always returned.
         """
-        if javascript is None:
-            raise ValueError("No script found; must specify a javascript")
         return self.__send_request(
             {"javascript": javascript}, vars, return_response, **kwargs
         )
@@ -66,73 +59,15 @@ def __send_request(
         self, data: dict, vars: dict = None, return_response: bool = False, **kwargs
     ):
         """
-        Send a script (XQuery or javascript) and possibly a dict of vars
+        Send a script (XQuery or JavaScript) and possibly a dict of vars
         to MarkLogic via a POST to the endpoint defined at
         https://docs.marklogic.com/REST/POST/v1/eval.
         """
         if vars is not None:
             data["vars"] = json.dumps(vars)
         response = self._session.post("v1/eval", data=data, **kwargs)
         return (
-            self.__process_response(response)
+            self._session.process_multipart_mixed_response(response)
             if response.status_code == 200 and not return_response
             else response
         )
-
-    def __process_response(self, response):
-        """
-        Process a multipart REST response by putting them in a list and
-        transforming each part based on the "X-Primitive" header.
-        """
-        if "Content-Length" in response.headers:
-            return None
-
-        parts = MultipartDecoder.from_response(response).parts
-        transformed_parts = []
-        for part in parts:
-            encoding = part.encoding
-            primitive_header = part.headers["X-Primitive".encode(encoding)].decode(
-                encoding
-            )
-            primitive_function = EvalManager.__primitive_value_converters.get(
-                primitive_header
-            )
-            if primitive_function is not None:
-                transformed_parts.append(primitive_function(part))
-            else:
-                transformed_parts.append(part.text)
-        return transformed_parts
-
-    __primitive_value_converters = {
-        "integer": lambda part: int(part.text),
-        "decimal": lambda part: Decimal(part.text),
-        "boolean": lambda part: ("False" == part.text),
-        "string": lambda part: part.text,
-        "map": lambda part: json.loads(part.text),
-        "element()": lambda part: part.text,
-        "array": lambda part: json.loads(part.text),
-        "array-node()": lambda part: json.loads(part.text),
-        "object-node()": lambda part: EvalManager.__process_object_node_part(part),
-        "document-node()": lambda part: EvalManager.__process_document_node_part(part),
-        "binary()": lambda part: Document(
-            EvalManager.__get_decoded_uri_from_part(part), part.content
-        ),
-    }
-
-    def __get_decoded_uri_from_part(part):
-        encoding = part.encoding
-        return part.headers["X-URI".encode(encoding)].decode(encoding)
-
-    def __process_object_node_part(part):
-        if b"X-URI" in part.headers:
-            return Document(
-                EvalManager.__get_decoded_uri_from_part(part), json.loads(part.text)
-            )
-        else:
-            return json.loads(part.text)
-
-    def __process_document_node_part(part):
-        if b"X-URI" in part.headers:
-            return Document(EvalManager.__get_decoded_uri_from_part(part), part.text)
-        else:
-            return part.text

test-app/src/main/ml-config/security/roles/python-tester.json

@@ -18,6 +18,11 @@
             "privilege-name": "xdbc:eval",
             "action": "http://marklogic.com/xdmp/privileges/xdbc-eval",
             "kind": "execute"
+        },
+        {
+            "privilege-name": "xdbc:invoke",
+            "action": "http://marklogic.com/xdmp/privileges/xdbc-invoke",
+            "kind": "execute"
         }
     ]
 }

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

@@ -0,0 +1 @@
+xdmp.arrayValues(['A', 1, 1.1, false, fn.doc('/musicians/logo.png')])

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

@@ -0,0 +1,3 @@
+xquery version "1.0-ml";
+
+('A', 1, 1.1, fn:false(), fn:doc('/musicians/logo.png'))

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

@@ -0,0 +1 @@
+xdmp.arrayValues([word1, word2, word1 + " " + word2])

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

@@ -0,0 +1,6 @@
+xquery version "1.0-ml";
+
+declare variable $word1 as xs:string external;
+declare variable $word2 as xs:string external;
+
+($word1, $word2, fn:concat($word1, " ", $word2))

tests/test_eval.py

@@ -2,7 +2,6 @@
 
 from marklogic.documents import Document
 from requests_toolbelt.multipart.decoder import MultipartDecoder
-from pytest import raises
 
 
 def test_xquery_common_primitives(client):
@@ -72,16 +71,6 @@ def test_javascript_specific_primitives(client):
     } == parts[2].content
 
 
-def test_javascript_noquery(client):
-    with raises(ValueError, match="No script found; must specify a javascript"):
-        client.eval.javascript(None)
-
-
-def test_xquery_noquery(client):
-    with raises(ValueError, match="No script found; must specify a xquery"):
-        client.eval.xquery(None)
-
-
 def test_xquery_with_return_response(client):
     response = client.eval.xquery("('A', 1, 1.1, fn:false())", return_response=True)
     assert 200 == response.status_code

tests/test_invoke.py

@@ -0,0 +1,53 @@
+import decimal
+
+from marklogic.documents import Document
+from requests_toolbelt.multipart.decoder import MultipartDecoder
+
+
+def test_invoke_xquery_simple(client):
+    parts = client.invoke("/simple.xqy")
+    __verify_invoke_simple(parts)
+
+
+def test_invoke_javascript_simple(client):
+    parts = client.invoke("/simple.sjs")
+    __verify_invoke_simple(parts)
+
+
+def test_invoke_xquery_simple_vars(client):
+    vars = {"word1": "hello", "word2": "world"}
+    parts = client.invoke("/simple_vars.xqy", vars)
+    __verify_invoke_with_vars(parts)
+
+
+def test_invoke_javascript_simple_vars(client):
+    vars = {"word1": "hello", "word2": "world"}
+    parts = client.invoke("/simple_vars.sjs", vars)
+    __verify_invoke_with_vars(parts)
+
+
+def test_invoke_with_return_response(client):
+    response = client.invoke("/simple.xqy", return_response=True)
+    assert 200 == response.status_code
+    parts = MultipartDecoder.from_response(response).parts
+    assert 5 == len(parts)
+
+
+def __verify_invoke_with_vars(parts):
+    assert "hello" == parts[0]
+    assert "world" == parts[1]
+    assert "hello world" == parts[2]
+
+
+def __verify_invoke_simple(parts):
+    assert type(parts[0]) is str
+    assert "A" == parts[0]
+    assert type(parts[1]) is int
+    assert 1 == parts[1]
+    assert type(parts[2]) is decimal.Decimal
+    assert decimal.Decimal("1.1") == parts[2]
+    assert type(parts[3]) is bool
+    assert parts[3] is False
+    assert type(parts[4]) is Document
+    assert "/musicians/logo.png" == parts[4].uri
+    assert b"PNG" in parts[4].content