# odysa/rdf4j-python architecture

> Architecture diagram of the GitHub repository odysa/rdf4j-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/odysa/rdf4j-python
- Repository: https://github.com/odysa/rdf4j-python

## Overview

##### Project type and purpose
- rdf4j-python is a Python SDK / client library that provides both synchronous and asynchronous Pythonic interfaces to the Java-based Eclipse RDF4J HTTP API.
- Its goal is to allow Python applications to manage RDF4J repositories, execute SPARQL queries/updates, and manipulate RDF data without leaving Python.

##### File structure
Top-level:
- .github/workflows – CI and release pipelines
- docs – Sphinx documentation setup
- examples – usage snippets
- pyproject.toml – packaging and dependencies
- rdf4j_python – main package
– _client: high-level AsyncRdf4j/Rdf4jContext classes
– _driver: low-level wrappers around HTTP endpoints for repositories, graphs, etc.
– model: data models (Namespace, RepositoryConfig, Term, Vocabulary)
– exception: custom exceptions for repository errors
– utils: constants and helper functions
- tests – pytest suite (unit tests, docker-compose for integration)

##### README for insights
- Supports async/await and sync usage
- Core features: repository management, SPARQL execution, triple add/get
- Dependencies: HTTP transport to RDF4J server; Python 3.8+

##### Detail
- Transport protocols (HTTP methods, endpoints, MIME types)
- Both async and sync paths if desired (e.g., two parallel flows)
- Notes on configuration points (pyproject.toml, environment variables, default ports)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Python Application"
        App["Python Application"]:::app
    end

    %% Library Layer
    subgraph "rdf4j-python Library"
        subgraph "Client Layer"
            Client["AsyncRdf4j / Rdf4jContext"]:::client
        end
        subgraph "Driver Layer"
            AR["AsyncRepository"]:::driver
            AD["AsyncRdf4jDb"]:::driver
            AN["AsyncNamedGraph"]:::driver
        end
        subgraph "HTTP Transport"
            HTTP["httpx/requests"]:::transport
        end
        subgraph "Model Layer"
            Namespace["Namespace"]:::model
            RepoInfo["RepositoryInfo"]:::model
            RepoConfig["RepositoryConfig"]:::model
            Term["Term (IRI/Literal)"]:::model
            Vocab["Vocabulary"]:::model
        end
        subgraph "Exception Layer"
            RepoEx["RepositoryException"]:::exception
        end
        subgraph "Utility Layer"
            Const["Constants"]:::utils
            Helpers["Helpers"]:::utils
        end
    end

    %% External Systems
    RDF4J["RDF4J Server"]:::external
    Persist["Persistent Storage"]:::external

    %% Project Files
    subgraph "Project Files"
        Examples["Usage Examples"]:::external
        DocsConf["Sphinx Conf"]:::external
        DocsApi["API Docs"]:::external
        CIci["CI Pipeline"]:::external
        CIrelease["Release Pipeline"]:::external
        Tests["Test Suite"]:::external
    end

    %% Data Flow
    App -->|"calls API"| Client
    Client -->|"calls repo API"| AR
    Client -->|"calls db API"| AD
    Client -->|"calls graph API"| AN
    AR -->|"HTTP request"| HTTP
    AD -->|"HTTP request"| HTTP
    AN -->|"HTTP request"| HTTP
    HTTP -->|"RESTful calls"| RDF4J
    RDF4J -->|"response JSON/XML"| HTTP
    HTTP -->|"deliver payload"| AR
    HTTP -->|"deliver payload"| AD
    HTTP -->|"deliver payload"| AN
    AR -->|"parse responses"| Namespace
    AR -->|"parse responses"| RepoInfo
    AR -->|"parse responses"| RepoConfig
    AR -->|"parse responses"| Term
    AR -->|"parse responses"| Vocab
    AD -->|"parse responses"| Namespace
    AD -->|"parse responses"| RepoInfo
    AD -->|"parse responses"| RepoConfig
    AD -->|"parse responses"| Term
    AD -->|"parse responses"| Vocab
    AN -->|"parse responses"| Namespace
    AN -->|"parse responses"| RepoInfo
    AN -->|"parse responses"| RepoConfig
    AN -->|"parse responses"| Term
    AN -->|"parse responses"| Vocab

    %% Error Flow
    RDF4J -->|"error"| HTTP
    HTTP -->|"error"| AR
    HTTP -->|"error"| AD
    HTTP -->|"error"| AN
    AR -->|"raise exceptions"| RepoEx
    AD -->|"raise exceptions"| RepoEx
    AN -->|"raise exceptions"| RepoEx
    RepoEx -.->|"bubbles to"| App

    %% Project Files Links
    App --> Examples
    App --> DocsConf
    App --> DocsApi
    App --> CIci
    App --> CIrelease
    App --> Tests

    %% Click Events
    click Client "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/_client/_client.py"
    click AR "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/_driver/_async_repository.py"
    click AD "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/_driver/_async_rdf4j_db.py"
    click AN "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/_driver/_async_named_graph.py"
    click Namespace "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/model/_namespace.py"
    click RepoInfo "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/model/_repository_info.py"
    click RepoConfig "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/model/repository_config.py"
    click Term "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/model/term.py"
    click Vocab "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/model/vocabulary.py"
    click RepoEx "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/exception/repo_exception.py"
    click Const "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/utils/const.py"
    click Helpers "https://github.com/odysa/rdf4j-python/blob/main/rdf4j_python/utils/helpers.py"
    click Examples "https://github.com/odysa/rdf4j-python/blob/main/examples/repo.py"
    click DocsConf "https://github.com/odysa/rdf4j-python/blob/main/docs/conf.py"
    click DocsApi "https://github.com/odysa/rdf4j-python/blob/main/docs/api.rst"
    click CIci "https://github.com/odysa/rdf4j-python/blob/main/.github/workflows/ci.yaml"
    click CIrelease "https://github.com/odysa/rdf4j-python/blob/main/.github/workflows/release.yaml"
    click Tests "https://github.com/odysa/rdf4j-python/tree/main/tests/"

    %% Styles
    classDef app fill:#add8e6,stroke:#000
    classDef client fill:#add8e6,stroke:#000
    classDef driver fill:#90ee90,stroke:#000
    classDef transport fill:#90ee90,stroke:#000
    classDef model fill:#ffffe0,stroke:#000
    classDef exception fill:#ffcccb,stroke:#000
    classDef utils fill:#d3d3d3,stroke:#000
    classDef external fill:#d3d3d3,stroke:#000
```
