feat: RDF4J Client

Taskfile.yml

@@ -378,3 +378,11 @@ tasks:
             sys.stderr.write(f"removing {path}\n")
             shutil.rmtree(path, ignore_errors=True)
         ' {{.RIMRAF_TARGET}}
+
+  test:rdf4j:
+    desc: Run fast tests against rdflib.contrib.rdf4j package
+    cmd: '{{.TEST_HARNESS}}{{.RUN_PREFIX}} pytest -m "not (testcontainer or webtest)" test/test_rdf4j'
+
+  test:rdf4j:all:
+    desc: Run all tests against rdflib.contrib.rdf4j package
+    cmd: '{{.TEST_HARNESS}}{{.RUN_PREFIX}} pytest test/test_rdf4j'

mkdocs.yml

@@ -43,6 +43,7 @@ nav:
     - Container: apidocs/rdflib.container.md
     - Collection: apidocs/rdflib.collection.md
     - Paths: apidocs/rdflib.paths.md
+    - RDF4J: apidocs/rdflib.contrib.rdf4j.md
     - Util: apidocs/rdflib.util.md
     - Plugins:
       - Parsers: apidocs/rdflib.plugins.parsers.md

pyproject.toml

@@ -41,14 +41,18 @@ rdfs2dot = 'rdflib.tools.rdfs2dot:main'
 rdfgraphisomorphism = 'rdflib.tools.graphisomorphism:main'
 
 [tool.poetry.dependencies]
-python = ">=3.8.1"
+# TODO: temporarily add new python version constraints for testcontainers
+# We can remove the upper bound once testcontainers releases a new version
+# https://github.com/testcontainers/testcontainers-python/pull/909
+python = ">=3.9.2, <4.0"
 isodate = {version=">=0.7.2,<1.0.0", python = "<3.11"}
 pyparsing = ">=2.1.0,<4"
 berkeleydb = {version = "^18.1.0", optional = true}
 networkx = {version = ">=2,<4", optional = true}
 html5rdf = {version = ">=1.2,<2", optional = true}
 lxml = {version = ">=4.3,<6.0", optional = true}
 orjson = {version = ">=3.9.14,<4", optional = true}
+httpx = {version = "^0.28.1", optional = true}
 
 [tool.poetry.group.dev.dependencies]
 black = "24.8.0"
@@ -63,6 +67,7 @@ coverage = {version = "^7.0.1", extras = ["toml"]}
 types-setuptools = ">=68.0.0.3,<72.0.0.0"
 setuptools = ">=68,<72"
 wheel = ">=0.42,<0.46"
+testcontainers = "^4.13.2"
 
 [tool.poetry.group.docs.dependencies]
 typing-extensions = "^4.11.0"
@@ -85,6 +90,7 @@ html = ["html5rdf"]
 # lxml support is optional, it is used only for parsing XML-formatted SPARQL results
 lxml = ["lxml"]
 orjson = ["orjson"]
+rdf4j = ["httpx"]
 
 [build-system]
 requires = ["poetry-core>=1.4.0"]
@@ -207,6 +213,8 @@ addopts = [
     "--ignore=admin",
     "--ignore=devtools",
     "--ignore=rdflib/extras/external_graph_libs.py",
+    "--ignore=rdflib/contrib/graphdb/client.py",
+    "--ignore=rdflib/contrib/rdf4j/client.py",
     "--ignore-glob=docs/*.py",
     "--ignore-glob=site/*",
     "--strict-markers",
@@ -218,6 +226,7 @@ filterwarnings = [
     "ignore:Code. _pytestfixturefunction is not defined in namespace .*:UserWarning",
 ]
 markers = [
+    "testcontainer: mark a test that uses testcontainer",
     "webtest: mark a test as using the internet",
 ]
 # log_cli = true

rdflib/contrib/graphdb/__init__.py

@@ -0,0 +1,6 @@
+from rdflib.contrib.rdf4j import has_httpx
+
+if has_httpx:
+    from .client import GraphDBClient
+
+    __all__ = ["GraphDBClient"]

rdflib/contrib/graphdb/client.py

@@ -0,0 +1,61 @@
+import httpx
+
+import rdflib.contrib.rdf4j
+from rdflib.contrib.rdf4j import RDF4JClient
+from rdflib.contrib.rdf4j.exceptions import (
+    RepositoryNotFoundError,
+    RepositoryNotHealthyError,
+)
+
+
+class Repository(rdflib.contrib.rdf4j.client.Repository):
+    """GraphDB Repository"""
+
+    def health(self, timeout: int = 5) -> bool:
+        """Repository health check.
+
+        Parameters:
+            timeout: A timeout parameter in seconds. If provided, the endpoint attempts
+                to retrieve the repository within this timeout. If not, the passive
+                check is performed.
+
+        Returns:
+            bool: True if the repository is healthy, otherwise an error is raised.
+
+        Raises:
+            RepositoryNotFoundError: If the repository is not found.
+            RepositoryNotHealthyError: If the repository is not healthy.
+            httpx.RequestError: On network/connection issues.
+            httpx.HTTPStatusError: Unhandled status code error.
+        """
+        try:
+            params = {"passive": str(timeout)}
+            response = self.http_client.get(
+                f"/repositories/{self.identifier}/health", params=params
+            )
+            response.raise_for_status()
+            return True
+        except httpx.HTTPStatusError as err:
+            if err.response.status_code == 404:
+                raise RepositoryNotFoundError(
+                    f"Repository {self._identifier} not found."
+                )
+            raise RepositoryNotHealthyError(
+                f"Repository {self._identifier} is not healthy. {err.response.status_code} - {err.response.text}"
+            )
+        except httpx.RequestError:
+            raise
+
+
+class RepositoryManager(rdflib.contrib.rdf4j.client.RepositoryManager):
+    """GraphDB Repository Manager"""
+
+    def get(self, repository_id: str) -> Repository:
+        _repo = super().get(repository_id)
+        return Repository(_repo.identifier, _repo.http_client)
+
+
+class GraphDBClient(RDF4JClient):
+    """GraphDB Client"""
+
+    # TODO: GraphDB specific API methods.

rdflib/contrib/rdf4j/__init__.py

@@ -0,0 +1,10 @@
+from importlib.util import find_spec
+
+has_httpx = find_spec("httpx") is not None
+
+if has_httpx:
+    from .client import RDF4JClient
+
+    __all__ = ["RDF4JClient", "has_httpx"]
+else:
+    __all__ = ["has_httpx"]