Skip to content

Commit 0840495

Browse files
rjrudinrjrudin
committed
Reorganizing docs and some fixes
The "Getting Started" guide wasn't really that; separated it out into a couple other pages. Fixed some issues with bad links as well and some bad grammar. Also using the same text in the README and the docs/index page for describing the client.
1 parent e24e0bf commit 0840495

File tree

8 files changed

+98
-61
lines changed

8 files changed

+98
-61
lines changed

‎README.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,17 @@
1-
User guide will be here soon. See the CONTRIBUTING.md guide for instructions on developing the client.
1+
# MarkLogic Python Client
2+
3+
The [Python `requests` library](https://pypi.org/project/requests/) allows Python developers to easily create
4+
applications that communicate with the [MarkLogic REST API](https://docs.marklogic.com/guide/rest-dev). The
5+
MarkLogic Python Client further simplifies usage of the `requests` library by supporting common authentication
6+
strategies with MarkLogic and improving the user experience with some of the more common endpoints in the MarkLogic
7+
REST API.
8+
9+
An instance of the client can be easily created and then used in the exact same way as the `requests` API:
10+
11+
```
12+
from marklogic import Client
13+
client = Client("http://localhost:8000", digest=("python-user", "pyth0n"))
14+
response = client.get("/v1/search", params={"q": "marklogic and python", "pageLength": 100})
15+
```
16+
17+
Please see [the user guide](https://marklogic.github.io/marklogic-python-client/) to start using the client.

docs/getting-started.md renamed to docs/creating-client.md

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,26 @@
11
---
22
layout: default
3-
title: Getting Started
4-
nav_order: 2
3+
title: Creating a client
4+
nav_order: 3
5+
permalink: /client
56
---
67

7-
**Until the 1.0 release is available**, please follow the instructions in the CONTRIBUTING.md file for installing the
8-
MarkLogic Python client into a Python virtual environment.
9-
10-
## Connecting to MarkLogic
11-
128
The `Client` class is the primary API to interact with in the MarkLogic Python client. The
139
`Client` class extends the `requests`
1410
[`Session` class](https://docs.python-requests.org/en/latest/user/advanced/#session-objects), thus exposing all methods
1511
found in both the `Session` class and the `requests` API. You can therefore use a `Client` object in the same manner
1612
as you'd use either the `Session` class or the `requests` API.
1713

18-
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.
19-
To do so, please go to the Admin application for your MarkLogic instance - e.g. if you are running MarkLogic locally,
20-
this will be at <http://localhost:8001>, and you will authenticate as your "admin" user. Then perform the following
21-
steps to create a new user:
22-
23-
1. Click on "Users" in the "Security" box.
24-
2. Click on "Create".
25-
3. In the form, enter "python-user" for "User Name" and "pyth0n" as the password.
26-
4. Scroll down until you see the "Roles" section. Click on the "rest-reader" and "rest-writer" checkboxes.
27-
5. Scroll to the top or bottom and click on "OK" to create the user.
14+
## Creating a client
2815

29-
A `Client` instance can be constructed either by providing a base URL for all requests along with authentication:
16+
A `Client` instance can be created either by providing a base URL for all requests along with authentication:
3017

3118
```
3219
from marklogic import Client
3320
client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
3421
```
3522

36-
Or via separate arguments for each of the parts of a base URL:
23+
Or via separate arguments for each part of a base URL:
3724

3825
```
3926
from marklogic import Client

‎docs/example-setup.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
layout: default
3+
title: Setup for examples
4+
nav_order: 2
5+
permalink: /setup
6+
---
7+
8+
The examples in this documentation depend on a particular MarkLogic username and password. If you
9+
would like to try these examples out against your own installation of MarkLogic, you will need to create this
10+
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 authenticate as your "admin" user.
11+
Then perform the following steps to create a new user:
12+
13+
1. Click on "Users" in the "Security" box.
14+
2. Click on "Create".
15+
3. In the form, enter "python-user" for "User Name" and "pyth0n" as the password.
16+
4. Scroll down until you see the "Roles" section. Click on the "rest-reader" and "rest-writer" checkboxes.
17+
5. Scroll to the top or bottom and click on "OK" to create the user.
18+
19+
You can verify that you correctly created the user by accessing the REST API for the out-of-the-box REST API
20+
server in MarkLogic that listens on port 8000. Go to <http://localhost:8000/v1/search> (changing "localhost" to
21+
the correct name of your MarkLogic host if you are not running it locally) in a web browser and enter the
22+
username and password for the new user you created. The browser should then display a search response returned by
23+
MarkLogic, verifying that the user is able to access the MarkLogic REST API.

‎docs/index.md‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,28 @@ title: Introduction
44
nav_order: 1
55
---
66

7-
The MarkLogic Python Client further simplifies usage of the
8-
[Python `requests` library](https://pypi.org/project/requests/) when developing applications in Python that communicate
9-
with the [MarkLogic REST API](https://docs.marklogic.com/guide/rest-dev).
7+
**Until the 1.0 release is available**, please follow the instructions in the CONTRIBUTING.md file for installing the
8+
MarkLogic Python client into a Python virtual environment (this notice will be removed before the release).
109

11-
See the [Getting Started guide](getting-started.md) to begin using the client.
10+
The [Python `requests` library](https://pypi.org/project/requests/) allows Python developers to easily create
11+
applications that communicate with the [MarkLogic REST API](https://docs.marklogic.com/guide/rest-dev). The
12+
MarkLogic Python Client further simplifies usage of the `requests` library by supporting common authentication
13+
strategies with MarkLogic and improving the user experience with some of the more common endpoints in the MarkLogic
14+
REST API.
15+
16+
An instance of the client can be easily created and then used in the exact same way as the `requests` API:
17+
18+
```
19+
from marklogic import Client
20+
client = Client("http://localhost:8000", digest=("python-user", "pyth0n"))
21+
response = client.get("/v1/search", params={"q": "marklogic and python", "pageLength": 100})
22+
```
23+
24+
The example above and the examples throughout this documentation depend on a MarkLogic user named "python-user".
25+
If you wish to try these examples on your own installation of MarkLogic, please see [the setup guide](/setup)
26+
for instructions on creating this user.
27+
28+
Otherwise, please see the [guide on creating a client](/client) for more information on connecting to a
29+
MarkLogic REST API instance. The [guide on managing documents](/documents) provides
30+
more information on how the client simplifies writing and reading multiple documents in a single request.
1231

‎docs/managing-documents/managing-documents.md‎

Lines changed: 3 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,12 @@
11
---
22
layout: default
3-
title: Managing Documents
3+
title: Managing documents
44
nav_order: 3
55
has_children: true
6-
permalink: /docs/managing-documents
6+
permalink: /documents
77
---
88

9-
The [/v1/documents endpoint](https://docs.marklogic.com/REST/client/management) in the MarkLogic REST API simplifies
9+
The [/v1/documents endpoint](https://docs.marklogic.com/REST/client/management) in the MarkLogic REST API supports
1010
operations that involve writing or reading a single document. It also supports operations that involve multiple
1111
documents, though those require use of a potentially complex multipart HTTP request or response. The MarkLogic Python
1212
client simplifies those operations by hiding the details of multipart requests and responses.
13-
14-
## Setup for examples
15-
16-
The examples shown in [Reading Documents](reading.md) and [Searching Documents](searching.md) assume that you have
17-
created a new MarkLogic user named "python-user" as described in the [Getting Started](getting-started.md) guide.
18-
The examples also depend on documents being created by the below script. If you would like to run each of the examples,
19-
please run the script below, which will create a `Client` instance that interacts with the out-of-the-box "Documents"
20-
database in MarkLogic.
21-
22-
```
23-
from marklogic import Client
24-
from marklogic.documents import Document, DefaultMetadata
25-
26-
client = Client('http://localhost:8000', digest=('python-user', 'pyth0n'))
27-
client.documents.write([
28-
DefaultMetadata(permissions={"rest-reader": ["read", "update"]}, collections=["python-example"]),
29-
Document("/doc1.json", {"text": "example one"}),
30-
Document("/doc2.json", {"text": "example two"})
31-
])
32-
```

‎docs/managing-documents/reading.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
---
22
layout: default
3-
title: Reading Documents
4-
parent: Managing Documents
5-
nav_order: 3
3+
title: Reading documents
4+
parent: Managing documents
5+
nav_order: 2
6+
permalink: /documents/reading
67
---
78

89
The [GET /v1/documents](https://docs.marklogic.com/REST/GET/v1/documents) endpoint in the MarkLogic REST API supports
@@ -12,8 +13,9 @@ handling the response by converting it into a list of `Document` instances via t
1213
## Setup for examples
1314

1415
The examples below all assume that you have created a new MarkLogic user named "python-user" as described in the
15-
[Getting Started](getting-started.md) guide. To run these examples, please run the following script first, which will
16+
[setup guide](/setup). To run these examples, please run the following script first, which will
1617
create a `Client` instance that interacts with the out-of-the-box "Documents" database in MarkLogic:
18+
1719
```
1820
from marklogic import Client
1921
from marklogic.documents import Document, DefaultMetadata

‎docs/managing-documents/searching.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
---
22
layout: default
3-
title: Searching Documents
4-
parent: Managing Documents
3+
title: Searching documents
4+
parent: Managing documents
55
nav_order: 3
6+
permalink: /documents/searching
67
---
78

89
The [POST /v1/search endpoint](https://docs.marklogic.com/REST/POST/v1/search) in the MarkLogic REST API supports
@@ -14,8 +15,9 @@ via the `client.documents.search` method.
1415
## Setup for examples
1516

1617
The examples below all assume that you have created a new MarkLogic user named "python-user" as described in the
17-
[Getting Started](getting-started.md) guide. To run these examples, please run the following script first, which will
18+
[setup guide](/setup). To run these examples, please run the following script first, which will
1819
create a `Client` instance that interacts with the out-of-the-box "Documents" database in MarkLogic:
20+
1921
```
2022
from marklogic import Client
2123
from marklogic.documents import Document, DefaultMetadata
@@ -122,7 +124,7 @@ docs = client.documents.search(collections=["python-example"])
122124
assert len(docs) == 2
123125
```
124126

125-
Similar to [reading documents](reading.md), you can use the `categories` argument to control what is returned for
127+
Similar to [reading documents](/documents/reading), you can use the `categories` argument to control what is returned for
126128
each matching document:
127129

128130
```
@@ -146,7 +148,7 @@ docs = client.documents.search("example", params={"database": "Documents"})
146148
assert len(docs) == 2
147149
```
148150

149-
# Error handling
151+
## Error handling
150152

151153
A POST call to the /v1/search endpoint in MarkLogic will return an HTTP response with a status code of 200 for a
152154
successful request. For any other status code, the `client.documents.search` method will the `requests` `Response` object,

‎docs/managing-documents/writing.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
---
22
layout: default
3-
title: Writing Documents
4-
nav_order: 2
5-
parent: Managing Documents
3+
title: Writing documents
4+
nav_order: 1
5+
parent: Managing documents
6+
permalink: /documents/writing
67
---
78

89
The [POST /v1/documents](https://docs.marklogic.com/REST/POST/v1/documents) endpoint in the MarkLogic REST API supports
910
writing multiple documents with metadata via a multipart HTTP request. The MarkLogic Python client
1011
simplifies the use of this endpoint via the `client.documents.write` method and the `Document`
1112
class. The examples below all assume that you have constructed a `Client` instance already as described in the
12-
[Getting Started](getting-started.md) guide.
13+
[setup guide](/setup).
1314

1415
## Writing documents with metadata
1516

@@ -96,7 +97,7 @@ that occurs most recently before it in the list (if one exists).
9697
## Additional control over writing a document
9798

9899
The "Usage Notes" section in the [POST /v1/documents documentation](https://docs.marklogic.com/REST/POST/v1/documents)
99-
describes how several parameters can be used to control how each document is written. Those inputs are:
100+
describes how several parameters can be used to control how each document is written. Those parameters are:
100101

101102
1. `extension` = a URI suffix for use when [MarkLogic generates the URI](https://docs.marklogic.com/guide/rest-dev/bulk#id_86768).
102103
2. `directory` = a URI prefix for use when MarkLogic generates the URI.
@@ -113,3 +114,10 @@ URI beginning with "/example/" and ending with ".json", with MarkLogic adding a
113114
construct the URI:
114115

115116
client.documents.write([Document(null, {"doc": 1}, extension=".json", directory="/example/")])
117+
118+
## Error handling
119+
120+
Because the `client.documents.write` method returns a `requests Response` object, any error that occurs during
121+
processing of the request will be captured within that `Response` object. The client does not attempt to provide any
122+
additional information, as the MarkLogic REST API will already provide details within the response body and potentially
123+
the response headers as well.

0 commit comments

Comments
 (0)