rdf4j-python 0.1.4__tar.gz → 0.1.6__tar.gz

rdf4j_python-0.1.6/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: rdf4j-python
+Version: 0.1.6
+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.6/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.4 → rdf4j_python-0.1.6}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "rdf4j-python"
 authors = [{ name = "Chengxu Bian", email = "cbian564@gmail.com" }]
-version = "0.1.4"
+version = "0.1.6"
 description = "The Python client for RDF4J"
 readme = "README.md"
 requires-python = ">=3.10"

{rdf4j_python-0.1.4 → rdf4j_python-0.1.6}/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):
@@ -251,3 +273,9 @@ class AsyncApiClient(BaseClient):
         return await self.client.delete(
             self._build_url(path), params=params, headers=headers
         )
+
+    async def aclose(self):
+        """
+        Asynchronously closes the client connection.
+        """
+        await self.client.aclose()

{rdf4j_python-0.1.4 → rdf4j_python-0.1.6}/rdf4j_python/_driver/_async_rdf4j_db.py

@@ -26,6 +26,7 @@ class AsyncRdf4j:
             base_url (str): Base URL of the RDF4J server.
         """
         self._base_url = base_url.rstrip("/")
+        self._client = AsyncApiClient(base_url=self._base_url)
 
     async def __aenter__(self):
         """Enters the async context and initializes the HTTP client.
@@ -33,7 +34,7 @@ class AsyncRdf4j:
         Returns:
             AsyncRdf4j: The initialized RDF4J interface.
         """
-        self._client = await AsyncApiClient(base_url=self._base_url).__aenter__()
+        self._client = await self._client.__aenter__()
         return self
 
     async def __aexit__(self, exc_type, exc_value, traceback):
@@ -103,7 +104,7 @@ class AsyncRdf4j:
             RepositoryCreationException: If repository creation fails.
         """
         path = f"/repositories/{config.repo_id}"
-        headers = {"Content-Type": Rdf4jContentType.TURTLE}
+        headers = {"Content-Type": Rdf4jContentType.TURTLE.value}
         response: httpx.Response = await self._client.put(
             path, content=config.to_turtle(), headers=headers
         )
@@ -128,3 +129,7 @@ class AsyncRdf4j:
             raise RepositoryDeletionException(
                 f"Failed to delete repository '{repository_id}': {response.status_code} - {response.text}"
             )
+
+    async def aclose(self):
+        """Asynchronously closes the client connection."""
+        await self._client.aclose()

{rdf4j_python-0.1.4 → rdf4j_python-0.1.6}/rdf4j_python/_driver/_async_repository.py

@@ -100,7 +100,8 @@ class AsyncRdf4JRepository:
             RepositoryNotFoundException: If the repository doesn't exist.
             httpx.HTTPStatusError: If the update fails.
         """
-        # TODO: handle update results
+        # 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": content_type}
         response = await self._client.post(