rdf4j-python 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

rdf4j_python/__init__.py

@@ -2,13 +2,80 @@
 RDF4J Python is a Python library for interacting with RDF4J repositories.
 """
 
-from ._driver import AsyncNamedGraph, AsyncRdf4j, AsyncRdf4JRepository
-from .exception import *  # noqa: F403
-from .model import *  # noqa: F403
-from .utils import *  # noqa: F403
+from ._driver import (
+    AsyncNamedGraph,
+    AsyncRdf4j,
+    AsyncRdf4JRepository,
+    AsyncTransaction,
+    IsolationLevel,
+    TransactionState,
+)
+from .exception import (
+    NamespaceException,
+    NetworkError,
+    QueryError,
+    Rdf4jError,
+    RepositoryCreationException,
+    RepositoryDeletionException,
+    RepositoryError,
+    RepositoryInternalException,
+    RepositoryNotFoundException,
+    RepositoryUpdateException,
+    TransactionError,
+    TransactionStateError,
+)
+from .model import (
+    IRI,
+    BlankNode,
+    Context,
+    DefaultGraph,
+    Literal,
+    Namespace,
+    Object,
+    Predicate,
+    Quad,
+    QuadResultSet,
+    RepositoryMetadata,
+    Subject,
+    Triple,
+    Variable,
+)
 
 __all__ = [
+    # Main classes
     "AsyncRdf4j",
     "AsyncRdf4JRepository",
     "AsyncNamedGraph",
+    # Transaction
+    "AsyncTransaction",
+    "IsolationLevel",
+    "TransactionState",
+    # Exceptions
+    "Rdf4jError",
+    "RepositoryError",
+    "RepositoryCreationException",
+    "RepositoryDeletionException",
+    "RepositoryNotFoundException",
+    "RepositoryInternalException",
+    "RepositoryUpdateException",
+    "NamespaceException",
+    "NetworkError",
+    "QueryError",
+    "TransactionError",
+    "TransactionStateError",
+    # Model types
+    "Namespace",
+    "RepositoryMetadata",
+    "IRI",
+    "BlankNode",
+    "Literal",
+    "DefaultGraph",
+    "Variable",
+    "Quad",
+    "Triple",
+    "Subject",
+    "Predicate",
+    "Object",
+    "Context",
+    "QuadResultSet",
 ]

rdf4j_python/_client/_client.py

@@ -1,7 +1,11 @@
-from typing import Any, Dict, Optional
+import logging
+from types import TracebackType
+from typing import Any, Self
 
 import httpx
 
+logger = logging.getLogger("rdf4j_python")
+
 
 class BaseClient:
     """Base HTTP client that provides shared URL building functionality."""
@@ -42,18 +46,20 @@ class BaseClient:
 class SyncApiClient(BaseClient):
     """Synchronous API client using httpx.Client."""
 
-    def __init__(self, base_url: str, timeout: int = 10):
+    def __init__(self, base_url: str, timeout: int = 10, retries: int = 3) -> None:
         """
         Initializes the SyncApiClient.
 
         Args:
             base_url (str): The base URL for the API endpoints.
             timeout (int, optional): Request timeout in seconds. Defaults to 10.
+            retries (int, optional): Number of retries for failed requests. Defaults to 3.
         """
         super().__init__(base_url, timeout)
-        self.client = httpx.Client(timeout=self.timeout)
+        transport = httpx.HTTPTransport(retries=retries)
+        self.client = httpx.Client(timeout=self.timeout, transport=transport)
 
-    def __enter__(self):
+    def __enter__(self) -> Self:
         """
         Enters the context and initializes the HTTP client.
 
@@ -63,7 +69,12 @@ class SyncApiClient(BaseClient):
         self.client.__enter__()
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
         """
         Exits the context and closes the HTTP client.
         """
@@ -72,99 +83,129 @@ class SyncApiClient(BaseClient):
     def get(
         self,
         path: str,
-        params: Optional[Dict[str, Any]] = None,
-        headers: Optional[Dict[str, str]] = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
     ) -> httpx.Response:
         """
         Sends a GET request.
 
         Args:
             path (str): API endpoint path.
-            params (Optional[Dict[str, Any]]): Query parameters.
-            headers (Optional[Dict[str, str]]): Request headers.
+            params (dict[str, Any] | None): Query parameters.
+            headers (dict[str, str] | None): Request headers.
 
         Returns:
             httpx.Response: The HTTP response.
         """
-        return self.client.get(self._build_url(path), params=params, headers=headers)
+        url = self._build_url(path)
+        logger.debug("GET %s params=%s", url, params)
+        response = self.client.get(url, params=params, headers=headers)
+        logger.debug("Response %s: %s bytes", response.status_code, len(response.content))
+        return response
 
     def post(
         self,
         path: str,
-        data: Optional[Dict[str, Any]] = None,
-        json: Optional[Any] = None,
-        headers: Optional[Dict[str, str]] = None,
+        content: str | bytes | None = None,
+        json: Any | None = None,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
     ) -> httpx.Response:
         """
         Sends a POST request.
 
         Args:
             path (str): API endpoint path.
-            data (Optional[Dict[str, Any]]): Form-encoded body data.
-            json (Optional[Any]): JSON-encoded body data.
-            headers (Optional[Dict[str, str]]): Request headers.
+            content (str | bytes | None): Raw content to include in the request body.
+            json (Any | None): JSON-encoded body data.
+            headers (dict[str, str] | None): Request headers.
+            params (dict[str, Any] | None): Query parameters.
 
         Returns:
             httpx.Response: The HTTP response.
         """
-        return self.client.post(
-            self._build_url(path), data=data, json=json, headers=headers
+        url = self._build_url(path)
+        logger.debug("POST %s params=%s", url, params)
+        response = self.client.post(
+            url, content=content, json=json, headers=headers, params=params
         )
+        logger.debug("Response %s: %s bytes", response.status_code, len(response.content))
+        return response
 
     def put(
         self,
         path: str,
-        data: Optional[Dict[str, Any]] = None,
-        json: Optional[Any] = None,
-        headers: Optional[Dict[str, str]] = None,
+        content: str | bytes | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        headers: dict[str, str] | None = None,
     ) -> httpx.Response:
         """
         Sends a PUT request.
 
         Args:
             path (str): API endpoint path.
-            data (Optional[Dict[str, Any]]): Form-encoded body data.
-            json (Optional[Any]): JSON-encoded body data.
-            headers (Optional[Dict[str, str]]): Request headers.
+            content (str | bytes | None): Raw content to include in the request body.
+            params (dict[str, Any] | None): Query parameters.
+            json (Any | None): JSON-encoded body data.
+            headers (dict[str, str] | None): Request headers.
 
         Returns:
             httpx.Response: The HTTP response.
         """
-        return self.client.put(
-            self._build_url(path), data=data, json=json, headers=headers
+        url = self._build_url(path)
+        logger.debug("PUT %s params=%s", url, params)
+        response = self.client.put(
+            url,
+            content=content,
+            json=json,
+            headers=headers,
+            params=params,
         )
+        logger.debug("Response %s: %s bytes", response.status_code, len(response.content))
+        return response
 
     def delete(
-        self, path: str, headers: Optional[Dict[str, str]] = None
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
     ) -> httpx.Response:
         """
         Sends a DELETE request.
 
         Args:
             path (str): API endpoint path.
-            headers (Optional[Dict[str, str]]): Request headers.
+            params (dict[str, Any] | None): Query parameters.
+            headers (dict[str, str] | None): Request headers.
 
         Returns:
             httpx.Response: The HTTP response.
         """
-        return self.client.delete(self._build_url(path), headers=headers)
+        url = self._build_url(path)
+        logger.debug("DELETE %s params=%s", url, params)
+        response = self.client.delete(url, params=params, headers=headers)
+        logger.debug("Response %s: %s bytes", response.status_code, len(response.content))
+        return response
 
 
 class AsyncApiClient(BaseClient):
     """Asynchronous API client using httpx.AsyncClient."""
 
-    def __init__(self, base_url: str, timeout: int = 10):
+    def __init__(self, base_url: str, timeout: int = 10, retries: int = 3) -> None:
         """
         Initializes the AsyncApiClient.
 
         Args:
             base_url (str): The base URL for the API endpoints.
             timeout (int, optional): Request timeout in seconds. Defaults to 10.
+            retries (int, optional): Number of retries for failed requests. Defaults to 3.
         """
         super().__init__(base_url, timeout)
-        self.client = httpx.AsyncClient(timeout=self.timeout)
+        transport = httpx.AsyncHTTPTransport(retries=retries)
+        self.client = httpx.AsyncClient(timeout=self.timeout, transport=transport)
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> Self:
         """
         Enters the async context and initializes the HTTP client.
 
@@ -174,7 +215,12 @@ class AsyncApiClient(BaseClient):
         await self.client.__aenter__()
         return self
 
-    async def __aexit__(self, exc_type, exc_value, traceback):
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
         """
         Exits the async context and closes the HTTP client.
         """
@@ -183,99 +229,114 @@ class AsyncApiClient(BaseClient):
     async def get(
         self,
         path: str,
-        params: Optional[Dict[str, Any]] = None,
-        headers: Optional[Dict[str, str]] = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
     ) -> httpx.Response:
         """
         Sends an asynchronous GET request.
 
         Args:
             path (str): API endpoint path.
-            params (Optional[Dict[str, Any]]): Query parameters.
-            headers (Optional[Dict[str, str]]): Request headers.
+            params (dict[str, Any] | None): Query parameters.
+            headers (dict[str, str] | None): Request headers.
 
         Returns:
             httpx.Response: The HTTP response.
         """
-        return await self.client.get(
-            self._build_url(path), params=params, headers=headers
-        )
+        url = self._build_url(path)
+        logger.debug("GET %s params=%s", url, params)
+        response = await self.client.get(url, params=params, headers=headers)
+        logger.debug("Response %s: %s bytes", response.status_code, len(response.content))
+        return response
 
     async def post(
         self,
         path: str,
-        content: Optional[str] = None,
-        json: Optional[Any] = None,
-        headers: Optional[Dict[str, str]] = None,
+        content: str | bytes | None = None,
+        json: Any | None = None,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
     ) -> httpx.Response:
         """
         Sends an asynchronous POST request.
 
         Args:
             path (str): API endpoint path.
-            content (Optional[str]): Raw string content to include in the request body.
-            json (Optional[Any]): JSON-encoded body data.
-            headers (Optional[Dict[str, str]]): Request headers.
+            content (str | bytes | None): Raw content to include in the request body.
+            json (Any | None): JSON-encoded body data.
+            headers (dict[str, str] | None): Request headers.
+            params (dict[str, Any] | None): Query parameters.
 
         Returns:
             httpx.Response: The HTTP response.
         """
-        return await self.client.post(
-            self._build_url(path), content=content, json=json, headers=headers
+        url = self._build_url(path)
+        logger.debug("POST %s params=%s", url, params)
+        response = await self.client.post(
+            url, content=content, json=json, headers=headers, params=params
         )
+        logger.debug("Response %s: %s bytes", response.status_code, len(response.content))
+        return response
 
     async def put(
         self,
         path: str,
-        content: Optional[bytes] = None,
-        params: Optional[Dict[str, Any]] = None,
-        json: Optional[Any] = None,
-        headers: Optional[Dict[str, str]] = None,
+        content: str | bytes | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        headers: dict[str, str] | None = None,
     ) -> httpx.Response:
         """
         Sends an asynchronous PUT request.
 
         Args:
             path (str): API endpoint path.
-            content (Optional[bytes]): Raw bytes to include in the request body.
-            params (Optional[Dict[str, Any]]): Query parameters.
-            json (Optional[Any]): JSON-encoded body data.
-            headers (Optional[Dict[str, str]]): Request headers.
+            content (str | bytes | None): Raw content to include in the request body.
+            params (dict[str, Any] | None): Query parameters.
+            json (Any | None): JSON-encoded body data.
+            headers (dict[str, str] | None): Request headers.
 
         Returns:
             httpx.Response: The HTTP response.
         """
-        return await self.client.put(
-            self._build_url(path),
+        url = self._build_url(path)
+        logger.debug("PUT %s params=%s", url, params)
+        response = await self.client.put(
+            url,
             content=content,
             json=json,
             headers=headers,
             params=params,
         )
+        logger.debug("Response %s: %s bytes", response.status_code, len(response.content))
+        return response
 
     async def delete(
         self,
         path: str,
-        params: Optional[Dict[str, Any]] = None,
-        headers: Optional[Dict[str, str]] = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
     ) -> httpx.Response:
         """
         Sends an asynchronous DELETE request.
 
         Args:
             path (str): API endpoint path.
-            params (Optional[Dict[str, Any]]): Query parameters.
-            headers (Optional[Dict[str, str]]): Request headers.
+            params (dict[str, Any] | None): Query parameters.
+            headers (dict[str, str] | None): Request headers.
 
         Returns:
             httpx.Response: The HTTP response.
         """
-        return await self.client.delete(
-            self._build_url(path), params=params, headers=headers
-        )
+        url = self._build_url(path)
+        logger.debug("DELETE %s params=%s", url, params)
+        response = await self.client.delete(url, params=params, headers=headers)
+        logger.debug("Response %s: %s bytes", response.status_code, len(response.content))
+        return response
 
-    async def aclose(self):
+    async def aclose(self) -> None:
         """
         Asynchronously closes the client connection.
         """
+        logger.debug("Closing async client connection")
         await self.client.aclose()

rdf4j_python/_driver/__init__.py

@@ -1,9 +1,13 @@
 from ._async_named_graph import AsyncNamedGraph
 from ._async_rdf4j_db import AsyncRdf4j
 from ._async_repository import AsyncRdf4JRepository
+from ._async_transaction import AsyncTransaction, IsolationLevel, TransactionState
 
 __all__ = [
     "AsyncRdf4j",
     "AsyncRdf4JRepository",
     "AsyncNamedGraph",
+    "AsyncTransaction",
+    "IsolationLevel",
+    "TransactionState",
 ]

rdf4j_python/_driver/_async_rdf4j_db.py

@@ -1,3 +1,6 @@
+from types import TracebackType
+from typing import Self
+
 import httpx
 import pyoxigraph as og
 
@@ -28,16 +31,21 @@ class AsyncRdf4j:
         self._base_url = base_url.rstrip("/")
         self._client = AsyncApiClient(base_url=self._base_url)
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> Self:
         """Enters the async context and initializes the HTTP client.
 
         Returns:
             AsyncRdf4j: The initialized RDF4J interface.
         """
-        self._client = await self._client.__aenter__()
+        await self._client.__aenter__()
         return self
 
-    async def __aexit__(self, exc_type, exc_value, traceback):
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
         """Closes the HTTP client when exiting the async context."""
         await self._client.__aexit__(exc_type, exc_value, traceback)
 
@@ -70,7 +78,10 @@ class AsyncRdf4j:
         query_solutions = og.parse_query_results(
             response.text, format=og.QueryResultsFormat.JSON
         )
-        assert isinstance(query_solutions, og.QuerySolutions)
+        if not isinstance(query_solutions, og.QuerySolutions):
+            raise TypeError(
+                f"Expected QuerySolutions, got {type(query_solutions).__name__}"
+            )
         return [
             RepositoryMetadata.from_sparql_query_solution(query_solution)
             for query_solution in query_solutions
@@ -114,7 +125,7 @@ class AsyncRdf4j:
             )
         return AsyncRdf4JRepository(self._client, config.repo_id)
 
-    async def delete_repository(self, repository_id: str):
+    async def delete_repository(self, repository_id: str) -> None:
         """Deletes a repository and all its data and configuration.
 
         Args:
@@ -130,6 +141,29 @@ class AsyncRdf4j:
                 f"Failed to delete repository '{repository_id}': {response.status_code} - {response.text}"
             )
 
-    async def aclose(self):
+    async def health_check(self) -> bool:
+        """Checks if the RDF4J server is reachable and healthy.
+
+        This method attempts to fetch the protocol version from the server
+        to verify connectivity.
+
+        Returns:
+            bool: True if the server is reachable and responds correctly,
+                  False otherwise.
+
+        Example:
+            >>> async with AsyncRdf4j("http://localhost:8080/rdf4j-server") as db:
+            ...     if await db.health_check():
+            ...         print("Server is healthy")
+            ...     else:
+            ...         print("Server is not reachable")
+        """
+        try:
+            response = await self._client.get("/protocol")
+            return response.status_code == httpx.codes.OK
+        except Exception:
+            return False
+
+    async def aclose(self) -> None:
         """Asynchronously closes the client connection."""
         await self._client.aclose()