Metadata-Version: 2.4
Name: pyomnigraph
Version: 0.3.0
Summary: pyomnigraph: Unified Python interface for multiple graph databases (SPARQL, Neo4j, Weaviate)
Project-URL: Home, https://github.com/WolfgangFahl/omnigraph
Project-URL: Documentation, https://wiki.bitplan.com/index.php/omnigraph
Project-URL: Source, https://github.com/WolfgangFahl/omnigraph
Author-email: Wolfgang Fahl <wf@WolfgangFahl.com>
Maintainer-email: Wolfgang Fahl <wf@WolfgangFahl.com>
License: Apache-2.0
License-File: LICENSE
Keywords: SPARQL,blazegraph,database,graph,jena,neo4j,qlever,rdf,virtuoso,weaviate
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: dacite>=1.8.1
Requires-Dist: dataclasses-json>=0.6.3
Requires-Dist: psutil>=7.0.0
Requires-Dist: pybasemkit>=0.1.3
Requires-Dist: pylodstorage>=0.18.7
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: qlever>=0.5.35
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tdqm
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: green; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# omnigraph
Unified Python interface for multiple graph databases

| | |
| :--- | :--- |
| **PyPi** | [![PyPI Status](https://img.shields.io/pypi/v/pyomnigraph.svg)](https://pypi.python.org/pypi/pyomnigraph/) [![License](https://img.shields.io/github/license/WolfgangFahl/pyomnigraph.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![pypi](https://img.shields.io/pypi/pyversions/pyomnigraph)](https://pypi.org/project/pyomnigraph/) [![format](https://img.shields.io/pypi/format/pyomnigraph)](https://pypi.org/project/pyomnigraph/) [![downloads](https://img.shields.io/pypi/dd/pyomnigraph)](https://pypi.org/project/pyomnigraph/) |
| **GitHub** | [![Github Actions Build](https://github.com/WolfgangFahl/pyomnigraph/actions/workflows/build.yml/badge.svg)](https://github.com/WolfgangFahl/pyomnigraph/actions/workflows/build.yml) [![Release](https://img.shields.io/github/v/release/WolfgangFahl/pyomnigraph)](https://github.com/WolfgangFahl/pyomnigraph/releases) [![Contributors](https://img.shields.io/github/contributors/WolfgangFahl/pyomnigraph)](https://github.com/WolfgangFahl/pyomnigraph/graphs/contributors) [![Last Commit](https://img.shields.io/github/last-commit/WolfgangFahl/pyomnigraph)](https://github.com/WolfgangFahl/pyomnigraph/commits/) [![GitHub issues](https://img.shields.io/github/issues/WolfgangFahl/pyomnigraph.svg)](https://github.com/WolfgangFahl/pyomnigraph/issues) [![GitHub closed issues](https://img.shields.io/github/issues-closed/WolfgangFahl/pyomnigraph.svg)](https://github.com/WolfgangFahl/pyomnigraph/issues/?q=is%3Aissue+is%3Aclosed) |
| **Code** | [![style-black](https://img.shields.io/badge/%20style-black-000000.svg)](https://github.com/psf/black) [![imports-isort](https://img.shields.io/badge/%20imports-isort-%231674b1)](https://pycqa.github.io/isort/) |
| **Docs** | [![API Docs](https://img.shields.io/badge/API-Documentation-blue)](https://WolfgangFahl.github.io/pyomnigraph/) [![formatter-docformatter](https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg)](https://github.com/PyCQA/docformatter) [![style-google](https://img.shields.io/badge/%20style-google-3666d6.svg)](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) |
| **Cite** | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21721772.svg)](https://doi.org/10.5281/zenodo.21721772) |

## Cite as

If you use pyomnigraph in your research, please cite it via its Zenodo concept DOI
(which always resolves to the latest version):

> Fahl, W.
> *pyomnigraph — Unified Python interface for multiple graph databases.*
> Zenodo. https://doi.org/10.5281/zenodo.21721772

Machine-readable metadata is available in [`CITATION.cff`](./CITATION.cff);
GitHub's "Cite this repository" button and Zenodo pick it up automatically.
For a specific release, use the version DOI shown on the corresponding
[Zenodo record](https://doi.org/10.5281/zenodo.21721772).

## Docs and Tutorials
[Wiki](https://wiki.bitplan.com/index.php/pyomnigraph)

## Motivation

The graph database landscape is fragmented, with each triple store having its own APIs, deployment methods, and operational quirks. Developers and researchers working with RDF data often need to:

- **Switch between different triple stores** for performance comparisons
- **Migrate data** from one system to another
- **Test the same queries** across multiple backends
- **Deploy applications** that work with various graph databases

This leads to:
- ❌ **Duplicated effort** writing database-specific code
- ❌ **Vendor lock-in** making migrations difficult
- ❌ **Inconsistent interfaces** slowing development
- ❌ **Manual deployment** processes for each database

**pyomnigraph solves this** by providing:
- ✅ **Unified API** - Same Python interface for all supported databases
- ✅ **Standardized deployment** - Consistent Docker-based setup
- ✅ **Easy switching** - Change backends with a single parameter
- ✅ **Comparative testing** - Run identical operations across multiple stores
- ✅ **Simplified management** - Start, stop, load data with simple commands

### Supported Triple Stores

| Database | Status | Notes |
|----------|--------|-------|
| **AllegroGraph** | 🟢 Working | Multi-model, entity-event knowledge graphs, no license file needed |
| **Blazegraph** | 🟢 Working | High performance, easy setup |
| **GraphDB** | 🟢 Working | Enterprise features and reasoning; runs on the free image, empty ruleset |
| **Apache Jena** | 🟢 Working | Robust, standards compliant |
| **MillenniumDB** | 🟢 Working | Property Graph + RDF, build-only: the store is produced by mdb import before it can serve |
| **Oxigraph** | 🟢 Working | Rust-based, embedded, fast |
| **QLever** | 🟢 Working | Extremely fast queries |
| **Virtuoso** | 🟢 Working | Mature, SPARQL and SQL over one engine, reasoning and inference, fine grained attribute based access control, SPARQL via SQL |
| **Stardog** | 🛑 Disabled | License required, knowledge graphs and reasoning |

Whether you're building a semantic web application, conducting research, or evaluating different triple stores, pyomnigraph eliminates the complexity of working with multiple graph database systems.

## Examples
```bash
omnigraph --list --include-inactive --doc-format github
```
| Active   | Name                                   | Container Name         | Wikidata                                               | Image                                                                                            |   Port |   Test Port | Dataset   | User   |
|----------|----------------------------------------|------------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------|--------|-------------|-----------|--------|
| 🟢️       | [allegrograph](http://localhost:10035) | allegrograph-omnigraph | [Q4731408](https://www.wikidata.org/wiki/Q4731408)     | [franzinc/agraph:latest](https://hub.docker.com/r/franzinc/agraph)                               |  10035 |       10535 | omnigraph | admin  |
| 🟢️       | [blazegraph](http://localhost:9898)    | blazegraph-omnigraph   | [Q20127748](https://www.wikidata.org/wiki/Q20127748)   | [lyrasis/blazegraph:2.1.5](https://hub.docker.com/r/lyrasis/blazegraph)                          |   9898 |        7898 | kb        |        |
| 🟢️       | [graphdb](http://localhost:7200)       | graphdb-omnigraph      | [Q58425577](https://www.wikidata.org/wiki/Q58425577)   | [ontotext/graphdb:11.2.0](https://hub.docker.com/r/ontotext/graphdb)                             |   7200 |        7700 | repo1     |        |
| 🟢️       | [jena](http://localhost:3030)          | jena-omnigraph         | [Q109376461](https://www.wikidata.org/wiki/Q109376461) | [stain/jena-fuseki:latest](https://hub.docker.com/r/stain/jena-fuseki)                           |   3030 |        7030 | ds        | admin  |
| 🟢️       | [millenniumdb](http://localhost:1234)  | millenniumdb-omnigraph | [Q118954995](https://www.wikidata.org/wiki/Q118954995) | [imfd/millenniumdb](https://hub.docker.com/r/imfd/millenniumdb)                                  |   1234 |        1734 | default   |        |
| 🟢️       | [oxigraph](http://localhost:7878)      | oxigraph-omnigraph     | [Q118980507](https://www.wikidata.org/wiki/Q118980507) | [oxigraph/oxigraph:latest](https://hub.docker.com/r/oxigraph/oxigraph)                           |   7878 |        7378 | default   |        |
| 🟢️       | [qlever](http://localhost:7019)        | qlever-omnigraph       | [Q111016295](https://www.wikidata.org/wiki/Q111016295) | [adfreiburg/qlever:latest](https://hub.docker.com/r/adfreiburg/qlever)                           |   7019 |        7819 | olympics  |        |
| 🟢️       | [virtuoso](http://localhost:8890)      | virtuoso-omnigraph     | [Q7935239](https://www.wikidata.org/wiki/Q7935239)     | [openlink/virtuoso-opensource-7:latest](https://hub.docker.com/r/openlink/virtuoso-opensource-7) |   8890 |        8390 | KB        | dba    |
| 🛑       | [stardog](http://localhost:5820)       | stardog-omnigraph      | [Q91147741](https://www.wikidata.org/wiki/Q91147741)   | [stardog/stardog:latest](https://hub.docker.com/r/stardog/stardog)                               |   5820 |        5320 | mydb      | admin  |

### Server Management

```bash
# Start specific servers
omnigraph -s jena --cmd start

# Restart sequence - stop remove and start
omnigraph -s jena --cmd stop rm start

# Start all configured servers
omnigraph -s all --cmd start

# Check server status
omnigraph -s blazegraph --cmd status

# Open web ui
omnigraph -s jena --cmd webui
```

### Data Operations

```bash
# Load datasets
omnigraph -s blazegraph --cmd load

# Get triple count
omnigraph -s blazegraph --cmd count

# Use test environment
omnigraph --test -s blazegraph --cmd start load
```

## Usage
### omnigraph command line
```bash
omnigraph -h
usage: omnigraph [-h] [-a] [-d] [-ds DATASETS [DATASETS ...]] [-dc DATASETS_CONFIG] [-f] [-r {turtle,rdf-xml,n3,json-ld}] [-q] [-V] [--apache APACHE]
                 [-c CONFIG] [--cmd CMD [CMD ...]] [-df DOC_FORMAT] [-l] [--test] [-s SERVERS [SERVERS ...]] [-v]

Unified Python interface for multiple graph databases

options:
  -h, --help            show this help message and exit
  -a, --about           show about info [default: False]
  -d, --debug           show debug info [default: False]
  -ds DATASETS [DATASETS ...], --datasets DATASETS [DATASETS ...]
                        datasets to work with - all is an alias for all datasets [default: ['wikidata_triplestores']]
  -dc DATASETS_CONFIG, --datasets-config DATASETS_CONFIG
                        Path to datasets configuration YAML file [default: /Users/wf/Library/Python/3.12/lib/python/site-
                        packages/omnigraph/resources/examples/datasets.yaml]
  -f, --force           force actions that would modify existing data [default: False]
  -r {turtle,rdf-xml,n3,json-ld}, --rdf_format {turtle,rdf-xml,n3,json-ld}
                        RDF format to use [default: turtle]
  -q, --quiet           avoid any output [default: False]
  -V, --version         show program's version number and exit
  --apache APACHE       create apache configuration file for the given server(s)
  -c CONFIG, --config CONFIG
                        Path to server configuration YAML file [default: /Users/wf/Library/Python/3.12/lib/python/site-
                        packages/omnigraph/resources/examples/servers.yaml]
  --cmd CMD [CMD ...]   commands to execute on servers: bash, clear, count, info, load, logs, needed, rm, start, status, stop, webui
  -df DOC_FORMAT, --doc-format DOC_FORMAT
                        The document format to use [default: plain]
  -l, --list-servers    List available servers [default: False]
  --test                use test environment [default: False]
  -s SERVERS [SERVERS ...], --servers SERVERS [SERVERS ...]
                        servers to work with - 'all' selects all configured servers [default: ['blazegraph']]
  -v, --verbose         show verbose output [default: False]
```

### rdfdump command line
```bash
rdfdump -h
usage: rdfdump [-h] [-a] [-d] [-ds DATASETS [DATASETS ...]] [-dc DATASETS_CONFIG] [-f] [-r {turtle,rdf-xml,n3,json-ld}] [-q] [-V] [--limit LIMIT] [-l]
               [--count] [--dump] [-4o] [--max-count MAX_COUNT] [--no-progress] [--output-path OUTPUT_PATH] [--tryit]

Unified Python interface for multiple graph databases

options:
  -h, --help            show this help message and exit
  -a, --about           show about info [default: False]
  -d, --debug           show debug info [default: False]
  -ds DATASETS [DATASETS ...], --datasets DATASETS [DATASETS ...]
                        datasets to work with - all is an alias for all datasets [default: ['wikidata_triplestores']]
  -dc DATASETS_CONFIG, --datasets-config DATASETS_CONFIG
                        Path to datasets configuration YAML file [default: /Users/wf/Library/Python/3.12/lib/python/site-
                        packages/omnigraph/resources/examples/datasets.yaml]
  -f, --force           force actions that would modify existing data [default: False]
  -r {turtle,rdf-xml,n3,json-ld}, --rdf_format {turtle,rdf-xml,n3,json-ld}
                        RDF format to use [default: turtle]
  -q, --quiet           avoid any output [default: False]
  -V, --version         show program's version number and exit
  --limit LIMIT         Number of triples per request [default: 10000]
  -l, --list            List available datasets [default: False]
  --count               List available datasets with triple counts[default: False]
  --dump                perform the dump [default: False]
  -4o, --for-omnigraph  store dump at default omnigraph location [default: False]
  --max-count MAX_COUNT
                        Maximum number of solutions/triples to download (uses dataset expected_solutions if not specified)
  --no-progress         Disable progress bar
  --output-path OUTPUT_PATH
                        Path for dump files
  --tryit               open the try it! URL [default: False]
```