API Documentation

Database Client

class snakesist.ExistClient(transport: str = 'http', host: str = 'localhost', port: int = 8080, user: str = 'admin', password: str = '', prefix: str = 'exist', root_collection: str = '/', parser: lxml.etree.XMLParser = <lxml.etree.XMLParser object>)

Bases: object

An eXist-db client object representing a database instance. The client can be used for CRUD operations. Resources can be queried using an XPath expression. Queried resources are identified by the absolute resource ID and, if the resource is part of a document, the node ID.

Parameters

  • host – hostname

  • port – port used to connect to the configured eXist instance

  • user – username

  • password – password

  • prefix – configured path prefix for the eXist instance

  • root_collection – a path to a collection which will be used as root for all document paths

  • parser – an lxml etree.XMLParser instance to parse query results

property base_url

The base URL pointing to the eXist instance.

delete_document(document_path: str) → None

Removes a document from the associated database.

Parameters

document_path – The path pointing to the document within the root collection.

delete_node(abs_resource_id: str, node_id: str = '') → None

Remove a node from the database.

Parameters

  • abs_resource_id – The absolute resource ID pointing to the document.

  • node_id – The node ID locating a node inside a document (optional).

classmethod from_url(url: str, parser=<lxml.etree.XMLParser object>) → snakesist.exist_client.ExistClient

Returns a client instance from the given URL. Path parts that point to something beyond the database instance’s path prefix are ignored.

property host

The database hostname

property password

The password used to connect to the database

property port

The database port number

property prefix

The URL prefix of the database

query(query_expression: str) → lxml.etree._Element

Make a database query using XQuery. The configured root collection will be the starting point of the query.

Parameters

query_expression – XQuery expression

Returns

The query result as a delb.Document object.

retrieve_resource(abs_resource_id: str, node_id: str) → snakesist.exist_client.NodeResource

Retrieve a single resource by its internal database IDs.

Parameters

  • abs_resource_id – The absolute resource ID pointing to the document.

  • node_id – The node ID locating a node inside a document (optional).

Returns

The queried node as a Resource object.

property root_collection

The configured root collection for database queries.

property root_collection_url

The URL pointing to the configured root collection.

property transport

The used transport protocol

update_node(data: str, abs_resource_id: str, node_id: str) → None

Replace a sub-document node with an updated version.

Parameters

  • data – A well-formed XML string containing the node to replace the old one with.

  • abs_resource_id – The absolute resource ID pointing to the document containing the node.

  • node_id – The node ID locating the node inside the containing document.

property user

The user name used to connect to the database

xpath(expression: str) → List[snakesist.exist_client.NodeResource]

Retrieve a set of resources from the database using an XPath expression. The configured root collection will be the starting point of the query.

Parameters

expression – XPath expression (whatever version your eXist instance supports via its RESTful API)

Returns

The query results as a list of Resource objects.

Resources

class snakesist.delb_plugins.ExistDBExtension

Bases: _delb.plugins.DocumentExtensionHooks

This class provides extensions to delb.Document in order to interact with a eXist-db instance.

See existdb_loader() on retrieving documents from an eXist-db instance.

config: types.SimpleNamespace
property existdb_collection

The collection within an eXist-db instance where the document was fetched from. This property can be changed to designate another location to store to.

existdb_delete()

Deletes the document that currently resides at the location which is made up of the current ExistDBExtension.existdb_collection and ExistDBExtension.existdb_filename in the associated eXist-db instance.

property existdb_filename

The filename within the eXist-db instance and collection where the document was fetched from. This property can be changed to designate another location to store to.

existdb_store(collection: str = None, filename: str = None, replace_existing: bool = False)

Stores the current state of the document in the associated eXist-db instance.

Parameters

  • collection – An alternate collection to save into.

  • filename – An alternate name to store the document.

  • replace_existing – Allows to overwrite existing documents.

snakesist.delb_plugins.existdb_loader(source: Any, config: types.SimpleNamespace) → Union[Tuple[Optional[lxml.etree._ElementTree], Dict[int, _ElementWrappingNode]], str]

This loader loads a document from a eXist-db instance. There are two ways to retrieve a particular document.

One is to specify an URL with the existdb:// scheme, which can optionally be extended with the transport protocol: existdb+http:// or existdb+https://.

The overall pattern of the URLs is: existdb[+http[s]]://[[<username>]:[<password>]@]<host>[:<port>][/<prefix>]/<path>

For example:

document = delb.Document("existdb://example.org/exist/corpus/document.xml")

Note that omitted ports would default to 80 or 443 respectively, depending on the used transport protocol. Which in turn is probed for if not specified, preferring encrypted connections.

The other way is to pass a configured client as existdb_client keyword and a path as string or pathlib.PurePosixPath that points to the document within the client’s configured snakesist.ExistClient.root_collection, hence this would be an equivalent to the example above, assuming that https is available on the addressed host:

client = snakesist.ExistClient(
    transport="https",
    host="example.org",
    port=443,
    user="",
    root_collection="/corpus",
)
document = delb.Document("document.xml", existdb_client=client)

In both cases the document instance will have a configured config namespace existdb with the property client which is a snakesist.ExistClient instance.

Further interaction with the database is facilitated with the ExistDBExtension that extends the delb.Document class.

class snakesist.NodeResource(exist_client: snakesist.exist_client.ExistClient, query_result: Optional[snakesist.exist_client.QueryResultItem] = None)

Bases: object

A representation of an XML node in a eXist-db resource. Each Resource object must be coupled to an ExistClient.

Resources are identified by an absolute resource ID that points to the containing document and a node ID within that document.

Parameters

exist_client – The client to which the resource is coupled.

Query_result

A tuple containing the absolute resource ID, node ID and the node of the resource.

property abs_resource_id

The absolute resource ID pointing to a document in the database.

delete()

Deletes the node from the database.

property document_path

The resource path pointing to the document.

property node_id

The node ID locating the node relative to the containing document.

update_pull()

Retrieve the current node state from the database and update the object.

update_push()

Writes the node to the database.