Delb plugins (#27)

* Adds tests to discuss URL resolution defaults

* Adds a proxy to the test database setup

in anticipation of probing the proper transport protocol if omitted

* Makes URL parsing tests and facilities workable in a real test world

* Updates to delb 0.2b4

* Implements ExistClient.from_url

* Stores prefix and root_collection as PurePosixPath

which implies a value cleanup and check.
it also makes their use more expectable.

* Updates delb and other dependencies

* Implements delb loader and document extension

* Adds a test that uses two delb document exttensions

* Update Travis config to reflect new testing setup

* Update lockfile

* Fix mypy missing import error

* Removes tests for unrequired ExistClient features / uses delb extension

* Let's delb extension use client's delete method

* Removes unrequired code parts

* Raises a ValueError in case of an invalid host in a parsed URL

* Rename xpath query method

* Add exception hierarchy draft

* Fix mypy import error

* Wraps all possible exceptions from http responses in snakesist exceptions

* Makes some exceptions more specific

* Fixes imports and applies black

* Removes a delb loader TODO b/c it's fine as it is

* Clarify that query starts at root collection

* Add prefix to exception names

* Refactor away single-use methods

* Adds full documentation for the delb plugins

* Updates to delb 0.2

* Renew SSL certificate

* Update README

* Bump version

* Lock dependencies

Co-authored-by: Theo Costea <theo.costea@gmail.com>

.travis.yml

@@ -3,9 +3,6 @@ services:
     - docker
 python:
     - "3.6"
-before_install:
-    - travis_retry docker pull existdb/existdb:4.7.1
-    - docker run -d -p 8080:8080 -p 8443:8443 --name exist-4.7.1 existdb/existdb:4.7.1
 install:
     - travis_retry pip install poetry
     - travis_retry poetry install

README.rst

@@ -22,29 +22,40 @@ It supports basic CRUD operations and uses `delb <https://delb.readthedocs.io>`_
 
     pip install snakesist
 
+``snakesist`` allows you to access individual documents from the database with a ``delb.Document``, either by simply using a URL
 
-Usage example
--------------
+.. code-block:: python
+
+    >>> from delb import Document
+
+    >>> manifest = Document("existdb://admin:@localhost:8080/exist/db/manifestos/dada_manifest.xml")
+    >>> [header.full_text for header in manifest.xpath("//head")]
+    ["Hugo Ball", "Das erste dadaistische Manifest"]
+
+or by instantiating a database client which you can subsequently reuse
 
 .. code-block:: python
 
-    from snakesist import ExistClient
+    >>> from snakesist import ExistClient
 
-    db = ExistClient()
+    >>> my_local_db = ExistClient(host="localhost", port=8080, user="admin", password="", root_collection="/db/manifestos")
+    >>> dada_manifest = Document("dada_manifest.xml", existdb_client=my_local_db)
+    >>> [header.full_text for header in dada_manifest.xpath("//head")]
+    ["Hugo Ball", "Das erste dadaistische Manifest"]
+    >>> communist_manifest = Document("communist_manifest.xml", existdb_client=my_local_db)
+    >>> communist_manifest.xpath("//head").first.full_text
+    "Manifest der Kommunistischen Partei"
 
-    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
+and not only for accessing individual documents, but also for querying data across multiple documents
+
+.. code-block:: python
+
+    >>> all_headers = my_local_db.xpath("//*:head")
+    >>> [header.full_text for header in all_headers]
+    ["Hugo Ball", "Das erste dadaistische Manifest", "Manifest der Kommunistischen Partei", "I. Bourgeois und Proletarier.", "II. Proletarier und Kommunisten", "III. Sozialistische und kommunistische Literatur", "IV. Stellung der Kommunisten zu den verschiedenen oppositionellen Parteien"]
 
-    # append 'Python' to all names which are 'Monty' and delete the rest
-    for name in names:
-        if name.node.full_text == 'Monty':
-            name.node.append_child(' Python')
-            name.update_push()
-        else:
-            name.delete()
+You can of course also modify and store documents back into the database or create new ones and store them.
 
 
 Your eXist instance
@@ -57,4 +68,6 @@ for database queries. This means that allowing database queries using the
 backend. eXist allows this by default, so if you haven't configured your
 instance otherwise, don't worry about it.
 
-``snakesist`` is tested with eXist 4.7.1 and is not compatible yet with eXist 5.0.0.
+Please note that ``snakesist`` is tested with eXist 4.7.1 and is not compatible yet
+with version 5. The bug preventing ``snakesist`` to be compatible with the newest major eXist
+version will be fixed with the release of eXist 5.3.0.

docs/api_doc.rst

@@ -4,12 +4,13 @@ API Documentation
 Database Client
 ---------------
 
-.. automodule:: snakesist
 .. autoclass:: snakesist.ExistClient
 
 Resources
 ---------
 
 .. autoclass:: snakesist.delb_plugins.ExistDBExtension
 
+.. autofunction:: snakesist.delb_plugins.existdb_loader
+
 .. autoclass:: snakesist.NodeResource

docs/conf.py

@@ -51,6 +51,7 @@
 
 intersphinx_mapping = {
     'delb': ('https://delb.readthedocs.io/en/latest/', None),
+    'cpython': ('https://docs.python.org', None)
 }