rdf4j-python 0.1.1a0__tar.gz → 0.1.2__tar.gz

{rdf4j_python-0.1.1a0 → rdf4j_python-0.1.2}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: rdf4j-python
-Version: 0.1.1a0
+Version: 0.1.2
 Summary: The Python client for RDF4J
+Author-email: Chengxu Bian <cbian564@gmail.com>
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -42,24 +43,23 @@ pip install rdf4j-python
 Here's a basic example of how to use `rdf4j-python` to create an in-memory sail repository
 
 ```python
-from rdf4j_python import AsyncRdf4j
-from rdf4j_python.model import MemoryStoreConfig, RepositoryConfig
-from rdf4j_python.utils.const import Rdf4jContentType
-
 async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
     repo_config = (
-        RepositoryConfig.builder_with_sail_repository(
-            MemoryStoreConfig.Builder().persist(False).build(),
-        )
+        RepositoryConfig.Builder()
         .repo_id("example-repo")
         .title("Example Repository")
+        .sail_repository_impl(
+            MemoryStoreConfig.Builder().persist(False).build(),
+        )
         .build()
     )
-    await db.create_repository(
-        repository_id=repo_config.repo_id,
-        rdf_config_data=repo_config.to_turtle(),
-        content_type=Rdf4jContentType.TURTLE,
+    repo = await db.create_repository(config=repo_config)
+    await repo.add_statement(
+        IRI("http://example.com/subject"),
+        IRI("http://example.com/predicate"),
+        Literal("test_object"),
     )
+    await repo.get_statements(subject=IRI("http://example.com/subject"))
 ```
 
 For more detailed examples, refer to the [examples](https://github.com/odysa/rdf4j-python/tree/main/examples) directory.

{rdf4j_python-0.1.1a0 → rdf4j_python-0.1.2}/README.md

@@ -31,24 +31,23 @@ pip install rdf4j-python
 Here's a basic example of how to use `rdf4j-python` to create an in-memory sail repository
 
 ```python
-from rdf4j_python import AsyncRdf4j
-from rdf4j_python.model import MemoryStoreConfig, RepositoryConfig
-from rdf4j_python.utils.const import Rdf4jContentType
-
 async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
     repo_config = (
-        RepositoryConfig.builder_with_sail_repository(
-            MemoryStoreConfig.Builder().persist(False).build(),
-        )
+        RepositoryConfig.Builder()
         .repo_id("example-repo")
         .title("Example Repository")
+        .sail_repository_impl(
+            MemoryStoreConfig.Builder().persist(False).build(),
+        )
         .build()
     )
-    await db.create_repository(
-        repository_id=repo_config.repo_id,
-        rdf_config_data=repo_config.to_turtle(),
-        content_type=Rdf4jContentType.TURTLE,
+    repo = await db.create_repository(config=repo_config)
+    await repo.add_statement(
+        IRI("http://example.com/subject"),
+        IRI("http://example.com/predicate"),
+        Literal("test_object"),
     )
+    await repo.get_statements(subject=IRI("http://example.com/subject"))
 ```
 
 For more detailed examples, refer to the [examples](https://github.com/odysa/rdf4j-python/tree/main/examples) directory.

{rdf4j_python-0.1.1a0 → rdf4j_python-0.1.2}/pyproject.toml

@@ -1,6 +1,7 @@
 [project]
 name = "rdf4j-python"
-version = "0.1.1a"
+authors = [{ name = "Chengxu Bian", email = "cbian564@gmail.com" }]
+version = "0.1.2"
 description = "The Python client for RDF4J"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -13,6 +14,11 @@ dev = [
     "pytest-docker>=3.2.1",
     "ruff>=0.11.8",
 ]
+docs = [
+    "furo>=2024.8.6",
+    "sphinx>=8",
+]
+
 
 [tool.pytest.ini_options]
 log_cli = true

rdf4j_python-0.1.2/rdf4j_python/__init__.py

@@ -0,0 +1,14 @@
+"""
+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__ = [
+    "AsyncRdf4j",
+    "AsyncRdf4JRepository",
+    "AsyncNamedGraph",
+]

rdf4j_python-0.1.2/rdf4j_python/_client/_client.py

@@ -0,0 +1,253 @@
+from typing import Any, Dict, Optional
+
+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(
+        self,
+        path: str,
+        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(
+        self,
+        path: str,
+        data: Optional[Dict[str, Any]] = None,
+        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
+        )
+
+    def put(
+        self,
+        path: str,
+        data: Optional[Dict[str, Any]] = None,
+        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
+        )
+
+    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(
+        self,
+        path: str,
+        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
+        )
+
+    async def post(
+        self,
+        path: str,
+        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), 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,
+            params=params,
+        )
+
+    async def delete(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = 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.
+
+        Returns:
+            httpx.Response: The HTTP response.
+        """
+        return await self.client.delete(
+            self._build_url(path), params=params, headers=headers
+        )

{rdf4j_python-0.1.1a0 → rdf4j_python-0.1.2}/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-0.1.2/rdf4j_python/_driver/_async_named_graph.py

@@ -0,0 +1,75 @@
+from typing import Iterable
+
+from rdf4j_python._client import AsyncApiClient
+from rdf4j_python.model import RDF4JDataSet
+from rdf4j_python.model.term import IRI, RDFStatement
+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) -> RDF4JDataSet:
+        """Fetches all RDF statements from this named graph.
+
+        Returns:
+            str: 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 RDF4JDataSet.from_raw_text(response.text)
+
+    async def add(self, statements: Iterable[RDFStatement]):
+        """Adds RDF statements to this named graph.
+
+        Args:
+            statements (Iterable[RDFStatement]): 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-0.1.1a0 → rdf4j_python-0.1.2}/rdf4j_python/_driver/_async_rdf4j_db.py

@@ -1,43 +1,66 @@
-from typing import Union
-
 import httpx
 import rdflib
 
-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",
@@ -46,54 +69,57 @@ class AsyncRdf4j:
         result = rdflib.query.Result.parse(
             response, format=Rdf4jContentType.SPARQL_RESULTS_JSON
         )
-
         return [
             RepositoryMetadata.from_rdflib_binding(binding)
             for binding in result.bindings
         ]
 
     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)