Metadata-Version: 2.5
Name: kapps-triplestore-interface
Version: 2.1.1
Summary: SPARQL queries and atomic updates against a GraphDB triplestore, as callable Python methods.
Project-URL: Homepage, https://github.com/circularfactory/kapps_triplestore_interface
Project-URL: Changelog, https://github.com/circularfactory/kapps_triplestore_interface/blob/main/CHANGELOG.md
Project-URL: Origin project, https://github.com/JaFeKl/graph_db_interface
Author-email: Jan-Felix Klein <janfelixklein@ooglemail.com>, Nico Brandt <nico.g.brandt@gmail.com>, Sören Weindel <soeren.weindel@kit.edu>, Etienne Hoffmann <etienne.hoffmann@kit.edu>
Maintainer-email: Etienne Hoffmann <etienne.hoffmann@kit.edu>, Sören Weindel <soeren.weindel@kit.edu>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.12
Requires-Dist: pydantic<3.0.0,>=2.11.7
Requires-Dist: python-snappy<0.8.0,>=0.7.3
Requires-Dist: rdflib==7.1.3
Requires-Dist: regex<2025.0.0,>=2024.11.6
Requires-Dist: requests<3.0.0,>=2.32.3
Description-Content-Type: text/markdown

# kapps-triplestore-interface

[![PyPI version](https://img.shields.io/pypi/v/kapps-triplestore-interface)](https://pypi.org/project/kapps-triplestore-interface/)
![Python](https://img.shields.io/badge/python-%3E=3.12-blue)
![License](https://img.shields.io/badge/license-MIT-blue)

This library turns SPARQL queries and updates against a running GraphDB triplestore into
callable Python methods. Three research projects run it in production.

## Installation

```bash
pip install kapps-triplestore-interface
```

Or, from a clone of this repository:

```bash
uv sync
```

## Getting Started

The package uses a single class named `GraphDB`. To use the interface, create an object from
this class:

```python
from kapps_triplestore_interface import GraphDB, GraphDBCredentials

credentials = GraphDBCredentials(
    base_url="<your_graph_db_url>",
    username="<your_graph_db_user>",
    password="<your_graph_db_password>",
    repository="<your_selected_repository_id>",
)

my_db = GraphDB(credentials=credentials)
```

## Running Tests

The test suite expects a running GraphDB instance and uses a dedicated test repository.

Required environment variables for tests:

- `GRAPHDB_URL`
- `GRAPHDB_USERNAME`
- `GRAPHDB_PASSWORD`
- `GRAPHDB_TEST_REPOSITORY`

Example:

```bash
export GRAPHDB_URL="http://localhost:7200"
export GRAPHDB_USERNAME="admin"
export GRAPHDB_PASSWORD="root"
export GRAPHDB_TEST_REPOSITORY="test-repo"
uv run pytest tests -v
```

Note: application/runtime credentials loaded via `GraphDBCredentials.from_env()` still use
`GRAPHDB_REPOSITORY` by default.

## Contributing

Development happens in a private repository at KIT. This GitHub repository is a **publish
target**. A pull request opened here cannot be merged back. Raise an issue instead, or contact the
maintainers.

## Origin

This is a renamed fork of
[`JaFeKl/graph_db_interface`](https://github.com/JaFeKl/graph_db_interface) by Jan-Felix Klein,
last released as [`graph-db-interface` 2.0.1](https://pypi.org/project/graph-db-interface/) on
PyPI under an MIT license. It is maintained here, and changes since then are listed in
[CHANGELOG.md](CHANGELOG.md).

## Migration from graph-db-interface

1. Change your dependency from `graph-db-interface` to `kapps-triplestore-interface`.
2. Change imports from `from graph_db_interface import ...` to `from kapps_triplestore_interface import ...`.
3. If you catch it, change `GraphDBInterfaceError` to `TripleStoreInterfaceError`.

## License

The package is licensed under the [MIT license](LICENSE).

## Acknowledgements

This package is developed as part of the INF subproject of the
[CRC 1574: Circular Factory for the Perpetual Product](https://www.sfb1574.kit.edu/english/index.php).
This work is therefore supported by the Deutsche Forschungsgemeinschaft (DFG, German Research
Foundation) [grant-number: SFB-1574-471687386].
