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

rdf4j_python/_driver/_async_repository.py

@@ -1,10 +1,13 @@
-from typing import Iterable, Optional
+import re
+from pathlib import Path
+from typing import Iterable, Optional, Union
 
 import httpx
 import pyoxigraph as og
 
 from rdf4j_python._client import AsyncApiClient
 from rdf4j_python._driver._async_named_graph import AsyncNamedGraph
+from rdf4j_python._driver._async_transaction import AsyncTransaction, IsolationLevel
 from rdf4j_python.exception.repo_exception import (
     NamespaceException,
     RepositoryInternalException,
@@ -26,13 +29,91 @@ from rdf4j_python.utils.const import Rdf4jContentType
 from rdf4j_python.utils.helpers import serialize_statements
 
 try:
-    from SPARQLWrapper import SPARQLWrapper
+    from SPARQLWrapper import SPARQLWrapper  # type: ignore[import-untyped]
 
     _has_sparql_wrapper = True
 except ImportError:
     _has_sparql_wrapper = False
 
 
+# Pattern to match PREFIX declarations (handles URIs with # fragments)
+_PREFIX_PATTERN = re.compile(r"PREFIX\s+\w*:\s*<[^>]*>", re.IGNORECASE)
+# Pattern to match BASE declarations
+_BASE_PATTERN = re.compile(r"BASE\s*<[^>]*>", re.IGNORECASE)
+
+
+def _remove_sparql_comments(query: str) -> str:
+    """Removes SPARQL comments while preserving # inside URIs and strings.
+
+    Args:
+        query (str): The SPARQL query string.
+
+    Returns:
+        str: The query with comments removed.
+    """
+    result = []
+    i = 0
+    in_uri = False
+    in_string = False
+    string_char = None
+
+    while i < len(query):
+        char = query[i]
+
+        if in_string:
+            result.append(char)
+            if char == string_char and (i == 0 or query[i - 1] != "\\"):
+                in_string = False
+            i += 1
+        elif in_uri:
+            result.append(char)
+            if char == ">":
+                in_uri = False
+            i += 1
+        elif char == "<":
+            in_uri = True
+            result.append(char)
+            i += 1
+        elif char in ('"', "'"):
+            in_string = True
+            string_char = char
+            result.append(char)
+            i += 1
+        elif char == "#":
+            # Skip until end of line
+            while i < len(query) and query[i] != "\n":
+                i += 1
+        else:
+            result.append(char)
+            i += 1
+
+    return "".join(result)
+
+
+def _detect_query_type(query: str) -> str:
+    """Detects the SPARQL query type, ignoring prefixes, base, and comments.
+
+    Args:
+        query (str): The SPARQL query string.
+
+    Returns:
+        str: The query type in uppercase (SELECT, ASK, CONSTRUCT, DESCRIBE, INSERT, DELETE, etc.)
+             or empty string if unable to determine.
+    """
+    # Remove comments (preserving # inside URIs)
+    cleaned = _remove_sparql_comments(query)
+    # Remove all PREFIX declarations
+    cleaned = _PREFIX_PATTERN.sub("", cleaned)
+    # Remove all BASE declarations
+    cleaned = _BASE_PATTERN.sub("", cleaned)
+    # Get the first word
+    cleaned = cleaned.strip()
+    if not cleaned:
+        return ""
+    first_word = cleaned.split()[0].upper()
+    return first_word
+
+
 class AsyncRdf4JRepository:
     """Asynchronous interface for interacting with an RDF4J repository."""
 
@@ -71,22 +152,57 @@ class AsyncRdf4JRepository:
         self,
         sparql_query: str,
         infer: bool = True,
-    ) -> og.QuerySolutions | og.QueryBoolean:
-        """Executes a SPARQL SELECT query.
+    ) -> og.QuerySolutions | og.QueryBoolean | og.QueryTriples:
+        """Executes a SPARQL query (SELECT, ASK, CONSTRUCT, or DESCRIBE).
 
         Args:
             sparql_query (str): The SPARQL query string.
             infer (bool): Whether to include inferred statements. Defaults to True.
 
         Returns:
-            og.QuerySolutions | og.QueryBoolean: Parsed query results.
+            og.QuerySolutions | og.QueryBoolean | og.QueryTriples: Parsed query results.
+
+        Note:
+            This method correctly handles queries with PREFIX declarations,
+            BASE URIs, and comments before the query keyword.
         """
         path = f"/repositories/{self._repository_id}"
         params = {"query": sparql_query, "infer": str(infer).lower()}
-        headers = {"Accept": Rdf4jContentType.SPARQL_RESULTS_JSON}
-        response = await self._client.get(path, params=params, headers=headers)
-        self._handle_repo_not_found_exception(response)
-        return og.parse_query_results(response.text, format=og.QueryResultsFormat.JSON)
+
+        # Detect query type (handles PREFIX, BASE, comments)
+        query_type = _detect_query_type(sparql_query)
+
+        if query_type == "SELECT":
+            headers = {"Accept": Rdf4jContentType.SPARQL_RESULTS_JSON}
+            response = await self._client.get(path, params=params, headers=headers)
+            self._handle_repo_not_found_exception(response)
+            return og.parse_query_results(
+                response.text, format=og.QueryResultsFormat.JSON
+            )
+        elif query_type == "ASK":
+            headers = {"Accept": Rdf4jContentType.SPARQL_RESULTS_JSON}
+            response = await self._client.get(path, params=params, headers=headers)
+            self._handle_repo_not_found_exception(response)
+            return og.parse_query_results(
+                response.text, format=og.QueryResultsFormat.JSON
+            )
+        elif query_type in ("CONSTRUCT", "DESCRIBE"):
+            headers = {"Accept": Rdf4jContentType.NTRIPLES}
+            response = await self._client.get(path, params=params, headers=headers)
+            self._handle_repo_not_found_exception(response)
+            # Create temporary store to convert N-Triples response to QueryTriples
+            store = og.Store()
+            for quad in og.parse(response.text, format=og.RdfFormat.N_TRIPLES):
+                store.add(quad)
+            return store.query("CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }")
+        else:
+            # Default to JSON for unknown query types
+            headers = {"Accept": Rdf4jContentType.SPARQL_RESULTS_JSON}
+            response = await self._client.get(path, params=params, headers=headers)
+            self._handle_repo_not_found_exception(response)
+            return og.parse_query_results(
+                response.text, format=og.QueryResultsFormat.JSON
+            )
 
     async def update(
         self, sparql_update_query: str, content_type: Rdf4jContentType
@@ -111,7 +227,7 @@ class AsyncRdf4JRepository:
         if response.status_code != httpx.codes.NO_CONTENT:
             raise RepositoryUpdateException(f"Failed to update: {response.text}")
 
-    async def get_namespaces(self):
+    async def get_namespaces(self) -> list[Namespace]:
         """Retrieves all namespaces in the repository.
 
         Returns:
@@ -128,7 +244,10 @@ class AsyncRdf4JRepository:
         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 [
             Namespace.from_sparql_query_solution(query_solution)
             for query_solution in query_solutions
@@ -177,7 +296,7 @@ class AsyncRdf4JRepository:
 
         return Namespace(prefix, response.text)
 
-    async def delete_namespace(self, prefix: str):
+    async def delete_namespace(self, prefix: str) -> None:
         """Deletes a namespace by prefix.
 
         Args:
@@ -192,7 +311,7 @@ class AsyncRdf4JRepository:
         self._handle_repo_not_found_exception(response)
         response.raise_for_status()
 
-    async def clear_all_namespaces(self):
+    async def clear_all_namespaces(self) -> None:
         """Removes all namespaces from the repository.
 
         Raises:
@@ -268,7 +387,7 @@ class AsyncRdf4JRepository:
         predicate: Optional[Predicate] = None,
         object_: Optional[Object] = None,
         contexts: Optional[list[Context]] = None,
-    ):
+    ) -> None:
         """Deletes statements from the repository matching the given pattern.
 
         Args:
@@ -308,7 +427,7 @@ class AsyncRdf4JRepository:
         predicate: Predicate,
         object: Object,
         context: Optional[Context] = None,
-    ):
+    ) -> None:
         """Adds a single RDF statement to the repository.
 
         Args:
@@ -337,7 +456,7 @@ class AsyncRdf4JRepository:
         if response.status_code != httpx.codes.NO_CONTENT:
             raise RepositoryUpdateException(f"Failed to add statement: {response.text}")
 
-    async def add_statements(self, statements: Iterable[Quad] | Iterable[Triple]):
+    async def add_statements(self, statements: Iterable[Quad] | Iterable[Triple]) -> None:
         """Adds a list of RDF statements to the repository.
 
         Args:
@@ -364,7 +483,7 @@ class AsyncRdf4JRepository:
         statements: Iterable[Quad] | Iterable[Triple],
         contexts: Optional[Iterable[Context]] = None,
         base_uri: Optional[str] = None,
-    ):
+    ) -> None:
         """Replaces all repository statements with the given RDF data.
 
         Args:
@@ -396,6 +515,86 @@ class AsyncRdf4JRepository:
                 f"Failed to replace statements: {response.text}"
             )
 
+    async def upload_file(
+        self,
+        file_path: Union[str, Path],
+        rdf_format: Optional[og.RdfFormat] = None,
+        context: Optional[Context] = None,
+        base_uri: Optional[str] = None,
+    ) -> None:
+        """Uploads an RDF file to the repository.
+
+        This method reads an RDF file from disk and uploads its contents to the repository.
+        The file can be in various RDF formats such as Turtle, N-Triples, N-Quads, RDF/XML, JSON-LD, TriG, or N3.
+
+        Args:
+            file_path (Union[str, Path]): Path to the RDF file to upload.
+            rdf_format (Optional[og.RdfFormat]): The RDF format of the file.
+                If None, the format is automatically detected from the file extension.
+                Supported formats include:
+                - og.RdfFormat.TURTLE (.ttl)
+                - og.RdfFormat.N_TRIPLES (.nt)
+                - og.RdfFormat.N_QUADS (.nq)
+                - og.RdfFormat.RDF_XML (.rdf, .xml)
+                - og.RdfFormat.JSON_LD (.jsonld)
+                - og.RdfFormat.TRIG (.trig)
+                - og.RdfFormat.N3 (.n3)
+            context (Optional[Context]): The named graph (context) to upload statements into.
+                If None, statements are added to the default graph.
+            base_uri (Optional[str]): The base URI for resolving relative URIs in the file.
+                If None, relative URIs are resolved based on the file path.
+
+        Raises:
+            FileNotFoundError: If the specified file doesn't exist.
+            RepositoryNotFoundException: If the repository doesn't exist.
+            RepositoryUpdateException: If the upload fails.
+            ValueError: If the RDF format is not supported.
+            SyntaxError: If the file contains invalid RDF data.
+
+        Example:
+            >>> repo = await db.get_repository("my-repo")
+            >>> # Upload a Turtle file (format auto-detected)
+            >>> await repo.upload_file("data.ttl")
+            >>> # Upload to a specific named graph
+            >>> await repo.upload_file("data.ttl", context=IRI("http://example.com/graph"))
+            >>> # Upload with explicit format
+            >>> await repo.upload_file("data.txt", rdf_format=og.RdfFormat.N_TRIPLES)
+        """
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        # Parse the RDF file using pyoxigraph
+        try:
+            # If base_uri is not provided, use the file path as base
+            if base_uri is None:
+                base_uri = file_path.as_uri()
+
+            # Parse the file
+            quads = list(
+                og.parse(path=str(file_path), format=rdf_format, base_iri=base_uri)
+            )
+
+            # If a context is specified, wrap all statements in that context
+            # Note: This overrides any named graph information in the file (e.g., from N-Quads)
+            if context is not None:
+                statements = [
+                    Quad(q.subject, q.predicate, q.object, context) for q in quads
+                ]
+            else:
+                statements = quads
+
+            # Upload the statements to the repository
+            await self.add_statements(statements)
+
+        except (ValueError, SyntaxError) as e:
+            raise type(e)(f"Failed to parse RDF file '{file_path}': {e}") from e
+        except Exception as e:
+            raise RepositoryUpdateException(
+                f"Failed to upload file '{file_path}': {e}"
+            ) from e
+
     async def get_named_graph(self, graph: str) -> AsyncNamedGraph:
         """Retrieves a named graph in the repository.
 
@@ -404,7 +603,39 @@ class AsyncRdf4JRepository:
         """
         return AsyncNamedGraph(self._client, self._repository_id, graph)
 
-    def _handle_repo_not_found_exception(self, response: httpx.Response):
+    def transaction(
+        self, isolation_level: Optional[IsolationLevel] = None
+    ) -> AsyncTransaction:
+        """Creates a new transaction for this repository.
+
+        Transactions allow grouping multiple operations (add, delete, update)
+        into a single atomic unit. Either all operations succeed (commit) or
+        none of them take effect (rollback).
+
+        Args:
+            isolation_level: Optional isolation level for the transaction.
+                Supported levels depend on the RDF4J store implementation.
+                Common levels include SNAPSHOT, SERIALIZABLE, READ_COMMITTED.
+
+        Returns:
+            AsyncTransaction: A transaction context manager.
+
+        Example:
+            ```python
+            # Using as context manager (recommended)
+            async with repo.transaction() as txn:
+                await txn.add_statements([quad1, quad2])
+                await txn.delete_statements([quad3])
+                # Auto-commits on success, auto-rollbacks on exception
+
+            # With isolation level
+            async with repo.transaction(IsolationLevel.SERIALIZABLE) as txn:
+                await txn.add_statements([quad1])
+            ```
+        """
+        return AsyncTransaction(self._client, self._repository_id, isolation_level)
+
+    def _handle_repo_not_found_exception(self, response: httpx.Response) -> None:
         """Raises a RepositoryNotFoundException if response is 404.
 
         Args:

rdf4j_python/_driver/_async_transaction.py

@@ -0,0 +1,310 @@
+"""Async transaction support for RDF4J repositories."""
+
+from enum import Enum
+from types import TracebackType
+from typing import TYPE_CHECKING, Iterable, Optional, Self
+
+import httpx
+
+from rdf4j_python.exception import TransactionError, TransactionStateError
+from rdf4j_python.model.term import Quad, Triple
+from rdf4j_python.utils.const import Rdf4jContentType
+from rdf4j_python.utils.helpers import serialize_statements
+
+if TYPE_CHECKING:
+    from rdf4j_python._client import AsyncApiClient
+
+
+class TransactionState(Enum):
+    """Represents the state of a transaction."""
+
+    PENDING = "pending"  # Transaction not yet started
+    ACTIVE = "active"  # Transaction is active
+    COMMITTED = "committed"  # Transaction has been committed
+    ROLLED_BACK = "rolled_back"  # Transaction has been rolled back
+
+
+class IsolationLevel(Enum):
+    """Transaction isolation levels supported by RDF4J.
+
+    Note: Not all RDF4J store implementations support all isolation levels.
+    If an unsupported level is requested, the store's default will be used.
+    """
+
+    NONE = "NONE"
+    READ_UNCOMMITTED = "READ_UNCOMMITTED"
+    READ_COMMITTED = "READ_COMMITTED"
+    SNAPSHOT_READ = "SNAPSHOT_READ"
+    SNAPSHOT = "SNAPSHOT"
+    SERIALIZABLE = "SERIALIZABLE"
+
+
+class AsyncTransaction:
+    """Async context manager for transactional operations on an RDF4J repository.
+
+    Transactions allow grouping multiple operations (add, delete, update) into
+    a single atomic unit. Either all operations succeed (commit) or none of them
+    take effect (rollback).
+
+    Usage as context manager (recommended):
+        ```python
+        async with repo.transaction() as txn:
+            await txn.add_statements([quad1, quad2])
+            await txn.add_statements([quad3])
+            # Auto-commits on success, auto-rollbacks on exception
+        ```
+
+    Manual usage:
+        ```python
+        txn = repo.transaction()
+        await txn.begin()
+        try:
+            await txn.add_statements([quad1, quad2])
+            await txn.commit()
+        except Exception:
+            await txn.rollback()
+            raise
+        ```
+
+    Attributes:
+        state: Current state of the transaction (PENDING, ACTIVE, COMMITTED, ROLLED_BACK)
+    """
+
+    _client: "AsyncApiClient"
+    _repository_id: str
+    _transaction_id: Optional[str]
+    _isolation_level: Optional[IsolationLevel]
+    _state: TransactionState
+
+    def __init__(
+        self,
+        client: "AsyncApiClient",
+        repository_id: str,
+        isolation_level: Optional[IsolationLevel] = None,
+    ):
+        """Initialize a transaction.
+
+        Args:
+            client: The async API client.
+            repository_id: The repository ID.
+            isolation_level: Optional isolation level for the transaction.
+        """
+        self._client = client
+        self._repository_id = repository_id
+        self._transaction_id = None
+        self._isolation_level = isolation_level
+        self._state = TransactionState.PENDING
+
+    @property
+    def state(self) -> TransactionState:
+        """Returns the current state of the transaction."""
+        return self._state
+
+    @property
+    def is_active(self) -> bool:
+        """Returns True if the transaction is active."""
+        return self._state == TransactionState.ACTIVE
+
+    async def __aenter__(self) -> Self:
+        """Start the transaction when entering the context."""
+        await self.begin()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Commit or rollback the transaction when exiting the context.
+
+        If an exception occurred, the transaction is rolled back.
+        Otherwise, it is committed.
+        """
+        if self._state != TransactionState.ACTIVE:
+            # Transaction already ended (manually committed/rolled back)
+            return
+
+        if exc_type is not None:
+            # An exception occurred, rollback
+            await self.rollback()
+        else:
+            # No exception, commit
+            await self.commit()
+
+    async def begin(self) -> None:
+        """Start the transaction.
+
+        Raises:
+            TransactionStateError: If the transaction has already been started.
+            TransactionError: If the server fails to create the transaction.
+        """
+        if self._state != TransactionState.PENDING:
+            raise TransactionStateError(
+                f"Cannot begin transaction: already in state {self._state.value}"
+            )
+
+        path = f"/repositories/{self._repository_id}/transactions"
+        params = {}
+        if self._isolation_level is not None:
+            params["isolation-level"] = self._isolation_level.value
+
+        response = await self._client.post(path, headers={}, params=params)
+
+        if response.status_code != httpx.codes.CREATED:
+            raise TransactionError(
+                f"Failed to start transaction: {response.status_code} - {response.text}"
+            )
+
+        # Extract transaction ID from Location header
+        location = response.headers.get("Location")
+        if not location:
+            raise TransactionError(
+                "Server did not return transaction ID in Location header"
+            )
+
+        # Location is like: /rdf4j-server/repositories/{id}/transactions/{txn-id}
+        self._transaction_id = location.rstrip("/").split("/")[-1]
+        self._state = TransactionState.ACTIVE
+
+    async def commit(self) -> None:
+        """Commit the transaction, making all changes permanent.
+
+        Raises:
+            TransactionStateError: If the transaction is not active.
+            TransactionError: If the commit fails.
+        """
+        if self._state != TransactionState.ACTIVE:
+            raise TransactionStateError(
+                f"Cannot commit transaction: in state {self._state.value}"
+            )
+
+        path = f"/repositories/{self._repository_id}/transactions/{self._transaction_id}"
+        params = {"action": "COMMIT"}
+
+        response = await self._client.put(path, params=params)
+
+        if response.status_code not in (httpx.codes.OK, httpx.codes.NO_CONTENT):
+            raise TransactionError(
+                f"Failed to commit transaction: {response.status_code} - {response.text}"
+            )
+
+        self._state = TransactionState.COMMITTED
+
+    async def rollback(self) -> None:
+        """Rollback the transaction, discarding all changes.
+
+        Raises:
+            TransactionStateError: If the transaction is not active.
+            TransactionError: If the rollback fails.
+        """
+        if self._state != TransactionState.ACTIVE:
+            raise TransactionStateError(
+                f"Cannot rollback transaction: in state {self._state.value}"
+            )
+
+        path = f"/repositories/{self._repository_id}/transactions/{self._transaction_id}"
+
+        response = await self._client.delete(path)
+
+        if response.status_code not in (httpx.codes.OK, httpx.codes.NO_CONTENT):
+            raise TransactionError(
+                f"Failed to rollback transaction: {response.status_code} - {response.text}"
+            )
+
+        self._state = TransactionState.ROLLED_BACK
+
+    def _ensure_active(self) -> None:
+        """Ensure the transaction is active before performing operations."""
+        if self._state != TransactionState.ACTIVE:
+            raise TransactionStateError(
+                f"Cannot perform operation: transaction in state {self._state.value}"
+            )
+
+    async def add_statements(
+        self, statements: Iterable[Quad] | Iterable[Triple]
+    ) -> None:
+        """Add statements to the repository within this transaction.
+
+        Args:
+            statements: The RDF statements to add.
+
+        Raises:
+            TransactionStateError: If the transaction is not active.
+            TransactionError: If the operation fails.
+        """
+        self._ensure_active()
+
+        path = f"/repositories/{self._repository_id}/transactions/{self._transaction_id}"
+        params = {"action": "ADD"}
+        headers = {"Content-Type": Rdf4jContentType.NQUADS}
+
+        response = await self._client.put(
+            path,
+            content=serialize_statements(statements),
+            params=params,
+            headers=headers,
+        )
+
+        if response.status_code not in (httpx.codes.OK, httpx.codes.NO_CONTENT):
+            raise TransactionError(
+                f"Failed to add statements: {response.status_code} - {response.text}"
+            )
+
+    async def delete_statements(
+        self, statements: Iterable[Quad] | Iterable[Triple]
+    ) -> None:
+        """Delete specific statements from the repository within this transaction.
+
+        Args:
+            statements: The RDF statements to delete.
+
+        Raises:
+            TransactionStateError: If the transaction is not active.
+            TransactionError: If the operation fails.
+        """
+        self._ensure_active()
+
+        path = f"/repositories/{self._repository_id}/transactions/{self._transaction_id}"
+        params = {"action": "DELETE"}
+        headers = {"Content-Type": Rdf4jContentType.NQUADS}
+
+        response = await self._client.put(
+            path,
+            content=serialize_statements(statements),
+            params=params,
+            headers=headers,
+        )
+
+        if response.status_code not in (httpx.codes.OK, httpx.codes.NO_CONTENT):
+            raise TransactionError(
+                f"Failed to delete statements: {response.status_code} - {response.text}"
+            )
+
+    async def update(self, sparql_update: str) -> None:
+        """Execute a SPARQL UPDATE within this transaction.
+
+        Args:
+            sparql_update: The SPARQL UPDATE query string.
+
+        Raises:
+            TransactionStateError: If the transaction is not active.
+            TransactionError: If the operation fails.
+        """
+        self._ensure_active()
+
+        path = f"/repositories/{self._repository_id}/transactions/{self._transaction_id}"
+        params = {"action": "UPDATE"}
+        headers = {"Content-Type": Rdf4jContentType.SPARQL_UPDATE}
+
+        response = await self._client.put(
+            path,
+            content=sparql_update,
+            params=params,
+            headers=headers,
+        )
+
+        if response.status_code not in (httpx.codes.OK, httpx.codes.NO_CONTENT):
+            raise TransactionError(
+                f"Failed to execute update: {response.status_code} - {response.text}"
+            )