API Documentation

Database Client

class delb_existdb.ExistClient(**options: ClientOptions)

Bases: object

An eXist-db client object to interact with a database instance. The client can be used for CRUD operations. Nodes can be queried using an XPath expression. Queried resources are identified by a document and a node ID (these map to eXist-db’s absolute and relative resource IDs).

Caution

The node IDs are mere pointers by index to a node within a document. Structural changes to a document may invalidate these and lead to undesired behaviour.

Parameters:

  • host – The name of the database serving host.

  • port – The port the database instance is listening to.

  • user – An optional username to authenticate.

  • password – The accompanying password for authentication.

  • prefix – The HTTP path prefix for the database instance.

  • collection – The path to the collection which will be used as root for all document paths.

  • parser_options – A named tuple from delb to define the XML parser’s behaviour.

property base_url: str

The base URL pointing to the eXist instance.

property collection: str

The collection for database queries. The attribute can be changed on an initialized client.

property collection_base_url: str

The URL pointing to the configured collection.

delete_document(path: str) → None

Removes a document from the associated database.

Parameters:

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

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

Remove a node from the database.

Parameters:

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

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

fetch_document(path: str) → Document

Fetches a document from the client’s configured collection.

Parameters:

path – Path of the document.

fetch_node(document_id: str, node_id: str) → NodeResource

Retrieve a node resource by its internal database IDs.

Parameters:

  • document_id – The ID of a document.

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

Returns:

The queried resource object.

classmethod from_url(url: str, parser_options: ParserOptions | None = None) → 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: str

The database hostname.

http_client: Final
property parser_options: ParserOptions
property password: str

The password used to connect to the database.

property port: int

The database port number.

property prefix: str

The URL prefix of the database.

query(query_expression: str) → TagNodeType

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

Parameters:

query_expression – XQuery expression.

Returns:

The query result as a delb.TagNode object.

retrieve_resource(abs_resource_id: str, node_id: str) → NodeResource

Deprecated. Use ExistClient.fetch_node()

property transport: str

The used transport protocol.

update_node(node: TagNodeType, document_id: str, node_id: str)

Replace a node with the contents of the given one.

Parameters:

  • node – An XML node to replace the old one with.

  • document_id – The document ID of the target.

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

property user: str

The user name used to connect to the database.

xpath(expression: str) → list[NodeResource]

Retrieve a set of resources from the database using an XPath expression. The configured 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 NodeResource objects.

Resources

class delb_existdb.NodeResource(exist_client: ExistClient, query_result: QueryResultItem)

Bases: object

A representation of an XML node in a eXist-db resource. Each object is coupled to an ExistClient. Resources are identified by a document ID that points to the containing document and a node ID within that document.

property abs_resource_id
delete()

Deletes the node from the database.

property document_id

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

property document_path

The resource path pointing to the document.

node

A delb node representation of the node.

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 current NodeResource.node contents to the database, replacing the previous state.

delb plugins

class delb_existdb.delb_plugins.ExistDBExtension

Bases: DocumentMixinBase

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: SimpleNamespace
property existdb_collection: str

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_filepath in the associated eXist-db instance.

property existdb_filepath: str

The filepath 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 = None, filepath: str | None = 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.

  • filepath – An alternate path to store the document.

  • replace_existing – Allows to overwrite existing documents.

delb_existdb.delb_plugins.existdb_loader(source: Any, config: SimpleNamespace) → LoaderResult

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 delb_existdb.ExistClient.collection, hence this would be an equivalent to the example above, assuming that https is available on the addressed host:

client = delb_existdb.ExistClient(
    transport="https",
    host="example.org",
    port=443,
    user="",
    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 delb_existdb.ExistClient instance.

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

Exceptions

exception delb_existdb.exceptions.DelbExistdbConfigError

Bases: DelbExistdbError

Raised if the database connection is improperly configured.

exception delb_existdb.exceptions.DelbExistdbError

Bases: Exception

DelbExistdb base exception class.

exception delb_existdb.exceptions.DelbExistdbNotFound

Bases: DelbExistdbReadError

Raised if a database resource is not found.

exception delb_existdb.exceptions.DelbExistdbQueryError(payload: str, response: httpx.Response)

Bases: DelbExistdbError

Informs about query errors.

messages: tuple[str, ...]
path
payload
exception delb_existdb.exceptions.DelbExistdbReadError

Bases: DelbExistdbError

Raised if a writing operation fails.

exception delb_existdb.exceptions.DelbExistdbWriteError

Bases: DelbExistdbError

Raised if a reading operation fails