Merge pull request #5 from marklogic/feature/493-digest-auth

DEVEXP-493 Initial client

Author: rjrudin

CONTRIBUTING.md

@@ -31,6 +31,25 @@ To run an individual test method:
 
     pytest -s test/test_search.py::test_search
 
+## Testing the client in a Python shell
+
+After running `poetry install` as described above, you can start a Python shell and manually test the client. You will 
+need to launch the shell in the same Python virtual environment as the one in which you ran `poetry install`. After 
+ensuring you've done that, start a new Python shell by running `python`. 
+
+You can then import the client via:
+
+    from marklogic.client import Client
+
+You can instantiate an instance of the client that communicates with this project's test application via:
+
+    client = Client("http://localhost:8030", digest=("python-test-user", "password"))
+
+And you can then start sending requests with the client - for example:
+
+    r = client.get("/v1/search?format=json&pageLength=2")
+    r.json()
+
 ## Testing the documentation locally
 
 The docs for this project are stored in the `./docs` directory as a set of Markdown files. These are published via

docs/getting-started.md

@@ -0,0 +1,69 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+---
+
+**Until the 1.0 release is available**, please follow the instructions in the CONTRIBUTING.md file for installing the 
+MarkLogic Python client into a Python virtual environment.
+
+## Connecting to MarkLogic
+
+(TODO This will almost certainly be reorganized before the 1.0 release.)
+
+The `Client` class is the primary API to interact with in the MarkLogic Python client. The
+`Client` class extends the `requests` 
+[`Session` class](https://docs.python-requests.org/en/latest/user/advanced/#session-objects), thus exposing all methods
+found in both the `Session` class and the `requests` API. You can therefore use a `Client` object in the same manner 
+as you'd use either the `Session` class or the `requests` API.
+
+A `Client` instance can be constructed either by providing a base URL for all requests along with authentication:
+
+    from marklogic.client import Client
+    client = Client('http://localhost:8030', digest=('username', 'password'))
+
+Or via separate arguments for each of the parts of a base URL:
+
+    from marklogic.client import Client
+    client = Client(host='localhost', port='8030', digest=('username', 'password'))
+
+After constructing a `Client` instance, each of the methods in the `requests` API for sending an HTTP request can be 
+used without needing to specify the base URL nor the authentication again. For example:
+
+    response = client.post('/v1/search')
+    response = client.get('/v1/documents', params={'uri': '/my-doc.json'})
+
+Because the `Client` class extends the `Sessions` class, it can be used as a context manager:
+
+    with Client('http://localhost:8030', digest=('username', 'password')) as client:
+        response = client.post('/v1/search')
+        response = client.get('/v1/documents', params={'uri': '/my-doc.json'})
+
+## Authentication
+
+The `Client` constructor includes a `digest` argument as a convenience for using digest authentication:
+
+    from marklogic.client import Client
+    client = Client('http://localhost:8030', digest=('username', 'password'))
+
+An `auth` argument is also available for using any authentication strategy that can be configured
+[via the requests `auth` argument](https://requests.readthedocs.io/en/latest/user/advanced/#custom-authentication). For 
+example, just like with `requests`, a tuple can be passed to the `auth` argument to use basic authentication:
+
+    from marklogic.client import Client
+    client = Client('http://localhost:8030', auth=('username', 'password'))
+
+## SSL 
+
+Configuring SSL connections is the same as 
+[documented for the `requests` library](https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification). 
+As a convience, the `Client` constructor includes a `verify` argument so that it does not need to be configured on the 
+`Client` instance after it's been constructed nor on every request:
+
+    from marklogic.client import Client
+    client = Client('https://localhost:8030', digest=('username', 'password'), verify='/path/to/cert.pem')
+
+When specifying the base URL via separate arguments, the `scheme` argument can be set for HTTPS connections:
+
+    from marklogic.client import Client
+    client = Client(host='localhost', port='8030', scheme='https', digest=('username', 'password'), verify=False)

marklogic/__init__.py

@@ -0,0 +1,48 @@
+import requests
+from requests.auth import HTTPDigestAuth
+from urllib.parse import urljoin
+
+
+class Client(requests.Session):
+    def __init__(
+        self,
+        base_url: str = None,
+        auth=None,
+        digest=None,
+        scheme: str = "http",
+        verify: bool = True,
+        host: str = None,
+        port: int = 0,
+        username: str = None,
+        password: str = None,
+    ):
+        if base_url:
+            self.base_url = base_url
+        else:
+            self.base_url = f"{scheme}://{host}:{port}"
+        super(Client, self).__init__()
+        self.verify = verify
+        if auth:
+            self.auth = auth
+        elif digest:
+            self.auth = HTTPDigestAuth(digest[0], digest[1])
+        else:
+            self.auth = HTTPDigestAuth(username, password)
+
+    def request(self, method, url, *args, **kwargs):
+        """
+        Overrides the requests function to generate the complete URL before the request
+        is sent.
+        """
+        url = urljoin(self.base_url, url)
+        return super(Client, self).request(method, url, *args, **kwargs)
+
+    def prepare_request(self, request, *args, **kwargs):
+        """
+        Overrides the requests function to generate the complete URL before the
+        request is prepared. See
+        https://requests.readthedocs.io/en/latest/user/advanced/#prepared-requests for
+        more information on prepared requests.
+        """
+        request.url = urljoin(self.base_url, request.url)
+        return super(Client, self).prepare_request(request, *args, **kwargs)

marklogic/client.py

@@ -0,0 +1,5 @@
+{
+    "server-name": "%%NAME%%",
+    "group-name": "Default",
+    "authentication": "digestbasic"
+}

test-app/src/main/ml-config/servers/test-server.json

@@ -1,10 +1,25 @@
 import pytest
-import requests
-from requests.auth import HTTPDigestAuth
+from marklogic.client import Client
 
 
 @pytest.fixture
-def test_session():
-    session = requests.Session()
-    session.auth = HTTPDigestAuth("python-test-user", "password")
-    return session
+def client():
+    return Client("http://localhost:8030", digest=("python-test-user", "password"))
+
+
+@pytest.fixture
+def basic_client():
+    # requests allows a tuple to be passed when doing basic authentication.
+    return Client("http://localhost:8030", auth=("python-test-user", "password"))
+
+
+@pytest.fixture
+def ssl_client():
+    return Client(host="localhost", scheme="https", port=8031,
+                  digest=("python-test-user", "password"),
+                  verify=False)
+
+
+@pytest.fixture
+def client_with_props():
+    return Client(host="localhost", port=8030, username="admin", password="admin")

tests/conftest.py

@@ -1,20 +1,20 @@
 from requests_toolbelt.multipart.decoder import MultipartDecoder
 
 
-def test_eval(test_session):
+def test_eval(client):
     """
-    This shows how a user would do an eval today. It's a good example of how a multipart/mixed 
-    response is a little annoying to deal with, as it requires using the requests_toolbelt 
-    library and a class called MultipartDecoder. 
+    This shows how a user would do an eval today. It's a good example of how a multipart/mixed
+    response is a little annoying to deal with, as it requires using the requests_toolbelt
+    library and a class called MultipartDecoder.
 
     Client support for this might look like this:
     response = client.eval.xquery("<hello>world</hello>")
 
     And then it's debatable whether we want to do anything beyond what MultipartDecoder
     is doing for handling the response.
     """
-    response = test_session.post(
-        "http://localhost:8030/v1/eval",
+    response = client.post(
+        "v1/eval",
         headers={"Content-type": "application/x-www-form-urlencoded"},
         data={"xquery": "<hello>world</hello>"},
     )

tests/test_eval.py

@@ -1,16 +1,16 @@
 from requests_toolbelt.multipart.decoder import MultipartDecoder
 
 
-def test_get_docs(test_session):
+def test_get_docs(client):
     """
     Possible future client interface:
     array_of_documents = client.documents.get(uri=[], metadata=True)
 
     Where each Document in the array would have fields of:
     uri/content/collections/permissions/quality/properties/metadata_values.
     """
-    response = test_session.get(
-        "http://localhost:8030/v1/documents",
+    response = client.get(
+        "/v1/documents",
         params={
             "uri": ["/doc1.json", "/doc2.xml"],
             "category": ["content", "metadata"],
@@ -19,20 +19,21 @@ def test_get_docs(test_session):
         headers={"Accept": "multipart/mixed"},
     )
 
+    assert 200 == response.status_code
+
     # Could provide a class for converting a multipart/mixed response into an array
     # of documents too:
     # from marklogic import DocumentDecoder
     # array_of_documents = DocumentDecoder.from_response(response)
-
     decoder = MultipartDecoder.from_response(response)
     for part in decoder.parts:
         print(part.headers)
         print(part.text)
 
 
-def test_search_docs(test_session):
-    response = test_session.get(
-        "http://localhost:8030/v1/search",
+def test_search_docs(client_with_props):
+    response = client_with_props.get(
+        "v1/search",
         params={
             "collection": "test-data",
             "category": ["content", "metadata"],
@@ -44,3 +45,10 @@ def test_search_docs(test_session):
     for part in MultipartDecoder.from_response(response).parts:
         print(part.headers)
         print(part.text)
+
+
+def test_get_docs_basic_auth(basic_client):
+    # Just verifies that basic auth works as expected.
+    response = basic_client.get("/v1/documents", params={"uri": "/doc1.json"})
+    assert 200 == response.status_code
+    assert "world" == response.json()["hello"]

tests/test_get_documents.py

@@ -1,5 +1,5 @@
-def test_search(test_session):
-    response = test_session.get("http://localhost:8030/v1/search")
+def test_search(client):
+    response = client.get("v1/search")
     assert 200 == response.status_code
     assert "application/xml; charset=utf-8" == response.headers["Content-type"]
     assert response.text.startswith("<search:response")

tests/test_search.py

@@ -1,18 +1,14 @@
-import requests
-
-
-def test_verify_false():
+def test_verify_false(ssl_client):
     """
-    The certificate verification in requests is fairly picky; while it's possible to disable
-    hostname validation, I did not find a way to ask it to not care about self-signed certificates.
-    So for now, this is just verifying that verify=False works with a MarkLogic app server that is
-    using a self-signed certificate. In the real world, a customer would have a real certificate and
-    would configure "verify" to point to that.
+    The certificate verification in requests is fairly picky; while it's
+    possible to disable hostname validation, I did not find a way to ask
+    it to not care about self-signed certificates. So for now, this is just
+    verifying that verify=False works with a MarkLogic app server that is
+    using a self-signed certificate. In the real world, a customer would
+    have a real certificate and would configure "verify" to point to that.
     """
-    response = requests.get(
-        "https://localhost:8031/v1/search",
-        auth=("python-test-user", "password"),
-        verify=False,
+    response = ssl_client.get(
+        "v1/search",
         headers={"Accept": "application/json"},
     )
     assert 200 == response.status_code