rdf4j-python 0.1.3__tar.gz → 0.1.5__tar.gz

rdf4j_python-0.1.5/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: rdf4j-python
+Version: 0.1.5
+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: pyoxigraph>=0.4.10
+Provides-Extra: sparqlwrapper
+Requires-Dist: sparqlwrapper>=2.0.0; extra == "sparqlwrapper"
+Dynamic: license-file
+
+# rdf4j-python
+
+**A modern Python client for the Eclipse RDF4J framework, enabling seamless RDF data management and SPARQL operations from Python applications.**
+
+rdf4j-python bridges the gap between Python and the robust [Eclipse RDF4J](https://rdf4j.org/) ecosystem, providing a clean, async-first API for managing RDF repositories, executing SPARQL queries, and handling semantic data with ease.
+
+> ⚠️ **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!
+
+## Features
+
+- **🚀 Async-First Design**: Native support for async/await with synchronous fallback
+- **🔄 Repository Management**: Create, access, and manage RDF4J repositories programmatically
+- **⚡ SPARQL Support**: Execute SELECT, ASK, CONSTRUCT, and UPDATE queries effortlessly
+- **📊 Flexible Data Handling**: Add, retrieve, and manipulate RDF triples and quads
+- **🎯 Multiple Formats**: Support for various RDF serialization formats (Turtle, N-Triples, JSON-LD, etc.)
+- **🛠️ Repository Types**: Memory stores, native stores, HTTP repositories, and more
+- **🔗 Named Graph Support**: Work with multiple graphs within repositories
+- **⚙️ Inferencing**: Built-in support for RDFS and custom inferencing rules
+
+## Installation
+
+### Prerequisites
+
+- Python 3.10 or higher
+- RDF4J Server (for remote repositories) or embedded usage
+
+### Install from PyPI
+
+```bash
+pip install rdf4j-python
+```
+
+### Install with Optional Dependencies
+
+```bash
+# Include SPARQLWrapper integration
+pip install rdf4j-python[sparqlwrapper]
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/odysa/rdf4j-python.git
+cd rdf4j-python
+uv sync --group dev
+```
+
+## Usage
+
+### Quick Start
+
+```python
+import asyncio
+from rdf4j_python import AsyncRdf4j
+from rdf4j_python.model.repository_config import RepositoryConfig, MemoryStoreConfig, SailRepositoryConfig
+from rdf4j_python.model.term import IRI, Literal
+
+async def main():
+    # Connect to RDF4J server
+    async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
+        # Create an in-memory repository
+        config = RepositoryConfig(
+            repo_id="my-repo",
+            title="My Repository",
+            impl=SailRepositoryConfig(sail_impl=MemoryStoreConfig(persist=False))
+        )
+        repo = await db.create_repository(config=config)
+        
+        # Add some data
+        await repo.add_statement(
+            IRI("http://example.com/person/alice"),
+            IRI("http://xmlns.com/foaf/0.1/name"),
+            Literal("Alice")
+        )
+        
+        # Query the data
+        results = await repo.query("SELECT * WHERE { ?s ?p ?o }")
+        for result in results:
+            print(f"Subject: {result['s']}, Predicate: {result['p']}, Object: {result['o']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Working with Multiple Graphs
+
+```python
+from rdf4j_python.model.term import Quad
+
+async def multi_graph_example():
+    async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
+        repo = await db.get_repository("my-repo")
+        
+        # Add data to specific graphs
+        statements = [
+            Quad(
+                IRI("http://example.com/person/bob"),
+                IRI("http://xmlns.com/foaf/0.1/name"),
+                Literal("Bob"),
+                IRI("http://example.com/graph/people")
+            ),
+            Quad(
+                IRI("http://example.com/person/bob"),
+                IRI("http://xmlns.com/foaf/0.1/age"),
+                Literal("30", datatype=IRI("http://www.w3.org/2001/XMLSchema#integer")),
+                IRI("http://example.com/graph/demographics")
+            )
+        ]
+        await repo.add_statements(statements)
+        
+        # Query specific graph
+        graph_query = """
+        SELECT * WHERE {
+            GRAPH <http://example.com/graph/people> {
+                ?person ?property ?value
+            }
+        }
+        """
+        results = await repo.query(graph_query)
+```
+
+### Advanced Repository Configuration
+
+Here's a more comprehensive example showing repository creation with different configurations:
+
+```python
+async def advanced_example():
+    async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
+        # Memory store with persistence
+        persistent_config = RepositoryConfig(
+            repo_id="persistent-repo",
+            title="Persistent Memory Store",
+            impl=SailRepositoryConfig(sail_impl=MemoryStoreConfig(persist=True))
+        )
+        
+        # Create and populate repository
+        repo = await db.create_repository(config=persistent_config)
+        
+        # Bulk data operations
+        data = [
+            (IRI("http://example.com/alice"), IRI("http://xmlns.com/foaf/0.1/name"), Literal("Alice")),
+            (IRI("http://example.com/alice"), IRI("http://xmlns.com/foaf/0.1/email"), Literal("alice@example.com")),
+            (IRI("http://example.com/bob"), IRI("http://xmlns.com/foaf/0.1/name"), Literal("Bob")),
+        ]
+        
+        statements = [
+            Quad(subj, pred, obj, IRI("http://example.com/default"))
+            for subj, pred, obj in data
+        ]
+        await repo.add_statements(statements)
+        
+        # Complex SPARQL query
+        query = """
+        PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+        SELECT ?name ?email WHERE {
+            ?person foaf:name ?name .
+            OPTIONAL { ?person foaf:email ?email }
+        }
+        ORDER BY ?name
+        """
+        results = await repo.query(query)
+```
+
+For more detailed examples, see the [examples](examples/) directory.
+
+## Development
+
+### Setting up Development Environment
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/odysa/rdf4j-python.git
+   cd rdf4j-python
+   ```
+
+2. **Install development dependencies**:
+   ```bash
+   uv sync --group dev
+   ```
+
+3. **Start RDF4J Server** (for integration tests):
+   ```bash
+   # Using Docker
+   docker run -p 19780:8080 eclipse/rdf4j:latest
+   ```
+
+4. **Run tests**:
+   ```bash
+   pytest tests/
+   ```
+
+5. **Run linting**:
+   ```bash
+   ruff check .
+   ruff format .
+   ```
+
+### Project Structure
+
+```
+rdf4j_python/
+├── _driver/          # Core async driver implementation
+├── model/            # Data models and configurations
+├── exception/        # Custom exceptions
+└── utils/           # Utility functions
+
+examples/            # Usage examples
+tests/              # Test suite
+docs/               # Documentation
+```
+
+### Contributing
+
+We welcome contributions! Here's how to get involved:
+
+1. **Fork** the repository on GitHub
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Make** your changes and add tests
+4. **Run** the test suite to ensure everything works
+5. **Commit** your changes (`git commit -m 'Add amazing feature'`)
+6. **Push** to your branch (`git push origin feature/amazing-feature`)
+7. **Open** a Pull Request
+
+### Running Examples
+
+```bash
+# Make sure RDF4J server is running on localhost:19780
+python examples/complete_workflow.py
+python examples/query.py
+```
+
+## License
+
+This project is licensed under the **BSD 3-Clause License**. See the [LICENSE](LICENSE) file for the full license text.
+
+```
+Copyright (c) 2025, Chengxu Bian
+All rights reserved.
+```
+
+---
+
+**Questions or Issues?** Please feel free to [open an issue](https://github.com/odysa/rdf4j-python/issues) on GitHub.
+
+**⭐ Star this repo** if you find it useful!

rdf4j_python-0.1.5/README.md

@@ -0,0 +1,245 @@
+# rdf4j-python
+
+**A modern Python client for the Eclipse RDF4J framework, enabling seamless RDF data management and SPARQL operations from Python applications.**
+
+rdf4j-python bridges the gap between Python and the robust [Eclipse RDF4J](https://rdf4j.org/) ecosystem, providing a clean, async-first API for managing RDF repositories, executing SPARQL queries, and handling semantic data with ease.
+
+> ⚠️ **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!
+
+## Features
+
+- **🚀 Async-First Design**: Native support for async/await with synchronous fallback
+- **🔄 Repository Management**: Create, access, and manage RDF4J repositories programmatically
+- **⚡ SPARQL Support**: Execute SELECT, ASK, CONSTRUCT, and UPDATE queries effortlessly
+- **📊 Flexible Data Handling**: Add, retrieve, and manipulate RDF triples and quads
+- **🎯 Multiple Formats**: Support for various RDF serialization formats (Turtle, N-Triples, JSON-LD, etc.)
+- **🛠️ Repository Types**: Memory stores, native stores, HTTP repositories, and more
+- **🔗 Named Graph Support**: Work with multiple graphs within repositories
+- **⚙️ Inferencing**: Built-in support for RDFS and custom inferencing rules
+
+## Installation
+
+### Prerequisites
+
+- Python 3.10 or higher
+- RDF4J Server (for remote repositories) or embedded usage
+
+### Install from PyPI
+
+```bash
+pip install rdf4j-python
+```
+
+### Install with Optional Dependencies
+
+```bash
+# Include SPARQLWrapper integration
+pip install rdf4j-python[sparqlwrapper]
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/odysa/rdf4j-python.git
+cd rdf4j-python
+uv sync --group dev
+```
+
+## Usage
+
+### Quick Start
+
+```python
+import asyncio
+from rdf4j_python import AsyncRdf4j
+from rdf4j_python.model.repository_config import RepositoryConfig, MemoryStoreConfig, SailRepositoryConfig
+from rdf4j_python.model.term import IRI, Literal
+
+async def main():
+    # Connect to RDF4J server
+    async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
+        # Create an in-memory repository
+        config = RepositoryConfig(
+            repo_id="my-repo",
+            title="My Repository",
+            impl=SailRepositoryConfig(sail_impl=MemoryStoreConfig(persist=False))
+        )
+        repo = await db.create_repository(config=config)
+        
+        # Add some data
+        await repo.add_statement(
+            IRI("http://example.com/person/alice"),
+            IRI("http://xmlns.com/foaf/0.1/name"),
+            Literal("Alice")
+        )
+        
+        # Query the data
+        results = await repo.query("SELECT * WHERE { ?s ?p ?o }")
+        for result in results:
+            print(f"Subject: {result['s']}, Predicate: {result['p']}, Object: {result['o']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Working with Multiple Graphs
+
+```python
+from rdf4j_python.model.term import Quad
+
+async def multi_graph_example():
+    async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
+        repo = await db.get_repository("my-repo")
+        
+        # Add data to specific graphs
+        statements = [
+            Quad(
+                IRI("http://example.com/person/bob"),
+                IRI("http://xmlns.com/foaf/0.1/name"),
+                Literal("Bob"),
+                IRI("http://example.com/graph/people")
+            ),
+            Quad(
+                IRI("http://example.com/person/bob"),
+                IRI("http://xmlns.com/foaf/0.1/age"),
+                Literal("30", datatype=IRI("http://www.w3.org/2001/XMLSchema#integer")),
+                IRI("http://example.com/graph/demographics")
+            )
+        ]
+        await repo.add_statements(statements)
+        
+        # Query specific graph
+        graph_query = """
+        SELECT * WHERE {
+            GRAPH <http://example.com/graph/people> {
+                ?person ?property ?value
+            }
+        }
+        """
+        results = await repo.query(graph_query)
+```
+
+### Advanced Repository Configuration
+
+Here's a more comprehensive example showing repository creation with different configurations:
+
+```python
+async def advanced_example():
+    async with AsyncRdf4j("http://localhost:19780/rdf4j-server") as db:
+        # Memory store with persistence
+        persistent_config = RepositoryConfig(
+            repo_id="persistent-repo",
+            title="Persistent Memory Store",
+            impl=SailRepositoryConfig(sail_impl=MemoryStoreConfig(persist=True))
+        )
+        
+        # Create and populate repository
+        repo = await db.create_repository(config=persistent_config)
+        
+        # Bulk data operations
+        data = [
+            (IRI("http://example.com/alice"), IRI("http://xmlns.com/foaf/0.1/name"), Literal("Alice")),
+            (IRI("http://example.com/alice"), IRI("http://xmlns.com/foaf/0.1/email"), Literal("alice@example.com")),
+            (IRI("http://example.com/bob"), IRI("http://xmlns.com/foaf/0.1/name"), Literal("Bob")),
+        ]
+        
+        statements = [
+            Quad(subj, pred, obj, IRI("http://example.com/default"))
+            for subj, pred, obj in data
+        ]
+        await repo.add_statements(statements)
+        
+        # Complex SPARQL query
+        query = """
+        PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+        SELECT ?name ?email WHERE {
+            ?person foaf:name ?name .
+            OPTIONAL { ?person foaf:email ?email }
+        }
+        ORDER BY ?name
+        """
+        results = await repo.query(query)
+```
+
+For more detailed examples, see the [examples](examples/) directory.
+
+## Development
+
+### Setting up Development Environment
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/odysa/rdf4j-python.git
+   cd rdf4j-python
+   ```
+
+2. **Install development dependencies**:
+   ```bash
+   uv sync --group dev
+   ```
+
+3. **Start RDF4J Server** (for integration tests):
+   ```bash
+   # Using Docker
+   docker run -p 19780:8080 eclipse/rdf4j:latest
+   ```
+
+4. **Run tests**:
+   ```bash
+   pytest tests/
+   ```
+
+5. **Run linting**:
+   ```bash
+   ruff check .
+   ruff format .
+   ```
+
+### Project Structure
+
+```
+rdf4j_python/
+├── _driver/          # Core async driver implementation
+├── model/            # Data models and configurations
+├── exception/        # Custom exceptions
+└── utils/           # Utility functions
+
+examples/            # Usage examples
+tests/              # Test suite
+docs/               # Documentation
+```
+
+### Contributing
+
+We welcome contributions! Here's how to get involved:
+
+1. **Fork** the repository on GitHub
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Make** your changes and add tests
+4. **Run** the test suite to ensure everything works
+5. **Commit** your changes (`git commit -m 'Add amazing feature'`)
+6. **Push** to your branch (`git push origin feature/amazing-feature`)
+7. **Open** a Pull Request
+
+### Running Examples
+
+```bash
+# Make sure RDF4J server is running on localhost:19780
+python examples/complete_workflow.py
+python examples/query.py
+```
+
+## License
+
+This project is licensed under the **BSD 3-Clause License**. See the [LICENSE](LICENSE) file for the full license text.
+
+```
+Copyright (c) 2025, Chengxu Bian
+All rights reserved.
+```
+
+---
+
+**Questions or Issues?** Please feel free to [open an issue](https://github.com/odysa/rdf4j-python/issues) on GitHub.
+
+**⭐ Star this repo** if you find it useful!

{rdf4j_python-0.1.3 → rdf4j_python-0.1.5}/pyproject.toml

@@ -1,18 +1,22 @@
 [project]
 name = "rdf4j-python"
 authors = [{ name = "Chengxu Bian", email = "cbian564@gmail.com" }]
-version = "0.1.3"
+version = "0.1.5"
 description = "The Python client for RDF4J"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = ["httpx>=0.28.1", "pyoxigraph>=0.4.10"]
 
+[project.optional-dependencies]
+sparqlwrapper = ["sparqlwrapper>=2.0.0"]
+
 [dependency-groups]
 dev = [
     "pytest>=8.3.5",
     "pytest-asyncio>=0.26.0",
     "pytest-docker>=3.2.1",
     "ruff>=0.11.8",
+    "ty>=0.0.1a7",
 ]
 docs = ["furo>=2024.8.6", "sphinx>=8"]
 

{rdf4j_python-0.1.3 → rdf4j_python-0.1.5}/rdf4j_python/_client/_client.py

@@ -42,6 +42,17 @@ class BaseClient:
 class SyncApiClient(BaseClient):
     """Synchronous API client using httpx.Client."""
 
+    def __init__(self, base_url: str, timeout: int = 10):
+        """
+        Initializes the SyncApiClient.
+
+        Args:
+            base_url (str): The base URL for the API endpoints.
+            timeout (int, optional): Request timeout in seconds. Defaults to 10.
+        """
+        super().__init__(base_url, timeout)
+        self.client = httpx.Client(timeout=self.timeout)
+
     def __enter__(self):
         """
         Enters the context and initializes the HTTP client.
@@ -49,7 +60,7 @@ class SyncApiClient(BaseClient):
         Returns:
             SyncApiClient: The instance of the client.
         """
-        self.client = httpx.Client(timeout=self.timeout).__enter__()
+        self.client.__enter__()
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):
@@ -142,6 +153,17 @@ class SyncApiClient(BaseClient):
 class AsyncApiClient(BaseClient):
     """Asynchronous API client using httpx.AsyncClient."""
 
+    def __init__(self, base_url: str, timeout: int = 10):
+        """
+        Initializes the AsyncApiClient.
+
+        Args:
+            base_url (str): The base URL for the API endpoints.
+            timeout (int, optional): Request timeout in seconds. Defaults to 10.
+        """
+        super().__init__(base_url, timeout)
+        self.client = httpx.AsyncClient(timeout=self.timeout)
+
     async def __aenter__(self):
         """
         Enters the async context and initializes the HTTP client.
@@ -149,7 +171,7 @@ class AsyncApiClient(BaseClient):
         Returns:
             AsyncApiClient: The instance of the client.
         """
-        self.client = await httpx.AsyncClient(timeout=self.timeout).__aenter__()
+        await self.client.__aenter__()
         return self
 
     async def __aexit__(self, exc_type, exc_value, traceback):

{rdf4j_python-0.1.3 → rdf4j_python-0.1.5}/rdf4j_python/_driver/_async_rdf4j_db.py

@@ -69,6 +69,7 @@ class AsyncRdf4j:
         query_solutions = og.parse_query_results(
             response.text, format=og.QueryResultsFormat.JSON
         )
+        assert isinstance(query_solutions, og.QuerySolutions)
         return [
             RepositoryMetadata.from_sparql_query_solution(query_solution)
             for query_solution in query_solutions

{rdf4j_python-0.1.3 → rdf4j_python-0.1.5}/rdf4j_python/_driver/_async_repository.py

@@ -25,10 +25,21 @@ from rdf4j_python.model.term import (
 from rdf4j_python.utils.const import Rdf4jContentType
 from rdf4j_python.utils.helpers import serialize_statements
 
+try:
+    from SPARQLWrapper import SPARQLWrapper
+
+    _has_sparql_wrapper = True
+except ImportError:
+    _has_sparql_wrapper = False
+
 
 class AsyncRdf4JRepository:
     """Asynchronous interface for interacting with an RDF4J repository."""
 
+    _client: AsyncApiClient
+    _repository_id: str
+    _sparql_wrapper: Optional["SPARQLWrapper"] = None
+
     def __init__(self, client: AsyncApiClient, repository_id: str):
         """Initializes the repository interface.
 
@@ -39,32 +50,47 @@ class AsyncRdf4JRepository:
         self._client = client
         self._repository_id = repository_id
 
+    async def get_sparql_wrapper(self) -> "SPARQLWrapper":
+        """Returns the SPARQLWrapper for the repository.
+
+        Returns:
+            SPARQLWrapper: The SPARQLWrapper for the repository.
+        """
+        if not _has_sparql_wrapper:
+            raise ImportError(
+                "SPARQLWrapper is not installed. Please install it with `pip install rdf4j-python[sparqlwrapper]`"
+            )
+
+        if self._sparql_wrapper is None:
+            self._sparql_wrapper = SPARQLWrapper(
+                f"{self._client.get_base_url()}/repositories/{self._repository_id}"
+            )
+        return self._sparql_wrapper
+
     async def query(
         self,
         sparql_query: str,
         infer: bool = True,
-        accept: Rdf4jContentType = Rdf4jContentType.SPARQL_RESULTS_JSON,
-    ):
+    ) -> og.QuerySolutions | og.QueryBoolean:
         """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.
+            og.QuerySolutions | og.QueryBoolean: Parsed query results.
         """
         path = f"/repositories/{self._repository_id}"
         params = {"query": sparql_query, "infer": str(infer).lower()}
-        headers = {"Accept": accept}
+        headers = {"Accept": Rdf4jContentType.SPARQL_RESULTS_JSON}
         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
+        return og.parse_query_results(response.text, format=og.QueryResultsFormat.JSON)
 
-    async def update(self, sparql_update: str):
+    async def update(
+        self, sparql_update_query: str, content_type: Rdf4jContentType
+    ) -> None:
         """Executes a SPARQL UPDATE command.
 
         Args:
@@ -74,11 +100,16 @@ class AsyncRdf4JRepository:
             RepositoryNotFoundException: If the repository doesn't exist.
             httpx.HTTPStatusError: If the update fails.
         """
+        # SPARQL UPDATE operations return HTTP 204 No Content on success.
+        # No result data is returned as per SPARQL 1.1 UPDATE specification.
         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)
+        headers = {"Content-Type": content_type}
+        response = await self._client.post(
+            path, content=sparql_update_query, headers=headers
+        )
         self._handle_repo_not_found_exception(response)
-        response.raise_for_status()
+        if response.status_code != httpx.codes.NO_CONTENT:
+            raise RepositoryUpdateException(f"Failed to update: {response.text}")
 
     async def get_namespaces(self):
         """Retrieves all namespaces in the repository.
@@ -97,6 +128,7 @@ class AsyncRdf4JRepository:
         query_solutions = og.parse_query_results(
             response.text, format=og.QueryResultsFormat.JSON
         )
+        assert isinstance(query_solutions, og.QuerySolutions)
         return [
             Namespace.from_sparql_query_solution(query_solution)
             for query_solution in query_solutions