snakesist¶

snakesist is an experimental Python database driver for eXist-db. It currently only supports retrieving, updating and deleting resources.

pip install snakesist

Usage example¶

import delb
from snakesist.exist_client import ExistClient

db = ExistClient(
    host='my.existdbinstance.org',  # defaults to 'localhost'
    port='80',  # defaults to 8080
    usr='foo_bar',  # defaults to 'admin'
    pw='f0ob4r'  # defaults to ''
)

db.root_collection = '/db/foo/bar'
# the client will only query from this point downwards

names = db.retrieve_resources('//*:persName')
# note the namespace wildcard in the XPath expression

for name in names:
    if name.node.full_text() == 'Monty':
        suffix = delb.TextNode(' Python')
        name.node.append_child(suffix)
        name.update_push()
    else:
        name.delete()

Your eXist instance¶

snakesist leverages the eXist RESTful API for database queries. This means that allowing database queries using the _query= parameter of the RESTful API is a requirement. eXist allows this by default, so if you haven’t configured your instance otherwise, don’t worry about it.

Stability¶

This package doesn’t have a stable release yet and lacks sufficient test coverage. Please use with care. It also has delb as a dependency (for accessing the document nodes), which is a very young project developed as a POC at the moment.

Contributions, suggestions, bug reports and feature requests for snakesist are more than welcome.

API Documentation¶

Database Client¶

class snakesist.exist_client.ExistClient(host: str = 'localhost', port: int = 8080, user: str = 'admin', password: str = '', prefix: str = 'exist', 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 parser – an lxml etree.XMLParser instance to parse query results

base_url¶: The base URL pointing to the eXist instance.

create_resource(document_path: str, node: str)¶

Write a new document node to the database.

Parameters:	document_path – Path to collection where document will be stored, relative to the configured root collection node – XML string

delete_document(document_path: str) → None¶

Remove a document from a database.

Parameters:	document_path – The path pointing to the document (relative to the REST endpoint, e. g. ‘/db/foo/bar’)

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).

query(query_expression: str) → delb.Document¶

Make a database query using XQuery

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.Resource¶

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.

retrieve_resources(xpath: str) → List[snakesist.exist_client.Resource]¶

Retrieve a set of resources from the database using an XPath expression.

Parameters:	xpath – XPath expression (whatever version your eXist instance supports via its RESTful API)
Returns:	The query results as a list of `Resource` objects.

root_collection¶: The configured root collection for database queries.

root_collection_url¶: The URL pointing to the configured root collection.

update_document(data: str, document_path: str) → None¶

Replace a document root node with an updated version.

Parameters:	data – A well-formed XML string containing the node to replace the old one with. document_path – The path pointing to the document (relative to the REST endpoint, e. g. ‘/db/foo/bar’)

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.

Resources¶

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

Bases: abc.ABC

A representation of an eXist resource (documents, nodes etc.). Each Resource object must be coupled to an ExistClient.

Resources are identified by IDs: Some resources (documents) just have an absolute resource ID, while others (nodes) require an additional node ID.

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

delete()¶: Remove the node from the database.

document_path¶: The resource path pointing to the document.

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()¶: Write the resource object to the database.