rdf4j-python 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

rdf4j_python/_driver/_async_repository.py

@@ -1,9 +1,41 @@
-from rdf4j_python import AsyncApiClient
+from typing import Iterable, Optional
+
+import httpx
+import rdflib
+import rdflib.resource
+import rdflib.serializer
+import rdflib.store
+
+from rdf4j_python._client import AsyncApiClient
+from rdf4j_python._driver._async_named_graph import AsyncNamedGraph
+from rdf4j_python.exception.repo_exception import (
+    NamespaceException,
+    RepositoryInternalException,
+    RepositoryNotFoundException,
+    RepositoryUpdateException,
+)
+from rdf4j_python.model import Namespace, RDF4JDataSet
+from rdf4j_python.model.term import (
+    Context,
+    Object,
+    Predicate,
+    RDFStatement,
+    Subject,
+)
 from rdf4j_python.utils.const import Rdf4jContentType
+from rdf4j_python.utils.helpers import serialize_statements
+
 
+class AsyncRdf4JRepository:
+    """Asynchronous interface for interacting with an RDF4J repository."""
 
-class AsyncRepository:
     def __init__(self, client: AsyncApiClient, repository_id: str):
+        """Initializes the repository interface.
+
+        Args:
+            client (AsyncApiClient): The RDF4J API client.
+            repository_id (str): The ID of the RDF4J repository.
+        """
         self._client = client
         self._repository_id = repository_id
 
@@ -13,39 +45,338 @@ class AsyncRepository:
         infer: bool = True,
         accept: Rdf4jContentType = Rdf4jContentType.SPARQL_RESULTS_JSON,
     ):
+        """Executes a SPARQL SELECT query.
+
+        Args:
+            sparql_query (str): The SPARQL query string.
+            infer (bool): Whether to include inferred statements. Defaults to True.
+            accept (Rdf4jContentType): The expected response format.
+
+        Returns:
+            dict or str: Parsed JSON results or raw response text.
+        """
         path = f"/repositories/{self._repository_id}"
         params = {"query": sparql_query, "infer": str(infer).lower()}
         headers = {"Accept": accept.value}
         response = await self._client.get(path, params=params, headers=headers)
+        self._handle_repo_not_found_exception(response)
         if "json" in response.headers.get("Content-Type", ""):
             return response.json()
         return response.text
 
     async def update(self, sparql_update: str):
+        """Executes a SPARQL UPDATE command.
+
+        Args:
+            sparql_update (str): The SPARQL update string.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            httpx.HTTPStatusError: If the update fails.
+        """
         path = f"/repositories/{self._repository_id}/statements"
         headers = {"Content-Type": Rdf4jContentType.SPARQL_UPDATE.value}
         response = await self._client.post(path, data=sparql_update, headers=headers)
-        response.raise_for_status()
-
-    async def replace_statements(
-        self, rdf_data: str, content_type: Rdf4jContentType = Rdf4jContentType.TURTLE
-    ):
-        path = f"/repositories/{self._repository_id}/statements"
-        headers = {"Content-Type": content_type.value}
-        response = await self._client.put(path, data=rdf_data, headers=headers)
+        self._handle_repo_not_found_exception(response)
         response.raise_for_status()
 
     async def get_namespaces(self):
+        """Retrieves all namespaces in the repository.
+
+        Returns:
+            list[Namespace]: A list of namespace objects.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+        """
         path = f"/repositories/{self._repository_id}/namespaces"
-        response = await self._client.get(path)
-        if Rdf4jContentType.SPARQL_RESULTS_JSON in response.headers.get(
-            "Content-Type", ""
-        ):
-            return response.json()
-        return response.text
+        headers = {"Accept": Rdf4jContentType.SPARQL_RESULTS_JSON}
+        response = await self._client.get(path, headers=headers)
+        result = rdflib.query.Result.parse(
+            response, format=Rdf4jContentType.SPARQL_RESULTS_JSON
+        )
+        self._handle_repo_not_found_exception(response)
+        return [Namespace.from_rdflib_binding(binding) for binding in result.bindings]
 
     async def set_namespace(self, prefix: str, namespace: str):
+        """Sets a namespace prefix.
+
+        Args:
+            prefix (str): The namespace prefix.
+            namespace (str): The namespace URI.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            NamespaceException: If the request fails.
+        """
         path = f"/repositories/{self._repository_id}/namespaces/{prefix}"
         headers = {"Content-Type": Rdf4jContentType.NTRIPLES.value}
-        response = await self._client.put(path, data=namespace, headers=headers)
+        response = await self._client.put(path, content=namespace, headers=headers)
+        self._handle_repo_not_found_exception(response)
+        if response.status_code != httpx.codes.NO_CONTENT:
+            raise NamespaceException(f"Failed to set namespace: {response.text}")
+
+    async def get_namespace(self, prefix: str) -> Namespace:
+        """Gets a namespace by its prefix.
+
+        Args:
+            prefix (str): The namespace prefix.
+
+        Returns:
+            Namespace: The namespace object.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            NamespaceException: If retrieval fails.
+        """
+        path = f"/repositories/{self._repository_id}/namespaces/{prefix}"
+        headers = {"Accept": Rdf4jContentType.NTRIPLES.value}
+        response = await self._client.get(path, headers=headers)
+        self._handle_repo_not_found_exception(response)
+
+        if response.status_code != httpx.codes.OK:
+            raise NamespaceException(f"Failed to get namespace: {response.text}")
+
+        return Namespace(prefix, response.text)
+
+    async def delete_namespace(self, prefix: str):
+        """Deletes a namespace by prefix.
+
+        Args:
+            prefix (str): The namespace prefix.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            httpx.HTTPStatusError: If deletion fails.
+        """
+        path = f"/repositories/{self._repository_id}/namespaces/{prefix}"
+        response = await self._client.delete(path)
+        self._handle_repo_not_found_exception(response)
         response.raise_for_status()
+
+    async def clear_all_namespaces(self):
+        """Removes all namespaces from the repository.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            httpx.HTTPStatusError: If clearing fails.
+        """
+        path = f"/repositories/{self._repository_id}/namespaces"
+        response = await self._client.delete(path)
+        self._handle_repo_not_found_exception(response)
+        response.raise_for_status()
+
+    async def size(self) -> int:
+        """Gets the number of statements in the repository.
+
+        Returns:
+            int: The total number of RDF statements.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            RepositoryInternalException: If retrieval fails.
+        """
+        path = f"/repositories/{self._repository_id}/size"
+        response = await self._client.get(path)
+        self._handle_repo_not_found_exception(response)
+
+        if response.status_code != httpx.codes.OK:
+            raise RepositoryInternalException(f"Failed to get size: {response.text}")
+
+        return int(response.text.strip())
+
+    async def get_statements(
+        self,
+        subject: Optional[Subject] = None,
+        predicate: Optional[Predicate] = None,
+        object_: Optional[Object] = None,
+        contexts: Optional[list[Context]] = None,
+        infer: bool = True,
+    ) -> RDF4JDataSet:
+        """Retrieves statements matching the given pattern.
+
+        Args:
+            subject (Optional[Subject]): Filter by subject.
+            predicate (Optional[Predicate]): Filter by predicate.
+            object_ (Optional[Object]): Filter by object.
+            contexts (Optional[list[Context]]): Filter by context (named graph).
+
+        Returns:
+            DataSet: Dataset of matching RDF statements.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+        """
+        path = f"/repositories/{self._repository_id}/statements"
+        params = {}
+
+        if subject:
+            params["subj"] = subject.n3()
+        if predicate:
+            params["pred"] = predicate.n3()
+        if object_:
+            params["obj"] = object_.n3()
+        if contexts:
+            params["context"] = [ctx.n3() for ctx in contexts]
+        params["infer"] = str(infer).lower()
+
+        headers = {"Accept": Rdf4jContentType.NQUADS}
+        response = await self._client.get(path, params=params, headers=headers)
+        dataset = RDF4JDataSet()
+        dataset.parse(data=response.text, format="nquads")
+        return dataset
+
+    async def delete_statements(
+        self,
+        subject: Optional[Subject] = None,
+        predicate: Optional[Predicate] = None,
+        object_: Optional[Object] = None,
+        contexts: Optional[list[Context]] = None,
+    ):
+        """Deletes statements from the repository matching the given pattern.
+
+        Args:
+            subject (Optional[Subject]): Filter by subject (N-Triples encoded).
+            predicate (Optional[Predicate]): Filter by predicate (N-Triples encoded).
+            object_ (Optional[Object]): Filter by object (N-Triples encoded).
+            contexts (Optional[list[Context]]): One or more specific contexts to restrict deletion to.
+                Use 'null' as a string to delete context-less statements.
+
+        Raises:
+            RepositoryNotFoundException: If the repository does not exist.
+            RepositoryUpdateException: If the deletion fails.
+        """
+        path = f"/repositories/{self._repository_id}/statements"
+        params = {}
+
+        if subject:
+            params["subj"] = subject.n3()
+        if predicate:
+            params["pred"] = predicate.n3()
+        if object_:
+            params["obj"] = object_.n3()
+        if contexts:
+            params["context"] = [ctx.n3() for ctx in contexts]
+
+        response = await self._client.delete(path, params=params)
+        self._handle_repo_not_found_exception(response)
+
+        if response.status_code != httpx.codes.NO_CONTENT:
+            raise RepositoryUpdateException(
+                f"Failed to delete statements: {response.text}"
+            )
+
+    async def add_statement(
+        self,
+        subject: Subject,
+        predicate: Predicate,
+        object: Object,
+        context: Optional[Context] = None,
+    ):
+        """Adds a single RDF statement to the repository.
+
+        Args:
+            subject (Node): The subject of the triple.
+            predicate (Node): The predicate of the triple.
+            object (Node): The object of the triple.
+            context (IdentifiedNode): The context (named graph).
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            httpx.HTTPStatusError: If addition fails.
+        """
+        path = f"/repositories/{self._repository_id}/statements"
+        response = await self._client.post(
+            path,
+            content=serialize_statements([(subject, predicate, object, context)]),
+            headers={"Content-Type": Rdf4jContentType.NQUADS},
+        )
+        self._handle_repo_not_found_exception(response)
+        if response.status_code != httpx.codes.NO_CONTENT:
+            raise RepositoryUpdateException(f"Failed to add statement: {response.text}")
+
+    async def add_statements(self, statements: Iterable[RDFStatement]):
+        """Adds a list of RDF statements to the repository.
+
+        Args:
+            statements (Iterable[RDFStatement]): A list of RDF statements.
+            RDFStatement: A tuple of subject, predicate, object, and context.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            httpx.HTTPStatusError: If addition fails.
+        """
+        path = f"/repositories/{self._repository_id}/statements"
+        response = await self._client.post(
+            path,
+            content=serialize_statements(statements),
+            headers={"Content-Type": Rdf4jContentType.NQUADS},
+        )
+        self._handle_repo_not_found_exception(response)
+        if response.status_code != httpx.codes.NO_CONTENT:
+            raise RepositoryUpdateException(
+                f"Failed to add statements: {response.text}"
+            )
+
+    async def replace_statements(
+        self,
+        statements: Iterable[RDFStatement],
+        contexts: Optional[list[Context]] = None,
+        base_uri: Optional[str] = None,
+    ):
+        """Replaces all repository statements with the given RDF data.
+
+        Args:
+            statements (Iterable[RDFStatement]): RDF statements to load.
+            contexts (Optional[list[Context]]): One or more specific contexts to restrict deletion to.
+
+        Raises:
+            RepositoryNotFoundException: If the repository doesn't exist.
+            httpx.HTTPStatusError: If the operation fails.
+        """
+        path = f"/repositories/{self._repository_id}/statements"
+        headers = {"Content-Type": Rdf4jContentType.NQUADS.value}
+
+        params = {}
+        if contexts:
+            params["context"] = [ctx.n3() for ctx in contexts]
+        if base_uri:
+            params["baseUri"] = base_uri
+
+        response = await self._client.put(
+            path,
+            content=serialize_statements(statements),
+            headers=headers,
+            params=params,
+        )
+        self._handle_repo_not_found_exception(response)
+        if response.status_code != httpx.codes.NO_CONTENT:
+            raise RepositoryUpdateException(
+                f"Failed to replace statements: {response.text}"
+            )
+
+    async def get_named_graph(self, graph: str) -> AsyncNamedGraph:
+        """Retrieves a named graph in the repository.
+
+        Returns:
+            AsyncNamedGraph: A named graph object.
+        """
+        return AsyncNamedGraph(self._client, self._repository_id, graph)
+
+    def _handle_repo_not_found_exception(self, response: httpx.Response):
+        """Raises a RepositoryNotFoundException if response is 404.
+
+        Args:
+            response (httpx.Response): HTTP response object.
+
+        Raises:
+            RepositoryNotFoundException: If repository is not found.
+        """
+        if response.status_code == httpx.codes.NOT_FOUND:
+            raise RepositoryNotFoundException(
+                f"Repository {self._repository_id} not found"
+            )
+
+    @property
+    def repository_id(self) -> str:
+        return self._repository_id

rdf4j_python/exception/__init__.py

@@ -0,0 +1,5 @@
+"""
+RDF4J Python Exception Module
+"""
+
+from .repo_exception import *  # noqa: F403

rdf4j_python/exception/repo_exception.py

@@ -1,4 +1,34 @@
-class RepositoryCreationException(Exception): ...
+class RepositoryCreationException(Exception):
+    """
+    Exception raised when a repository creation fails.
+    """
 
 
-class RepositoryDeletionException(Exception): ...
+class RepositoryDeletionException(Exception):
+    """
+    Exception raised when a repository deletion fails.
+    """
+
+
+class NamespaceException(Exception):
+    """
+    Exception raised when a namespace operation fails.
+    """
+
+
+class RepositoryNotFoundException(Exception):
+    """
+    Exception raised when a repository is not found.
+    """
+
+
+class RepositoryInternalException(Exception):
+    """
+    Exception raised when a repository internal error occurs.
+    """
+
+
+class RepositoryUpdateException(Exception):
+    """
+    Exception raised when a repository update fails.
+    """

rdf4j_python/model/__init__.py

@@ -0,0 +1,13 @@
+"""
+RDF4J Python Model Module
+"""
+
+from ._dataset import RDF4JDataSet
+from ._namespace import Namespace
+from ._repository_info import RepositoryMetadata
+
+__all__ = [
+    "Namespace",
+    "RepositoryMetadata",
+    "RDF4JDataSet",
+]

rdf4j_python/model/_base_model.py

@@ -5,13 +5,25 @@ from rdflib.term import Identifier, Literal, URIRef, Variable
 
 
 class _BaseModel(ABC):
+    """Abstract base class providing utility methods for parsing RDF query results."""
+
     @staticmethod
     def get_literal(
         result: Mapping[Variable, Identifier],
         var_name: str,
         default: Optional[str] = None,
-    ):
-        """Extract and convert an RDFLib Literal to a Python value."""
+    ) -> Optional[str]:
+        """
+        Extracts a literal value from a SPARQL query result.
+
+        Args:
+            result (Mapping[Variable, Identifier]): A mapping of variable bindings from a query result.
+            var_name (str): The variable name to extract.
+            default (Optional[str], optional): The value to return if the variable is not found or is not a Literal. Defaults to None.
+
+        Returns:
+            Optional[str]: The Python representation of the literal, or the default value.
+        """
         val = result.get(Variable(var_name))
         return val.toPython() if isinstance(val, Literal) else default
 
@@ -20,7 +32,17 @@ class _BaseModel(ABC):
         result: Mapping[Variable, Identifier],
         var_name: str,
         default: Optional[str] = None,
-    ):
-        """Extract and convert an RDFLib URIRef to a string."""
+    ) -> Optional[str]:
+        """
+        Extracts a URI value from a SPARQL query result.
+
+        Args:
+            result (Mapping[Variable, Identifier]): A mapping of variable bindings from a query result.
+            var_name (str): The variable name to extract.
+            default (Optional[str], optional): The value to return if the variable is not found or is not a URIRef. Defaults to None.
+
+        Returns:
+            Optional[str]: The URI string, or the default value.
+        """
         val = result.get(Variable(var_name))
         return str(val) if isinstance(val, URIRef) else default

rdf4j_python/model/_dataset.py

@@ -0,0 +1,38 @@
+from rdflib import Dataset as _Dataset
+
+from rdf4j_python.model.term import IRI
+
+
+class RDF4JDataSet(_Dataset):
+    """
+    An RDFLib Dataset subclass with RDF4J-specific utility methods.
+    """
+
+    def as_list(self) -> list[tuple]:
+        """
+        Converts all quads in the dataset to a list of 4-tuples.
+
+        Replaces the RDF4J default context IRI ("urn:x-rdflib:default") with None.
+
+        Returns:
+            list[tuple]: A list of (subject, predicate, object, context) quads.
+        """
+        return [
+            (s, p, o, ctx if ctx != IRI("urn:x-rdflib:default") else None)
+            for s, p, o, ctx in self.quads((None, None, None, None))
+        ]
+
+    @staticmethod
+    def from_raw_text(text: str) -> "RDF4JDataSet":
+        """
+        Parses a string of N-Quads RDF data into an RDF4JDataSet.
+
+        Args:
+            text (str): The RDF data in N-Quads format.
+
+        Returns:
+            RDF4JDataSet: A populated dataset.
+        """
+        ds = RDF4JDataSet()
+        ds.parse(data=text, format="nquads")
+        return ds

rdf4j_python/model/_namespace.py

@@ -0,0 +1,134 @@
+from typing import Mapping
+
+from rdflib.namespace import Namespace as RdflibNamespace
+from rdflib.term import Identifier, Variable
+
+from rdf4j_python.model.term import IRI
+
+from ._base_model import _BaseModel
+
+
+class Namespace:
+    """
+    Represents a namespace in RDF4J.
+    """
+
+    _prefix: str
+    _namespace: RdflibNamespace
+
+    def __init__(self, prefix: str, namespace: str):
+        """
+        Initializes a new Namespace.
+
+        Args:
+            prefix (str): The prefix of the namespace.
+            namespace (str): The namespace URI.
+        """
+        self._prefix = prefix
+        self._namespace = RdflibNamespace(namespace)
+
+    @classmethod
+    def from_rdflib_binding(cls, binding: Mapping[Variable, Identifier]) -> "Namespace":
+        """
+        Creates a Namespace from a RDFlib binding.
+
+        Args:
+            binding (Mapping[Variable, Identifier]): The RDFlib binding.
+
+        Returns:
+            Namespace: The created Namespace.
+        """
+        prefix = _BaseModel.get_literal(binding, "prefix", "")
+        namespace = _BaseModel.get_literal(binding, "namespace", "")
+        return cls(
+            prefix=prefix,
+            namespace=namespace,
+        )
+
+    def __str__(self):
+        """
+        Returns a string representation of the Namespace.
+
+        Returns:
+            str: A string representation of the Namespace.
+        """
+        return f"{self._prefix}: {self._namespace}"
+
+    def __repr__(self):
+        """
+        Returns a string representation of the Namespace.
+
+        Returns:
+            str: A string representation of the Namespace.
+        """
+        return f"Namespace(prefix={self._prefix}, namespace={self._namespace})"
+
+    def __contains__(self, item: str) -> bool:
+        """
+        Checks if the Namespace contains a given item.
+
+        Args:
+            item (str): The item to check.
+
+        Returns:
+            bool: True if the Namespace contains the item, False otherwise.
+        """
+        return item in self._namespace
+
+    def term(self, name: str) -> IRI:
+        """
+        Returns the IRI for a given term.
+
+        Args:
+            name (str): The term name.
+
+        Returns:
+            IRI: The IRI for the term.
+        """
+        return IRI(self._namespace.term(name))
+
+    def __getitem__(self, item: str) -> IRI:
+        """
+        Returns the IRI for a given term.
+
+        Args:
+            item (str): The term name.
+
+        Returns:
+            IRI: The IRI for the term.
+        """
+        return self.term(item)
+
+    def __getattr__(self, item: str) -> IRI:
+        """
+        Returns the IRI for a given term.
+
+        Args:
+            item (str): The term name.
+
+        Returns:
+            IRI: The IRI for the term.
+        """
+        if item.startswith("__"):
+            raise AttributeError
+        return self.term(item)
+
+    @property
+    def namespace(self) -> IRI:
+        """
+        Returns the namespace URI.
+
+        Returns:
+            IRI: The namespace URI.
+        """
+        return IRI(self._namespace)
+
+    @property
+    def prefix(self) -> str:
+        """
+        Returns the prefix of the namespace.
+
+        Returns:
+            str: The prefix of the namespace.
+        """
+        return self._prefix