Merge pull request #16 from marklogic/feature/514-read-write-docs

DEVEXP-514 Added docs for reading, writing, and searching

Author: rjrudin

docs/getting-started.md

@@ -9,73 +9,100 @@ 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.
 
+To try out any of the examples below or in the rest of this guide, you will first need to create a new MarkLogic user. 
+To do so, please go to the Admin application for your MarkLogic instance - e.g. if you are running MarkLogic locally, 
+this will be at <http://localhost:8001>, and you will authenticate as your "admin" user. Then perform the following 
+steps to create a new user:
+
+1. Click on "Users" in the "Security" box.
+2. Click on "Create".
+3. In the form, enter "python-user" for "User Name" and "pyth0n" as the password. 
+4. Scroll down until you see the "Roles" section. Click on the "rest-reader" and "rest-writer" checkboxes. 
+5. Scroll to the top or bottom and click on "OK" to create the user.
+
 A `Client` instance can be constructed either by providing a base URL for all requests along with authentication:
 
-    from marklogic import Client
-    client = Client('http://localhost:8030', digest=('username', 'password'))
+```
+from marklogic import Client
+client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
+```
 
 Or via separate arguments for each of the parts of a base URL:
 
-    from marklogic import Client
-    client = Client(host='localhost', port='8030', digest=('username', 'password'))
+```
+from marklogic import Client
+client = Client(host='localhost', port='8000', digest=('python-user', 'pyth0n'))
+```
 
 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'})
+```
+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'})
+```
+with Client('http://localhost:8000', digest=('python-user', 'pyth0n')) 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 import Client
-    client = Client('http://localhost:8030', digest=('username', 'password'))
+```
+from marklogic import Client
+client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
+```
 
 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 import Client
-    client = Client('http://localhost:8030', auth=('username', 'password'))
+```
+from marklogic import Client
+client = Client('http://localhost:8000', auth=('python-user', 'pyth0n'))
+```
 
 ### MarkLogic Cloud Authentication
 
 When connecting to a [MarkLogic Cloud instance](https://developer.marklogic.com/products/cloud/), you will need to set 
 the `cloud_api_key` and `base_path` arguments. You only need to specify a `host` as well, as port 443 and HTTPS will be
 used by default. For example:
 
-    from marklogic import Client
-    client = Client(host='example.marklogic.cloud', cloud_api_key='some-key-value', base_path='/ml/example/manage')
+```
+from marklogic import Client
+client = Client(host='example.marklogic.cloud', cloud_api_key='some-key-value', base_path='/ml/example/manage')
+```
 
 You may still use a full base URL if you wish:
 
-    from marklogic import Client
-    client = Client('https://example.marklogic.cloud', cloud_api_key='some-key-value', base_path='/ml/example/manage')
+```
+from marklogic import Client
+client = Client('https://example.marklogic.cloud', cloud_api_key='some-key-value', base_path='/ml/example/manage')
+```
 
 MarkLogic Cloud uses an access token for authentication; the access token is generated using the API key value. In some 
 scenarios, you may wish to set the token expiration time to a value other than the default used by MarkLogic Cloud. To 
 do so, set the `cloud_token_duration` argument to a number greater than zero that defines the token duration in 
 minutes:
 
-    from marklogic import Client
-    # Sets a token duration of 10 minutes.
-    client = Client(host='example.marklogic.cloud', cloud_api_key='some-key-value', base_path='/ml/example/manage', 
-        cloud_token_duration=10)
+```
+from marklogic import Client
+# Sets a token duration of 10 minutes.
+client = Client(host='example.marklogic.cloud', cloud_api_key='some-key-value', base_path='/ml/example/manage', 
+    cloud_token_duration=10)
+```
 
 ## SSL 
 
@@ -84,10 +111,14 @@ Configuring SSL connections is the same as
 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 import Client
-    client = Client('https://localhost:8030', digest=('username', 'password'), verify='/path/to/cert.pem')
+```
+from marklogic import Client
+client = Client('https://localhost:8000', digest=('python-user', 'pyth0n'), verify='/path/to/cert.pem')
+```
 
 When specifying the base URL via separate arguments, the `scheme` argument can be set for HTTPS connections:
 
-    from marklogic import Client
-    client = Client(host='localhost', port='8030', scheme='https', digest=('username', 'password'), verify=False)
+```
+from marklogic import Client
+client = Client(host='localhost', port='8000', scheme='https', digest=('python-user', 'pyth0n'), verify=False)
+```

docs/index.md

@@ -7,3 +7,6 @@ nav_order: 1
 The MarkLogic Python Client further simplifies usage of the 
 [Python `requests` library](https://pypi.org/project/requests/) when developing applications in Python that communicate
 with the [MarkLogic REST API](https://docs.marklogic.com/guide/rest-dev). 
+
+See the [Getting Started guide](getting-started.md) to begin using the client.
+

docs/managing-documents/managing-documents.md

@@ -0,0 +1,32 @@
+---
+layout: default
+title: Managing Documents
+nav_order: 3
+has_children: true
+permalink: /docs/managing-documents
+---
+
+The [/v1/documents endpoint](https://docs.marklogic.com/REST/client/management) in the MarkLogic REST API simplifies
+operations that involve writing or reading a single document. It also supports operations that involve multiple 
+documents, though those require use of a potentially complex multipart HTTP request or response. The MarkLogic Python
+client simplifies those operations by hiding the details of multipart requests and responses.
+
+## Setup for examples
+
+The examples shown in [Reading Documents](reading.md) and [Searching Documents](searching.md) assume that you have 
+created a new MarkLogic user named "python-user" as described in the [Getting Started](getting-started.md) guide. 
+The examples also depend on documents being created by the below script. If you would like to run each of the examples, 
+please run the script below, which will create a `Client` instance that interacts with the out-of-the-box "Documents"
+database in MarkLogic.
+
+```
+from marklogic import Client
+from marklogic.documents import Document, DefaultMetadata
+
+client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
+client.documents.write([
+    DefaultMetadata(permissions={"rest-reader": ["read", "update"]}, collections=["python-example"]),
+    Document("/doc1.json", {"text": "example one"}),
+    Document("/doc2.json", {"text": "example two"})
+])
+```

docs/managing-documents/reading.md

@@ -0,0 +1,94 @@
+---
+layout: default
+title: Reading Documents
+parent: Managing Documents
+nav_order: 3
+---
+
+The [GET /v1/documents](https://docs.marklogic.com/REST/GET/v1/documents) endpoint in the MarkLogic REST API supports
+reading multiple documents with metadata via a multipart/mixed HTTP response. The MarkLogic Python client simplifies
+handling the response by converting it into a list of `Document` instances via the `client.documents.read` method. 
+
+## Setup for examples
+
+The examples below all assume that you have created a new MarkLogic user named "python-user" as described in the 
+[Getting Started](getting-started.md) guide. To run these examples, please run the following script first, which will 
+create a `Client` instance that interacts with the out-of-the-box "Documents" database in MarkLogic:
+```
+from marklogic import Client
+from marklogic.documents import Document, DefaultMetadata
+
+client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
+client.documents.write([
+    DefaultMetadata(permissions={"rest-reader": ["read", "update"]}, collections=["python-example"]),
+    Document("/doc1.json", {"text": "example one"}),
+    Document("/doc2.xml", "<text>example two</text>"),
+    Document("/doc3.bin", b"binary example", permissions={"rest-reader": ["read", "update"]})
+])
+```
+
+## Reading documents
+
+A list of `Document` instances can be obtained for a list of URIs, where each `Document` has its `uri` and `content`
+attributes populated but no metadata by default:
+
+```
+docs = client.documents.read(["/doc1.json", "/doc2.xml", "/doc3.bin"])
+assert len(docs) == 3
+```
+
+The [requests toolbelt](https://toolbelt.readthedocs.io/en/latest/) library is used to process the multipart
+HTTP response returned by MarkLogic. By default, the `content` attribute of each `Document` will be a binary value. 
+The client will convert this into something more useful based on the content types in the table below:
+
+| Content type | `content` attribute type |
+| --- | --- |
+| application/json | dictionary |
+| application/xml | string |
+| text/xml | string | 
+| text/plain | string |
+
+Thus, the `Document` with a URI of "/doc1.json" will have a dictionary as the value of its 
+`content` attribute. The `Document` with a URI of "/doc2.xml" will have a string as the value of its `content`
+attribute. And the `Docuemnt` with a URI of "/doc3.bin" will have a binary value for its `content` attribute.
+
+A `Document` instance can be examined simply by printing or logging it; this will display all of the instance's 
+changeable attributes, including the URI, content, and metadata:
+
+```
+doc = docs[0]
+print(doc)
+
+# Can always built-in Python vars method.
+print(vars(doc))
+```
+
+## Reading documents with metadata
+
+Metadata for each document can be retrieved via the `categories` argument. The acceptable values for this argument
+match those of the `category` parameter in the [GET /v1/documents](https://docs.marklogic.com/REST/GET/v1/documents)
+documentation: `content`, `metadata`, `metadata-values`, `collections`, `permissions`, `properties`, and `quality`.
+
+The following shows different examples of configuring the `categories` argument:
+
+```
+uris = ["/doc1.json", "/doc2.xml", "/doc3.bin"]
+
+# Retrieve content and all metadata for each document.
+docs = client.documents.read(uris, categories=["content", "metadata"])
+print(docs)
+
+# Retrieve content, collections, and permissions for each document.
+docs = client.documents.read(uris, categories=["content", "collections", "permissions"])
+print(docs)
+
+# Retrieve only collections for each document; the content attribute will be None.
+docs = client.documents.read(uris, categories=["collections"])
+print(docs)
+```
+
+# Error handling
+
+A GET call to the /v1/documents endpoint in MarkLogic will return an HTTP response with a status code of 200 for a
+successful request. For any other status code, the `client.documents.read` method will the `requests` `Response` object,
+providing access to the error details returned by MarkLogic.