mlclient package

The ML Client package.

The root package of Python API to manage MarkLogic instance. It contains the most generic modules:

ml_config
The ML Configuration module.

ml_manager
The ML Manager module.

ml_response_parser
The ML Response Parser module.

constants
The ML Client Constants module.

mimetypes
The ML Client Mimetypes module.

exceptions
The ML Client Exceptions module.

utils
The ML Client Utils module.

This package exports the following classes:

MLClient
A low-level class used to send simple HTTP requests to a MarkLogic instance.
MLResourceClient
A MLClient subclass calling ResourceCall implementation classes.
MLResourcesClient
A MLResourceClient subclass supporting REST Resources of the MarkLogic server.
MLConfiguration
A class representing MarkLogic configuration.
MLManager
A high-level class managing a MarkLogic instance.
MLResponseParser
A MarkLogic HTTP response parser.

Examples

>>> from mlclient import MLResourcesClient

class mlclient.MLClient(protocol: str = 'http', host: str = 'localhost', port: int = 8002, auth_method: str = 'basic', username: str = 'admin', password: str = 'admin', retry: Retry = Retry(total=10, connect=5, read=None, redirect=None, status=None))[source]

Bases: object

A low-level class used to send simple HTTP requests to a MarkLogic instance.

Using configuration details provided it allows you to hit MarkLogic’s endpoints. It can connect with the MarkLogic Server as a Context Manager or explicitly by using the connect method.

protocol

a protocol used for HTTP requests (http / https)

Type:: str

host

a host name

Type:: str

port

an App Service port

Type:: int

auth_method

an authorization method (basic / digest)

Type:: str

username

a username

Type:: str

password

a password

Type:: str

base_url

a base url built based on the protocol, the host name and the port provided

Type:: str

Examples

>>> from mlclient import MLClient
>>> config = {
...     "host": "localhost",
...     "port": 8002,
...     "username": "admin",
...     "password": "admin",
... }
>>> with MLClient(**config) as client:
...     resp = client.post(
...         endpoint="/v1/eval",
...         body={"xquery": "xdmp:database() => xdmp:database-name()"})
...     print(resp.text)
...
--6a5df7d535c71968
Content-Type: text/plain
X-Primitive: string
App-Services
--6a5df7d535c71968--

connect()[source]: Start an HTTP session.

delete_(endpoint: str, params: dict | None = None, headers: dict | None = None) → Response | None[source]

Send a DELETE request.

Parameters:

endpoint (str) – A REST endpoint to call
params (dict) – Request parameters
headers (dict) – Request headers

Returns:

An HTTP response

Return type:

Response

disconnect()[source]: Close an HTTP session.

get(endpoint: str, params: dict | None = None, headers: dict | None = None) → Response | None[source]

Send a GET request.

Parameters:

endpoint (str) – A REST endpoint to call
params (dict) – Request parameters
headers (dict) – Request headers

Returns:

An HTTP response

Return type:

Response

is_connected() → bool[source]

Return a connection status.

Returns:: True if the client has started a connection; otherwise False
Return type:: bool

Send a POST request.

Parameters:

endpoint (str) – A REST endpoint to call
params (dict) – Request parameters
headers (dict) – Request headers
body (str | dict) – A request body

Returns:

An HTTP response

Return type:

Response

Send a PUT request.

Parameters:

endpoint (str) – A REST endpoint to call
params (dict) – Request parameters
headers (dict) – Request headers
body (str | dict) – A request body

Returns:

An HTTP response

Return type:

Response

request(method: str, endpoint: str, params: dict | None = None, headers: dict | None = None, body: str | dict | None = None)[source]

Send an HTTP request.

Parameters:

method (str) – An HTTP request method
endpoint (str) – A REST endpoint to call
params (dict) – Request parameters
headers (dict) – Request headers
body (str | dict) – A request body

Returns:

An HTTP response

Return type:

Response

class mlclient.MLManager(environment_name: str)[source]

Bases: object

A high-level class managing a MarkLogic instance.

It combines MLConfiguration and MLClient components to simplify every action to perform on your instance.

property config: MLConfiguration

A MarkLogic configuration.

Returns:: A MarkLogic configuration
Return type:: MLConfiguration

property environment_name: str

An MLClient configuration environment name.

Returns:: An MLClient configuration environment name.
Return type:: str

get_client(app_server_id: str) → MLClient[source]

Initialize an MLClient instance for a specific App Server.

Parameters:: app_server_id (str) – An App Server identifier
Returns:: An MLClient instance
Return type:: MLClient

get_documents_client(app_server_id: str | None = None) → DocumentsClient[source]

Initialize a DocumentsClient instance for a specific App Server.

If the no identifier is provided - it returns a client of a first configured REST server within an environment.

Parameters:

app_server_id (str | None, default None) – An App Server identifier

Returns:

A DocumentsClient instance

Return type:

DocumentsClient

Raises:

NotARestServerError – If the App-Server identifier does not point to a REST server
NoRestServerConfiguredError – If an identifier has not been provided and there’s no REST servers configured for the environment

get_eval_client(app_server_id: str | None = None) → EvalClient[source]

Initialize a EvalClient instance for a specific App Server.

If the no identifier is provided - it returns a client of a first configured REST server within an environment.

Parameters:

app_server_id (str | None, default None) – An App Server identifier

Returns:

A EvalClient instance

Return type:

EvalClient

Raises:

NotARestServerError – If the App-Server identifier does not point to a REST server
NoRestServerConfiguredError – If an identifier has not been provided and there’s no REST servers configured for the environment

get_logs_client(app_server_id: str | None = None) → LogsClient[source]

Initialize a LogsClient instance for a specific App Server.

If the no identifier is provided - it returns a client of a first configured REST server within an environment.

Parameters:

app_server_id (str | None, default None) – An App Server identifier

Returns:

A LogsClient instance

Return type:

LogsClient

Raises:

NotARestServerError – If the App-Server identifier does not point to a REST server
NoRestServerConfiguredError – If an identifier has not been provided and there’s no REST servers configured for the environment

get_resources_client(app_server_id: str | None = None) → MLResourcesClient[source]

Initialize an MLResourcesClient instance for a specific App Server.

If the no identifier is provided - it returns a client of a first configured REST server within an environment.

Parameters:

app_server_id (str | None, default None) – An App Server identifier

Returns:

An MLResourcesClient instance

Return type:

MLResourcesClient

Raises:

NotARestServerError – If the App-Server identifier does not point to a REST server
NoRestServerConfiguredError – If an identifier has not been provided and there’s no REST servers configured for the environment

class mlclient.MLResourceClient(protocol: str = 'http', host: str = 'localhost', port: int = 8002, auth_method: str = 'basic', username: str = 'admin', password: str = 'admin', retry: Retry = Retry(total=10, connect=5, read=None, redirect=None, status=None))[source]

Bases: MLClient

An MLClient subclass calling ResourceCall implementation classes.

It can connect with the MarkLogic Server as a Context Manager or explicitly by using the connect method.

You can call ML REST Resource by using the call() method accepting a ResourceCall implementation classes.

All attributes are inherited from the MLClient superclass.

Examples

>>> from mlclient import MLResourceClient
>>> from mlclient.calls import EvalCall
>>> config = {
...     "host": "localhost",
...     "port": 8002,
...     "username": "admin",
...     "password": "admin",
... }
>>> with MLResourceClient(**config) as client:
...     eval_call = EvalCall(xquery="xdmp:database() => xdmp:database-name()")
...     resp = client.call(eval_call)
...     print(resp.text)
...
--6a5df7d535c71968
Content-Type: text/plain
X-Primitive: string
App-Services
--6a5df7d535c71968--

call(call: ResourceCall) → Response[source]

Send a custom request to a MarkLogic endpoint.

Parameters:: call (ResourceCall) – A specific endpoint call implementation
Returns:: An HTTP response
Return type:: Response

class mlclient.MLResourcesClient(protocol: str = 'http', host: str = 'localhost', port: int = 8002, auth_method: str = 'basic', username: str = 'admin', password: str = 'admin', retry: Retry = Retry(total=10, connect=5, read=None, redirect=None, status=None))[source]

Bases: MLResourceClient

An MLResourceClient subclass supporting REST Resources of the MarkLogic server.

It can connect with the MarkLogic Server as a Context Manager or explicitly by using the connect method.

There are two ways to call ML REST Resources: - by using defined methods corresponding to a resource (e.g. /v1/eval -> eval()) - by using the call() method accepting a ResourceCall implementation classes.

This class can be treated as an example of MLClient class extension for your own dedicated APIs or as a superclass for your client.

All attributes are inherited from the MLClient superclass.

Examples

>>> from mlclient import MLResourcesClient
>>> config = {
...     "host": "localhost",
...     "port": 8002,
...     "username": "admin",
...     "password": "admin",
... }
>>> with MLResourcesClient(**config) as client:
...     resp = client.eval(xquery="xdmp:database() => xdmp:database-name()")
...     print(resp.text)
...
--6a5df7d535c71968
Content-Type: text/plain
X-Primitive: string
App-Services
--6a5df7d535c71968--

delete_database(database: str, forest_delete: str | None = None) → Response[source]

Send a DELETE request to the /manage/v2/databases/{id|name} endpoint.

Parameters:

database (str) – A database identifier. The database can be identified either by ID or name.
forest_delete (str) – Specifies to delete the forests attached to the database. If unspecified, the forests will not be affected. If “configuration” is specified, the forest configuration will be removed but public forest data will remain. If “data” is specified, the forest configuration and data will be removed.

Returns:

An HTTP response

Return type:

Response

Send a DELETE request to the /v1/documents endpoint.

Parameters:

uri (str | list) – One or more URIs for documents in the database. If you specify multiple URIs, the Accept header must be multipart/mixed.
database (str) – Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the “eval-in” privilege.
category (str | list) – The category of data to fetch about the requested document. Category can be specified multiple times to retrieve any combination of content and metadata. Valid categories: content (default), metadata, metadata-values, collections, permissions, properties, and quality. Use metadata to request all categories except content.
txid (str) – The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
temporal_collection (str) – Specify the name of a temporal collection into which the documents are to be inserted.
system_time (str) – Set the system start time for the insertion or update. This time will override the system time set by MarkLogic. Ignored if temporal-collection is not included in the request.
wipe_temporal (bool) – Remove all versions of a temporal document rather than performing a temporal delete. You can only use this parameter when you also specify a temporal-collection parameter.

Returns:

An HTTP response

Return type:

Response

delete_forest(forest: str, level: str, replicas: str | None = None) → Response[source]

Send a DELETE request to the /manage/v2/forests/{id|name} endpoint.

Parameters:

forest (str) – A forest identifier. The forest can be identified either by ID or name.
level (str) – The type of state change to initiate. Allowed values: full, config-only. A config-only deletion removes only the forest configuration; the data contained in the forest remains on disk. A full deletion removes both the forest configuration and the data.
replicas (str) – Determines how to process the replicas. Allowed values: detach to detach the replica but keep it; delete to detach and delete the replica.

Returns:

An HTTP response

Return type:

Response

delete_role(role: str) → Response[source]

Send a DELETE request to the /manage/v2/roles/{id|name} endpoint.

Parameters:: role (str) – A role identifier. The role can be identified either by ID or name.
Returns:: An HTTP response
Return type:: Response

delete_server(server: str, group_id: str) → Response[source]

Send a DELETE request to the /manage/v2/servers/{id|name} endpoint.

Parameters:

server (str) – A server identifier. The server can be identified either by ID or name.
group_id (str) – The id or name of the group to which the App Server belongs. This parameter is required.

Returns:

An HTTP response

Return type:

Response

delete_user(user: str) → Response[source]

Send a DELETE request to the /manage/v2/users/{id|name} endpoint.

Parameters:: user (str) – A user identifier. The user can be identified either by ID or name.
Returns:: An HTTP response
Return type:: Response

Send a POST request to the /v1/eval endpoint.

Parameters:

xquery (str) – The query to evaluate, expressed using XQuery. You must include either this parameter or the javascript parameter, but not both.
javascript (str) – The query to evaluate, expressed using server-side JavaScript. You must include either this parameter or the xquery parameter, but not both.
variables – External variables to pass to the query during evaluation
database – Perform this operation on the named content database instead of the default content database associated with the REST API instance. The database can be identified by name or by database id.
txid – The transaction identifier of the multi-statement transaction in which to service this request.

Returns:

An HTTP response

Return type:

Response

get_database(database: str, data_format: str | None = None, view: str | None = None) → Response[source]

Send a GET request to the /manage/v2/databases/{id|name} endpoint.

Parameters:

database (str) – A database identifier. The database can be identified either by ID or name.
data_format (str) – The format of the returned data. Can be either html, json, or xml (default). This parameter is not meaningful with view=edit.
view (str) – A specific view of the returned data. Can be properties-schema, package, describe, config, counts, edit, status, forest-storage, or default.

Returns:

An HTTP response

Return type:

Response

get_database_properties(database: str, data_format: str | None = None) → Response[source]

Send a GET request to the /manage/v2/databases/{id|name}/properties endpoint.

Parameters:

database (str) – A database identifier. The database can be identified either by ID or name.
data_format (str) – The format of the returned data. Can be either json or xml (default). This parameter overrides the Accept header if both are present.

Returns:

An HTTP response

Return type:

Response

get_databases(data_format: str | None = None, view: str | None = None) → Response[source]

Send a GET request to the /manage/v2/databases endpoint.

Parameters:

data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
view (str) – A specific view of the returned data. Can be schema, properties-schema, metrics, package, describe, or default.

Returns:

An HTTP response

Return type:

Response

Send a GET request to the /v1/documents endpoint.

Parameters:

uri (str | list) – One or more URIs for documents in the database. If you specify multiple URIs, the Accept header must be multipart/mixed.
database (str) – Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the “eval-in” privilege.
category (str) – The category of data to fetch about the requested document. Category can be specified multiple times to retrieve any combination of content and metadata. Valid categories: content (default), metadata, metadata-values, collections, permissions, properties, and quality. Use metadata to request all categories except content.
data_format (str) – The expected format of metadata returned in the response. Accepted values: xml or json. This parameter does not affect document content. For metadata, this parameter overrides the MIME type in the Accept header, except when the Accept header is multipart/mixed.
timestamp (str) – A timestamp returned in the ML-Effective-Timestamp header of a previous request. Use this parameter to fetch documents based on the contents of the database at a fixed point-in-time.
transform (str) – Names a content transformation previously installed via the /config/transforms service. The service applies the transformation to all documents prior to constructing the response.
transform_params (str) – A transform parameter names and values. For example, { “myparam”: 1 }. Transform parameters are passed to the transform named in the transform parameter.
txid (str) – The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.

Returns:

An HTTP response

Return type:

Response

get_forest(forest: str, data_format: str | None = None, view: str | None = None) → Response[source]

Send a GET request to the /manage/v2/forests/{id|name} endpoint.

Parameters:

forest (str) – A forest identifier. The forest can be identified either by ID or name.
data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
view (str) – A specific view of the returned data. Can be properties-schema, config, edit, package, describe, status, xdmp:server-status or default.

Returns:

An HTTP response

Return type:

Response

get_forest_properties(forest: str, data_format: str | None = None) → Response[source]

Send a GET request to the /manage/v2/forests/{id|name}/properties endpoint.

Parameters:

forest (str) – A forest identifier. The forest can be identified either by ID or name.
data_format (str) – The format of the returned data. Can be either json or xml (default). This parameter overrides the Accept header if both are present.

Returns:

An HTTP response

Return type:

Response

Send a GET request to the /manage/v2/forests endpoint.

Parameters:

data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
view (str) – A specific view of the returned data. Can be either describe, default, status, metrics, schema, storage, or properties-schema.
database (str) – Returns a summary of the forests for the specified database. The database can be identified either by id or name.
group (str) – Returns a summary of the forests for the specified group. The group can be identified either by id or name.
host (str) – Returns a summary of the forests for the specified host. The host can be identified either by id or name.
full_refs (bool) – If set to true, full detail is returned for all relationship references. A value of false (the default) indicates to return detail only for first references.

Returns:

An HTTP response

Return type:

Response

Send a GET request to the /manage/v2/logs endpoint.

Parameters:

filename (str) – The log file to be returned.
data_format (str) – The format of the data in the log file. The supported formats are xml, json or html.
host (str) – The host from which to return the log data.
start_time (str) – The start time for the log data.
end_time (str) – The end time for the log data.
regex (str) – Filters the log data, based on a regular expression.

Returns:

An HTTP response

Return type:

Response

get_role(role: str, data_format: str | None = None, view: str | None = None) → Response[source]

Send a GET request to the /manage/v2/roles/{id|name} endpoint.

Parameters:

role (str) – A role identifier. The role can be identified either by ID or name.
data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
view (str) – A specific view of the returned data. Can be: describe, or default.

Returns:

An HTTP response

Return type:

Response

get_role_properties(role: str, data_format: str | None = None) → Response[source]

Send a GET request to the /manage/v2/roles/{id|name}/properties endpoint.

Parameters:

role (str) – A role identifier. The role can be identified either by ID or name.
data_format (str) – The format of the returned data. Can be either json or xml (default). This parameter overrides the Accept header if both are present.

Returns:

An HTTP response

Return type:

Response

get_roles(data_format: str | None = None, view: str | None = None) → Response[source]

Send a GET request to the /manage/v2/roles endpoint.

Parameters:

data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
view (str) – A specific view of the returned data. Can be: describe, or default.

Returns:

An HTTP response

Return type:

Response

Send a GET request to the /manage/v2/servers/{id|name} endpoint.

Parameters:

server (str) – A server identifier. The server can be identified either by ID or name.
group_id (str) – The id or name of the group to which the App Server belongs. This parameter is required.
data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
view (str) – A specific view of the returned data. Can be properties-schema, config, edit, package, describe, status, xdmp:server-status or default.
host_id (str) – Meaningful only when view=status. Specifies to return the status for the server in the specified host. The host can be identified either by id or name.
full_refs (bool) – If set to true, full detail is returned for all relationship references. A value of false (the default) indicates to return detail only for first references. This parameter is not meaningful with view=package.
modules (bool) – Meaningful only with view=package. Whether to include a manifest of the modules database for the App Server in the results, if one exists. It is an error to request a modules database manifest for an App Server that uses the filesystem for modules. Default: false.

Returns:

An HTTP response

Return type:

Response

get_server_properties(server: str, group_id: str, data_format: str | None = None) → Response[source]

Send a GET request to the /manage/v2/servers/{id|name}/properties endpoint.

Parameters:

server (str) – A server identifier. The server can be identified either by ID or name.
group_id (str) – The id or name of the group to which the App Server belongs. This parameter is required.
data_format (str) – The format of the returned data. Can be either json or xml (default). This parameter overrides the Accept header if both are present.

Returns:

An HTTP response

Return type:

Response

get_servers(data_format: str | None = None, group_id: str | None = None, view: str | None = None, full_refs: bool | None = None) → Response[source]

Send a GET request to the /manage/v2/servers endpoint.

Parameters:

data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
group_id (str) – Specifies to return only the servers in the specified group. The group can be identified either by id or name. If not specified, the response includes information about all App Servers.
view (str) – A specific view of the returned data. Can be schema, properties-schema, metrics, package, describe, or default.
full_refs (bool) – If set to true, full detail is returned for all relationship references. A value of false (the default) indicates to return detail only for first references. This parameter is not meaningful with view=package.

Returns:

An HTTP response

Return type:

Response

get_user(user: str, data_format: str | None = None, view: str | None = None) → Response[source]

Send a GET request to the /manage/v2/users/{id|name} endpoint.

Parameters:

user (str) – A user identifier. The user can be identified either by ID or name.
data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
view (str) – A specific view of the returned data. Can be: describe, or default.

Returns:

An HTTP response

Return type:

Response

get_user_properties(user: str, data_format: str | None = None) → Response[source]

Send a GET request to the /manage/v2/users/{id|name}/properties endpoint.

Parameters:

user (str) – A user identifier. The user can be identified either by ID or name.
data_format (str) – The format of the returned data. Can be either json or xml (default). This parameter overrides the Accept header if both are present.

Returns:

An HTTP response

Return type:

Response

get_users(data_format: str | None = None, view: str | None = None) → Response[source]

Send a GET request to the /manage/v2/users endpoint.

Parameters:

data_format (str) – The format of the returned data. Can be either html, json, or xml (default).
view (str) – A specific view of the returned data. Can be: describe, or default.

Returns:

An HTTP response

Return type:

Response

post_database(database: str, body: str | dict) → Response[source]

Send a POST request to the /manage/v2/databases/{id|name} endpoint.

Parameters:

database (str) – A database identifier. The database can be identified either by ID or name.
body (str | dict) – A database properties in XML or JSON format.

Returns:

An HTTP response

Return type:

Response

post_databases(body: str | dict) → Response[source]

Send a POST request to the /manage/v2/databases endpoint.

Parameters:: body (str | dict) – A database properties in XML or JSON format.
Returns:: An HTTP response
Return type:: Response

post_documents(body_parts: list[mlclient.structures.calls.documents.DocumentsBodyPart], database: str | None = None, transform: str | None = None, transform_params: dict | None = None, txid: str | None = None, temporal_collection: str | None = None, system_time: str | None = None)[source]

Send a POST request to the /v1/documents endpoint.

Parameters:

body_parts (list[DocumentsBodyPart]) – A list of multipart request body parts
database (str) – Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the “eval-in” privilege.
transform (str) – Names a content transformation previously installed via the /config/transforms service. The service applies the transformation to all documents prior to constructing the response.
transform_params (str) – A transform parameter names and values. For example, { “myparam”: 1 }. Transform parameters are passed to the transform named in the transform parameter.
txid (str) – The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
temporal_collection (str) – Specify the name of a temporal collection into which the documents are to be inserted.
system_time (str) – Set the system start time for the insertion or update. This time will override the system time set by MarkLogic. Ignored if temporal-collection is not included in the request.

Returns:

An HTTP response

Return type:

Response

post_forest(forest: str, body: str | dict) → Response[source]

Send a POST request to the /manage/v2/forests/{id|name} endpoint.

Parameters:

forest (str) – A forest identifier. The forest can be identified either by ID or name.
body (dict) – A list of properties. Need to include the ‘state’ property (the type of state change to initiate). Allowed values: clear, merge, restart, attach, detach, retire, employ.

Returns:

An HTTP response

Return type:

Response

post_forests(body: str | dict, wait_for_forest_to_mount: bool | None = None) → Response[source]

Send a POST request to the /manage/v2/forests endpoint.

Parameters:

body (str | dict) – A database properties in XML or JSON format.
wait_for_forest_to_mount (bool) – Whether to wait for the new forest to mount before sending a response to this request. Allowed values: true (default) or false.

Returns:

An HTTP response

Return type:

Response

post_roles(body: str | dict) → Response[source]

Send a POST request to the /manage/v2/roles endpoint.

Parameters:: body (str | dict) – A role properties in XML or JSON format.
Returns:: An HTTP response
Return type:: Response

post_servers(body: str | dict, group_id: str | None = None, server_type: str | None = None) → Response[source]

Send a POST request to the /manage/v2/servers endpoint.

Parameters:

body (str | dict) – A database properties in XML or JSON format.
group_id (str) – The id or name of the group to which the App Server belongs. The group must be specified by this parameter or by the group-name property in the request payload. If it is specified in both places, the values must be the same.
server_type (str) – The type of App Server to create. The App Server type must be specified by this parameter or in the request payload. If it is specified in both places, the values must be the same. The valid types are: http, odbc, xdbc, or webdav.

Returns:

An HTTP response

Return type:

Response

post_users(body: str | dict) → Response[source]

Send a POST request to the /manage/v2/users endpoint.

Parameters:: body (str | dict) – A user properties in XML or JSON format.
Returns:: An HTTP response
Return type:: Response

put_database_properties(database: str, body: str | dict) → Response[source]

Send a PUT request to the /manage/v2/databases/{id|name}/properties endpoint.

Parameters:

database (str) – A database identifier. The database can be identified either by ID or name.
body (str | dict) – A database properties in XML or JSON format.

Returns:

An HTTP response

Return type:

Response

put_forest_properties(forest: str, body: str | dict) → Response[source]

Send a PUT request to the /manage/v2/databases/{id|name}/properties endpoint.

Parameters:

forest (str) – A forest identifier. The forest can be identified either by ID or name.
body (str | dict) – A forest properties in XML or JSON format.

Returns:

An HTTP response

Return type:

Response

put_forests(body: str | dict) → Response[source]

Send a PUT request to the /manage/v2/forests endpoint.

Parameters:: body (str | dict) – A database properties in XML or JSON format.
Returns:: An HTTP response
Return type:: Response

put_role_properties(role: str, body: str | dict) → Response[source]

Send a PUT request to the /manage/v2/roles/{id|name}/properties endpoint.

Parameters:

role (str) – A role identifier. The role can be identified either by ID or name.
body (str | dict) – A role properties in XML or JSON format.

Returns:

An HTTP response

Return type:

Response

put_server_properties(server: str, group_id: str, body: str | dict) → Response[source]

Send a PUT request to the /manage/v2/servers/{id|name}/properties endpoint.

Parameters:

server (str) – A server identifier. The server can be identified either by ID or name.
group_id (str) – The id or name of the group to which the App Server belongs. This parameter is required.
body (str | dict) – A database properties in XML or JSON format.

Returns:

An HTTP response

Return type:

Response

put_user_properties(user: str, body: str | dict) → Response[source]

Send a PUT request to the /manage/v2/users/{id|name}/properties endpoint.

Parameters:

user (str) – A user identifier. The user can be identified either by ID or name.
body (str | dict) – A user properties in XML or JSON format.

Returns:

An HTTP response

Return type:

Response

Raises:

NotImplementedError – If the call’s method is not GET, POST, PUT nor DELETE.

class mlclient.MLResponseParser[source]

Bases: object

A MarkLogic HTTP response parser.

MarkLogic returns responses with multipart/mixed content. This class allows to get all returned parts as python representations. They are parsed depending on content type of corresponding part.

Examples

>>> from mlclient import MLResourcesClient, MLResponseParser
>>> config = {
...     "host": "localhost",
...     "port": 8002,
...     "username": "admin",
...     "password": "admin",
...     "auth_method": "digest",
... }
>>> with MLResourcesClient(**config) as client:
...     resp = client.eval(xquery="xdmp:database() => xdmp:database-name()")
...     print("Raw:", resp.text)
...     print("Parsed:", MLResponseParser.parse(resp))
...
Raw:
--6a5df7d535c71968
Content-Type: text/plain
X-Primitive: string
App-Services
--6a5df7d535c71968--
Parsed: App-Services

Parse MarkLogic HTTP Response.

Parameters:

response (Response) – An HTTP response taken from MarkLogic instance
output_type (type | None , default None) – A raw output type (supported: str, bytes)

Returns:

bytes | str | int | float | bool | dict |
ElemTree.ElementTree | ElemTree.Element |
list – A parsed response body

classmethod parse_with_headers(response: Response, output_type: type | None = None) → tuple | list[tuple][source]

Parse MarkLogic HTTP Response and get headers.

Parameters:

response (Response) – An HTTP response taken from MarkLogic instance
output_type (type | None , default None) – A raw output type (supported: str, bytes)

Returns:

A parsed response body with headers

Return type:

tuple

mlclient.ml_config module

The ML Configuration module.

This module contains an API for MarkLogic configuration. It exports the following classes:

MLConfiguration
A class representing MarkLogic configuration.

MLAppServerConfiguration
A class representing MarkLogic App Server configuration.

AuthMethod
An enumeration class representing authorization methods.

class mlclient.ml_config.AuthMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

An enumeration class representing authorization methods.

BASIC = 'basic'

DIGEST = 'digest'

pydantic model mlclient.ml_config.MLAppServerConfiguration[source]

Bases: BaseModel

A class representing MarkLogic App Server configuration.

Show JSON schema

{
   "title": "MLAppServerConfiguration",
   "description": "A class representing MarkLogic App Server configuration.",
   "type": "object",
   "properties": {
      "id": {
         "description": "A unique identifier of the App Server",
         "title": "Id",
         "type": "string"
      },
      "port": {
         "description": "A port number",
         "title": "Port",
         "type": "integer"
      },
      "auth": {
         "allOf": [
            {
               "$ref": "#/$defs/AuthMethod"
            }
         ],
         "default": "digest",
         "description": "An authorization method"
      },
      "rest": {
         "default": false,
         "description": "A flag informing if the App-Server is a REST server",
         "title": "Rest",
         "type": "boolean"
      }
   },
   "$defs": {
      "AuthMethod": {
         "description": "An enumeration class representing authorization methods.",
         "enum": [
            "basic",
            "digest"
         ],
         "title": "AuthMethod",
         "type": "string"
      }
   },
   "required": [
      "id",
      "port"
   ]
}

Fields:

auth_method (mlclient.ml_config.AuthMethod)
identifier (str)
port (int)
rest (bool)

field auth_method: AuthMethod = AuthMethod.DIGEST (alias 'auth'): An authorization method

field identifier: str [Required] (alias 'id'): A unique identifier of the App Server

field port: int [Required]: A port number

field rest: bool = False: A flag informing if the App-Server is a REST server

serialize_auth(auth_method: AuthMethod, _info)[source]: Serialize auth field.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

pydantic model mlclient.ml_config.MLConfiguration[source]

Bases: BaseModel

A class representing MarkLogic configuration.

Show JSON schema

{
   "title": "MLConfiguration",
   "description": "A class representing MarkLogic configuration.",
   "type": "object",
   "properties": {
      "app-name": {
         "description": "An application name",
         "title": "App-Name",
         "type": "string"
      },
      "protocol": {
         "default": "http",
         "description": "An HTTP protocol",
         "title": "Protocol",
         "type": "string"
      },
      "host": {
         "default": "localhost",
         "description": "A hostname",
         "title": "Host",
         "type": "string"
      },
      "username": {
         "default": "admin",
         "description": "An username",
         "title": "Username",
         "type": "string"
      },
      "password": {
         "default": "admin",
         "description": "A password",
         "title": "Password",
         "type": "string"
      },
      "app-servers": {
         "default": [
            {
               "id": "manage",
               "port": 8002,
               "auth": "digest",
               "rest": true
            }
         ],
         "description": "App Servers configurations' list",
         "items": {
            "$ref": "#/$defs/MLAppServerConfiguration"
         },
         "title": "App-Servers",
         "type": "array"
      }
   },
   "$defs": {
      "AuthMethod": {
         "description": "An enumeration class representing authorization methods.",
         "enum": [
            "basic",
            "digest"
         ],
         "title": "AuthMethod",
         "type": "string"
      },
      "MLAppServerConfiguration": {
         "description": "A class representing MarkLogic App Server configuration.",
         "properties": {
            "id": {
               "description": "A unique identifier of the App Server",
               "title": "Id",
               "type": "string"
            },
            "port": {
               "description": "A port number",
               "title": "Port",
               "type": "integer"
            },
            "auth": {
               "allOf": [
                  {
                     "$ref": "#/$defs/AuthMethod"
                  }
               ],
               "default": "digest",
               "description": "An authorization method"
            },
            "rest": {
               "default": false,
               "description": "A flag informing if the App-Server is a REST server",
               "title": "Rest",
               "type": "boolean"
            }
         },
         "required": [
            "id",
            "port"
         ],
         "title": "MLAppServerConfiguration",
         "type": "object"
      }
   },
   "required": [
      "app-name"
   ]
}

Fields:

app_name (str)
app_servers (List[mlclient.ml_config.MLAppServerConfiguration])
host (str)
password (str)
protocol (str)
username (str)

field app_name: str [Required] (alias 'app-name'): An application name

field app_servers: List[MLAppServerConfiguration] = [MLAppServerConfiguration(identifier='manage', port=8002, auth_method=<AuthMethod.DIGEST: 'digest'>, rest=True)] (alias 'app-servers'): App Servers configurations’ list

field host: str = 'localhost': A hostname

field password: str = 'admin': A password

field protocol: str = 'http': An HTTP protocol

field username: str = 'admin': An username

classmethod from_environment(environment_name: str) → MLConfiguration[source]

Instantiate MLConfiguration from an environment.

This method looks for a configuration file in the .mlclient directory. An environment configuration needs to match a file name pattern to be recognized: mlclient-<environment-name>.yaml.

Parameters:

environment_name (str) – An MLClient environment name

Returns:

An MLConfiguration instance

Return type:

MLConfiguration

Raises:

MLClientDirectoryNotFoundError – If .mlclient directory has not been found
MLClientEnvironmentNotFoundError – If there’s no .mlclient/mlclient-<environment_name>.yaml file

classmethod from_file(file_path: str) → MLConfiguration[source]

Instantiate MLConfiguration from a file.

Parameters:: file_path (str) – A source configuration file
Returns:: An MLConfiguration instance
Return type:: MLConfiguration

provide_config(app_server_id: str) → dict[source]

Provide an app server configuration for MLClient’s use.

Parameters:: app_server_id (str) – A unique identifier of the App Server
Returns:: A configuration dictionary for an MLClient initialization
Return type:: dict

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

property rest_servers: list[str]: REST servers identifiers.

mlclient.constants module

The ML Client Constants module.

mlclient.exceptions module

The ML Client Exceptions module.

It contains all custom exceptions related to ML Client:

WrongParametersError
A custom Exception class for wrong parameters.
UnsupportedFormatError
A custom Exception class for an unsupported format.
MLClientDirectoryNotFoundError
A custom Exception class for a non-existing MLClient configuration directory.
MLClientEnvironmentNotFoundError
A custom Exception class for a non-existing MLClient environment.
NoSuchAppServerError
A custom Exception class for a non-existing app server configuration.
NotARestServerError
A custom Exception class for a regular App-Server used as a REST Server.
NoRestServerConfiguredError
A custom Exception class for no REST Server configured when required.
MarkLogicError
A custom Exception class representing MarkLogic errors.
UnsupportedFileExtensionError
A custom Exception class for an unsupported file extension.
ResourceNotFoundError
A custom Exception class for a not found resource.

exception mlclient.exceptions.InvalidLogTypeError[source]

Bases: Exception

A custom Exception class for an invalid log type.

Raised while getting LogType enum for a value different from error, access and request.

exception mlclient.exceptions.MLClientDirectoryNotFoundError[source]

Bases: Exception

A custom Exception class for a non-existing MLClient configuration directory.

Raised when initializing an MLConfiguration from an environment.

exception mlclient.exceptions.MLClientEnvironmentNotFoundError[source]

Bases: Exception

A custom Exception class for a non-existing MLClient environment.

Raised when initializing an MLConfiguration from an environment.

exception mlclient.exceptions.MarkLogicError(error: dict | str)[source]

Bases: Exception

A custom Exception class representing MarkLogic errors.

Raised whenever an ML server returns an error.

exception mlclient.exceptions.NoRestServerConfiguredError[source]

Bases: Exception

A custom Exception class for no REST Server configured when required.

Raised while getting an app server config when no REST server is configured.

exception mlclient.exceptions.NoSuchAppServerError[source]

Bases: Exception

A custom Exception class for a non-existing app server configuration.

Raised when getting an app server config from an MLConfiguration instance.

exception mlclient.exceptions.NotARestServerError[source]

Bases: Exception

A custom Exception class for a regular App-Server used as a REST Server.

Raised while getting an app server config not being a REST server.

exception mlclient.exceptions.ResourceNotFoundError(resource_name: str)[source]

Bases: Exception

A custom Exception class for a not found resource.

Raised while attempting to get a resource that does exist.

exception mlclient.exceptions.UnsupportedFileExtensionError[source]

Bases: Exception

A custom Exception class for an unsupported file extension.

Raised while evaluating code from file with unsupported extension.

exception mlclient.exceptions.UnsupportedFormatError[source]

Bases: Exception

A custom Exception class for an unsupported format.

Raised when getting an Accept header for a format.

exception mlclient.exceptions.WrongParametersError[source]

Bases: Exception

A custom Exception class for wrong parameters.

Raised when attempting to call a REST Resource with incorrect parameters.

mlclient.utils module

The ML Client Utils module.

It contains all useful functions and classes shared in ML Client package. It exports following functions:

get_accept_header_for_format(data_format: str) -> str
Return an Accept header for data format.

get_content_type_header_for_data(data: str | dict) -> str
Return a Content-Type header for data provided.

get_resource(resource_name: str) -> TextIO
Return an MLClient resource.

It also exports a single class:

BiDict
A bidirectional dictionary.

class mlclient.utils.BiDict(input_dict: dict)[source]

Bases: object

A bidirectional dictionary.

This dict allows you to find a corresponding value by key in two directions.

get(key: Any, default: Any = None) → Any[source]

Return a corresponding value for a key regardless direction.

Parameters:

key (Any) – A dictionary key or value
default (Ant, default None) – A default value

Returns:

A corresponding value from the dictionary

Return type:

Any

mlclient.utils.get_accept_header_for_format(data_format: str) → str[source]

Return an Accept header for data format.

Parameters:: data_format (str) – Data format
Returns:: An Accept header value
Return type:: str
Raises:: UnsupportedFormatError – If the format provided is not being supported

mlclient.utils.get_content_type_header_for_data(content: str | dict) → str[source]

Return a Content-Type header for data provided.

Parameters:: content (str | dict) – Data to send in a request
Returns:: A Content-Type header value
Return type:: str

mlclient.utils.get_resource(resource_name: str) → TextIO[source]

Return an MLClient resource.

The resource needs to be included in mlclient.resources package to be returned.

Parameters:: resource_name (str) – An MLClient resource name
Returns:: A MLClient resource
Return type:: TextIO
Raises:: ResourceNotFoundError – If the resource does not exist