rdf4j-python 0.1.1a0__py3-none-any.whl → 0.1.3__py3-none-any.whl

rdf4j_python/__init__.py

@@ -1,9 +1,14 @@
-from ._client import AsyncApiClient, SyncApiClient
-from ._driver import AsyncRdf4j, AsyncRdf4JRepository
+"""
+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
 
 __all__ = [
-    "AsyncApiClient",
-    "SyncApiClient",
     "AsyncRdf4j",
     "AsyncRdf4JRepository",
+    "AsyncNamedGraph",
 ]

rdf4j_python/_client/_client.py

@@ -4,20 +4,58 @@ import httpx
 
 
 class BaseClient:
+    """Base HTTP client that provides shared URL building functionality."""
+
     def __init__(self, base_url: str, timeout: int = 10):
+        """
+        Initializes a BaseClient.
+
+        Args:
+            base_url (str): The base URL for the API endpoints.
+            timeout (int, optional): Request timeout in seconds. Defaults to 10.
+        """
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
 
     def _build_url(self, path: str) -> str:
+        """
+        Builds a full URL by combining the base URL and the given path.
+
+        Args:
+            path (str): The path to append to the base URL.
+
+        Returns:
+            str: The full URL.
+        """
         return f"{self.base_url}/{path.lstrip('/')}"
 
+    def get_base_url(self) -> str:
+        """
+        Returns the base URL.
+
+        Returns:
+            str: The base URL.
+        """
+        return self.base_url
+
 
 class SyncApiClient(BaseClient):
+    """Synchronous API client using httpx.Client."""
+
     def __enter__(self):
+        """
+        Enters the context and initializes the HTTP client.
+
+        Returns:
+            SyncApiClient: The instance of the client.
+        """
         self.client = httpx.Client(timeout=self.timeout).__enter__()
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):
+        """
+        Exits the context and closes the HTTP client.
+        """
         self.client.__exit__(exc_type, exc_value, traceback)
 
     def get(
@@ -26,6 +64,17 @@ class SyncApiClient(BaseClient):
         params: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = 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.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
         return self.client.get(self._build_url(path), params=params, headers=headers)
 
     def post(
@@ -35,6 +84,18 @@ class SyncApiClient(BaseClient):
         json: Optional[Any] = None,
         headers: Optional[Dict[str, str]] = 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.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
         return self.client.post(
             self._build_url(path), data=data, json=json, headers=headers
         )
@@ -46,6 +107,18 @@ class SyncApiClient(BaseClient):
         json: Optional[Any] = None,
         headers: Optional[Dict[str, str]] = 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.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
         return self.client.put(
             self._build_url(path), data=data, json=json, headers=headers
         )
@@ -53,15 +126,36 @@ class SyncApiClient(BaseClient):
     def delete(
         self, path: str, headers: Optional[Dict[str, str]] = None
     ) -> httpx.Response:
+        """
+        Sends a DELETE request.
+
+        Args:
+            path (str): API endpoint path.
+            headers (Optional[Dict[str, str]]): Request headers.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
         return self.client.delete(self._build_url(path), headers=headers)
 
 
 class AsyncApiClient(BaseClient):
+    """Asynchronous API client using httpx.AsyncClient."""
+
     async def __aenter__(self):
+        """
+        Enters the async context and initializes the HTTP client.
+
+        Returns:
+            AsyncApiClient: The instance of the client.
+        """
         self.client = await httpx.AsyncClient(timeout=self.timeout).__aenter__()
         return self
 
     async def __aexit__(self, exc_type, exc_value, traceback):
+        """
+        Exits the async context and closes the HTTP client.
+        """
         await self.client.__aexit__(exc_type, exc_value, traceback)
 
     async def get(
@@ -70,6 +164,17 @@ class AsyncApiClient(BaseClient):
         params: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = 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.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
         return await self.client.get(
             self._build_url(path), params=params, headers=headers
         )
@@ -77,26 +182,72 @@ class AsyncApiClient(BaseClient):
     async def post(
         self,
         path: str,
-        data: Optional[Dict[str, Any]] = None,
+        content: Optional[str] = None,
         json: Optional[Any] = None,
         headers: Optional[Dict[str, str]] = 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.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
         return await self.client.post(
-            self._build_url(path), data=data, json=json, headers=headers
+            self._build_url(path), content=content, json=json, headers=headers
         )
 
     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,
     ) -> 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.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
         return await self.client.put(
-            self._build_url(path), content=content, json=json, headers=headers
+            self._build_url(path),
+            content=content,
+            json=json,
+            headers=headers,
+            params=params,
         )
 
     async def delete(
-        self, path: str, headers: Optional[Dict[str, str]] = None
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
     ) -> httpx.Response:
-        return await self.client.delete(self._build_url(path), headers=headers)
+        """
+        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.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
+        return await self.client.delete(
+            self._build_url(path), params=params, headers=headers
+        )

rdf4j_python/_driver/__init__.py

@@ -1,7 +1,9 @@
+from ._async_named_graph import AsyncNamedGraph
 from ._async_rdf4j_db import AsyncRdf4j
 from ._async_repository import AsyncRdf4JRepository
 
 __all__ = [
     "AsyncRdf4j",
     "AsyncRdf4JRepository",
+    "AsyncNamedGraph",
 ]

rdf4j_python/_driver/_async_named_graph.py

@@ -0,0 +1,76 @@
+from typing import Iterable
+
+import pyoxigraph as og
+
+from rdf4j_python._client import AsyncApiClient
+from rdf4j_python.model.term import IRI, Quad, QuadResultSet, Triple
+from rdf4j_python.utils.const import Rdf4jContentType
+from rdf4j_python.utils.helpers import serialize_statements
+
+
+class AsyncNamedGraph:
+    """Asynchronous interface for operations on a specific RDF4J named graph."""
+
+    def __init__(self, client: AsyncApiClient, repository_id: str, graph_uri: str):
+        """Initializes the AsyncNamedGraph.
+
+        Args:
+            client (AsyncApiClient): The RDF4J HTTP client.
+            repository_id (str): The ID of the RDF4J repository.
+            graph_uri (str): The URI identifying the named graph.
+        """
+        self._client = client
+        self._repository_id = repository_id
+        self._graph_uri = graph_uri
+
+    async def get(self) -> QuadResultSet:
+        """Fetches all RDF statements from this named graph.
+
+        Returns:
+            QuadResultSet: RDF data serialized in the requested format.
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails.
+        """
+        path = f"/repositories/{self._repository_id}/rdf-graphs/{self._graph_uri}"
+        headers = {"Accept": Rdf4jContentType.NQUADS}
+        response = await self._client.get(path, headers=headers)
+        response.raise_for_status()
+        return og.parse(response.content, format=og.RdfFormat.N_QUADS)
+
+    async def add(self, statements: Iterable[Quad] | Iterable[Triple]):
+        """Adds RDF statements to this named graph.
+
+        Args:
+            statements (Iterable[Quad] | Iterable[Triple]): RDF statements to add.
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails.
+        """
+        path = f"/repositories/{self._repository_id}/rdf-graphs/{self._graph_uri}"
+        headers = {"Content-Type": Rdf4jContentType.NQUADS}
+        response = await self._client.post(
+            path, content=serialize_statements(statements), headers=headers
+        )
+        response.raise_for_status()
+
+    async def clear(self):
+        """Deletes all statements from this named graph.
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails.
+        """
+        path = f"/repositories/{self._repository_id}/rdf-graphs/{self._graph_uri}"
+        response = await self._client.delete(path)
+        response.raise_for_status()
+
+    @property
+    def iri(self) -> IRI:
+        """Returns the IRI of the named graph.
+
+        Returns:
+            str: The graph IRI.
+        """
+        return IRI(
+            f"{self._client.get_base_url()}/repositories/{self._repository_id}/rdf-graphs/{self._graph_uri}"
+        )

rdf4j_python/_driver/_async_rdf4j_db.py

@@ -1,99 +1,125 @@
-from typing import Union
-
 import httpx
-import rdflib
+import pyoxigraph as og
 
-from rdf4j_python import AsyncApiClient
+from rdf4j_python._client import AsyncApiClient
 from rdf4j_python.exception.repo_exception import (
     RepositoryCreationException,
     RepositoryDeletionException,
 )
 from rdf4j_python.model._repository_info import RepositoryMetadata
+from rdf4j_python.model.repository_config import RepositoryConfig
 from rdf4j_python.utils.const import Rdf4jContentType
 
 from ._async_repository import AsyncRdf4JRepository
 
 
 class AsyncRdf4j:
+    """Asynchronous entry point for interacting with an RDF4J server."""
+
     _client: AsyncApiClient
     _base_url: str
 
     def __init__(self, base_url: str):
+        """Initializes the RDF4J API client.
+
+        Args:
+            base_url (str): Base URL of the RDF4J server.
+        """
         self._base_url = base_url.rstrip("/")
 
     async def __aenter__(self):
+        """Enters the async context and initializes the HTTP client.
+
+        Returns:
+            AsyncRdf4j: The initialized RDF4J interface.
+        """
         self._client = await AsyncApiClient(base_url=self._base_url).__aenter__()
         return self
 
     async def __aexit__(self, exc_type, exc_value, traceback):
+        """Closes the HTTP client when exiting the async context."""
         await self._client.__aexit__(exc_type, exc_value, traceback)
 
     async def get_protocol_version(self) -> str:
+        """Fetches the RDF4J protocol version.
+
+        Returns:
+            str: The protocol version string.
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails.
+        """
         response = await self._client.get("/protocol")
         response.raise_for_status()
         return response.text
 
     async def list_repositories(self) -> list[RepositoryMetadata]:
-        """
-        List all RDF4J repositories.
+        """Lists all available RDF4J repositories.
+
+        Returns:
+            list[RepositoryMetadata]: A list of repository metadata objects.
 
-        :return: List of repository information.
+        Raises:
+            httpx.HTTPStatusError: If the request fails.
         """
         response = await self._client.get(
             "/repositories",
             headers={"Accept": Rdf4jContentType.SPARQL_RESULTS_JSON},
         )
-        result = rdflib.query.Result.parse(
-            response, format=Rdf4jContentType.SPARQL_RESULTS_JSON
+        query_solutions = og.parse_query_results(
+            response.text, format=og.QueryResultsFormat.JSON
         )
-
         return [
-            RepositoryMetadata.from_rdflib_binding(binding)
-            for binding in result.bindings
+            RepositoryMetadata.from_sparql_query_solution(query_solution)
+            for query_solution in query_solutions
         ]
 
     async def get_repository(self, repository_id: str) -> AsyncRdf4JRepository:
-        """
-        Get an AsyncRepository instance for the specified repository ID.
+        """Gets an interface to a specific RDF4J repository.
+
+        Args:
+            repository_id (str): The ID of the repository.
 
-        :param repository_id: The ID of the repository.
-        :return: An instance of AsyncRepository.
+        Returns:
+            AsyncRdf4JRepository: An async interface for the repository.
         """
         return AsyncRdf4JRepository(self._client, repository_id)
 
     async def create_repository(
         self,
-        repository_id: str,
-        rdf_config_data: str,
-        content_type: Union[Rdf4jContentType, str] = Rdf4jContentType.TURTLE,
+        config: RepositoryConfig,
     ) -> AsyncRdf4JRepository:
-        """
-        Create a new RDF4J repository.
+        """Creates a new RDF4J repository using RDF configuration.
 
-        :param repository_id: Repository ID to create.
-        :param rdf_config_data: RDF config in Turtle, RDF/XML, etc.
-        :param content_type: MIME type of RDF config.
-        """
-        path = f"/repositories/{repository_id}"
+        Args:
+            repository_id (str): The repository ID to create.
+            config (RepositoryConfig): RDF configuration.
 
-        if isinstance(content_type, Rdf4jContentType):
-            content_type = content_type.value
-        headers = {"Content-Type": content_type}
+        Returns:
+            AsyncRdf4JRepository: An async interface to the newly created repository.
 
+        Raises:
+            RepositoryCreationException: If repository creation fails.
+        """
+        path = f"/repositories/{config.repo_id}"
+        headers = {"Content-Type": Rdf4jContentType.TURTLE}
         response: httpx.Response = await self._client.put(
-            path, content=rdf_config_data, headers=headers
+            path, content=config.to_turtle(), headers=headers
         )
         if response.status_code != httpx.codes.NO_CONTENT:
             raise RepositoryCreationException(
                 f"Repository creation failed: {response.status_code} - {response.text}"
             )
-        return AsyncRdf4JRepository(self._client, repository_id)
+        return AsyncRdf4JRepository(self._client, config.repo_id)
 
     async def delete_repository(self, repository_id: str):
-        """
-        Delete an RDF4J repository and its data/config.
+        """Deletes a repository and all its data and configuration.
+
+        Args:
+            repository_id (str): The ID of the repository to delete.
 
-        :param repository_id: The repository ID to delete.
+        Raises:
+            RepositoryDeletionException: If the deletion fails.
         """
         path = f"/repositories/{repository_id}"
         response = await self._client.delete(path)