rdf4j-python 0.1.0__tar.gz → 0.1.2__tar.gz

rdf4j_python-0.1.2/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Chengxu Bian
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

rdf4j_python-0.1.2/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: rdf4j-python
+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
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: rdflib>=7.1.4
+Dynamic: license-file
+
+# 🐍 rdf4j-python
+
+**A Pythonic interface to the powerful Java-based [Eclipse RDF4J](https://rdf4j.org/) framework.**
+
+> ⚠️ **Note:** This project is currently under active development and considered **experimental**. Interfaces may change. Use with caution in production environments—and feel free to help shape its future!
+
+✅ **Supports both asynchronous (`async/await`) and synchronous programming styles.**
+
+## 🌐 Overview
+
+`rdf4j-python` bridges the gap between Python applications and the [Eclipse RDF4J](https://rdf4j.org/) framework, enabling seamless interaction with RDF4J repositories directly from Python. This integration allows developers to leverage RDF4J's robust capabilities for managing RDF data and executing SPARQL queries without leaving the Python ecosystem.
+
+## 🚀 Features
+
+- **Seamless Integration**: Interact with RDF4J repositories using Pythonic constructs.
+- **SPARQL Support**: Execute SPARQL queries and updates effortlessly.
+- **Repository Management**: Create, access, and manage RDF4J repositories programmatically.
+- **Data Handling**: Add and retrieve RDF triples with ease.
+- **Format Flexibility**: Support for various RDF serialization formats.
+
+## 📦 Installation
+
+Install via pip:
+
+```bash
+pip install rdf4j-python
+```
+
+## 🧪 Usage (Async)
+
+Here's a basic example of how to use `rdf4j-python` to create an in-memory sail repository
+
+```python
+async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
+    repo_config = (
+        RepositoryConfig.Builder()
+        .repo_id("example-repo")
+        .title("Example Repository")
+        .sail_repository_impl(
+            MemoryStoreConfig.Builder().persist(False).build(),
+        )
+        .build()
+    )
+    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.
+
+## 🤝 Contributing
+
+We welcome contributions and feedback! If you'd like to help improve this project:
+
+- Fork the repo and submit a pull request
+- Open an issue for bugs, feature ideas, or discussions
+- ⭐ Star the repo if you find it useful!
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](https://github.com/odysa/rdf4j-python/blob/main/LICENSE) file for details.

rdf4j_python-0.1.2/README.md

@@ -0,0 +1,65 @@
+# 🐍 rdf4j-python
+
+**A Pythonic interface to the powerful Java-based [Eclipse RDF4J](https://rdf4j.org/) framework.**
+
+> ⚠️ **Note:** This project is currently under active development and considered **experimental**. Interfaces may change. Use with caution in production environments—and feel free to help shape its future!
+
+✅ **Supports both asynchronous (`async/await`) and synchronous programming styles.**
+
+## 🌐 Overview
+
+`rdf4j-python` bridges the gap between Python applications and the [Eclipse RDF4J](https://rdf4j.org/) framework, enabling seamless interaction with RDF4J repositories directly from Python. This integration allows developers to leverage RDF4J's robust capabilities for managing RDF data and executing SPARQL queries without leaving the Python ecosystem.
+
+## 🚀 Features
+
+- **Seamless Integration**: Interact with RDF4J repositories using Pythonic constructs.
+- **SPARQL Support**: Execute SPARQL queries and updates effortlessly.
+- **Repository Management**: Create, access, and manage RDF4J repositories programmatically.
+- **Data Handling**: Add and retrieve RDF triples with ease.
+- **Format Flexibility**: Support for various RDF serialization formats.
+
+## 📦 Installation
+
+Install via pip:
+
+```bash
+pip install rdf4j-python
+```
+
+## 🧪 Usage (Async)
+
+Here's a basic example of how to use `rdf4j-python` to create an in-memory sail repository
+
+```python
+async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
+    repo_config = (
+        RepositoryConfig.Builder()
+        .repo_id("example-repo")
+        .title("Example Repository")
+        .sail_repository_impl(
+            MemoryStoreConfig.Builder().persist(False).build(),
+        )
+        .build()
+    )
+    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.
+
+## 🤝 Contributing
+
+We welcome contributions and feedback! If you'd like to help improve this project:
+
+- Fork the repo and submit a pull request
+- Open an issue for bugs, feature ideas, or discussions
+- ⭐ Star the repo if you find it useful!
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](https://github.com/odysa/rdf4j-python/blob/main/LICENSE) file for details.

{rdf4j_python-0.1.0 → rdf4j_python-0.1.2}/pyproject.toml

@@ -1,6 +1,7 @@
 [project]
 name = "rdf4j-python"
-version = "0.1.0"
+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.2/rdf4j_python/_driver/__init__.py

@@ -0,0 +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.2/rdf4j_python/_driver/_async_rdf4j_db.py

@@ -0,0 +1,129 @@
+import httpx
+import rdflib
+
+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]:
+        """Lists all available RDF4J repositories.
+
+        Returns:
+            list[RepositoryMetadata]: A list of repository metadata objects.
+
+        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
+        )
+        return [
+            RepositoryMetadata.from_rdflib_binding(binding)
+            for binding in result.bindings
+        ]
+
+    async def get_repository(self, repository_id: str) -> AsyncRdf4JRepository:
+        """Gets an interface to a specific RDF4J repository.
+
+        Args:
+            repository_id (str): The ID of the repository.
+
+        Returns:
+            AsyncRdf4JRepository: An async interface for the repository.
+        """
+        return AsyncRdf4JRepository(self._client, repository_id)
+
+    async def create_repository(
+        self,
+        config: RepositoryConfig,
+    ) -> AsyncRdf4JRepository:
+        """Creates a new RDF4J repository using RDF configuration.
+
+        Args:
+            repository_id (str): The repository ID to create.
+            config (RepositoryConfig): RDF configuration.
+
+        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=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, config.repo_id)
+
+    async def delete_repository(self, repository_id: str):
+        """Deletes a repository and all its data and configuration.
+
+        Args:
+            repository_id (str): The ID of the repository to delete.
+
+        Raises:
+            RepositoryDeletionException: If the deletion fails.
+        """
+        path = f"/repositories/{repository_id}"
+        response = await self._client.delete(path)
+        if response.status_code != httpx.codes.NO_CONTENT:
+            raise RepositoryDeletionException(
+                f"Failed to delete repository '{repository_id}': {response.status_code} - {response.text}"
+            )