Metadata-Version: 2.4
Name: ontosql
Version: 0.5.0
Summary: Semantic data access for SQL — map ontology-shaped models onto real schemas with explicit OntoMapper bindings (import ontosql)
Project-URL: Homepage, https://github.com/eddiethedean/ontosql
Project-URL: Documentation, https://ontosql.readthedocs.io/
Project-URL: Repository, https://github.com/eddiethedean/ontosql
Project-URL: Issues, https://github.com/eddiethedean/ontosql/issues
Project-URL: Changelog, https://github.com/eddiethedean/ontosql/blob/main/CHANGELOG.md
Author: OntoSQL Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: fastapi,json-ld,mapper,ontology,pydantic,rdf,semantic-web,sqlmodel
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: sqlmodel>=0.0.14
Requires-Dist: triplemodel>=0.12.0
Requires-Dist: typing-extensions>=4.0
Provides-Extra: async
Requires-Dist: aiosqlite>=0.20; extra == 'async'
Requires-Dist: greenlet>=3.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20; extra == 'dev'
Requires-Dist: fastapi>=0.100; extra == 'dev'
Requires-Dist: greenlet>=3.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'dev'
Requires-Dist: orjson>=3.9; extra == 'dev'
Requires-Dist: pyld>=3.0; extra == 'dev'
Requires-Dist: pyshacl>=0.29; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: sparqlmodel>=0.13.1; extra == 'dev'
Requires-Dist: ty>=0.0.37; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Requires-Dist: orjson>=3.9; extra == 'fastapi'
Provides-Extra: jsonld
Requires-Dist: pyld>=3.0; extra == 'jsonld'
Provides-Extra: shacl
Requires-Dist: pyshacl>=0.29; extra == 'shacl'
Provides-Extra: sparql
Requires-Dist: sparqlmodel>=0.13.1; extra == 'sparql'
Description-Content-Type: text/markdown

# OntoSQL

[![PyPI version](https://img.shields.io/pypi/v/ontosql)](https://pypi.org/project/ontosql/)
[![CI](https://github.com/eddiethedean/ontosql/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/ontosql/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/ontosql)](https://pypi.org/project/ontosql/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Documentation](https://readthedocs.org/projects/ontosql/badge/?version=latest)](https://ontosql.readthedocs.io/en/latest/)

**Semantic CRUD for SQL-first Python apps** — SQLModel tables, Pydantic ontology models, explicit mappers, optional JSON-LD/RDF export.

> **0.5.x beta** — API stability tiers in [SPECS](https://ontosql.readthedocs.io/en/latest/SPECS.html); semver guarantees begin at 1.0. Pin versions in production.

> **Not** a SPARQL database or OBDA query engine. RDF and graph sync are optional extras.

Real databases rarely match ontology shapes one-to-one. OntoSQL separates **physical** SQLModel tables from **semantic** Pydantic entities and connects them with explicit **mappers**. Application code uses semantic types; OntoSQL compiles SQL on the backend.

## Install

```bash
pip install ontosql
pip install "ontosql[async,fastapi]"   # optional extras — see docs
```

**Requirements:** Python 3.10+. See [Compatibility](https://ontosql.readthedocs.io/en/latest/COMPATIBILITY.html).

## Start here

| I want to… | Go to |
|------------|-------|
| Try CRUD in 5 minutes (pip only) | [Quick start](https://ontosql.readthedocs.io/en/latest/getting-started/quickstart.html) |
| Pick a path (async, FastAPI, hybrid) | [Start here](https://ontosql.readthedocs.io/en/latest/guides/start-here.html) |
| Understand the design | [Architecture](https://ontosql.readthedocs.io/en/latest/ARCHITECTURE.html) |
| Decide if OntoSQL fits | [When to use OntoSQL](https://ontosql.readthedocs.io/en/latest/getting-started/when-to-use.html) |
| Evaluate for production | [Security](https://ontosql.readthedocs.io/en/latest/SECURITY.html) · [Compatibility](https://ontosql.readthedocs.io/en/latest/COMPATIBILITY.html) · [Enterprise adoption](https://ontosql.readthedocs.io/en/latest/enterprise-adoption.html) |

**Full docs:** [ontosql.readthedocs.io](https://ontosql.readthedocs.io/en/latest/)

## Minimal example

```python
from sqlmodel import Field, Session, SQLModel, create_engine
from ontosql import Map, OntoMapper, OntoModel, OntoSession, onto_property

class PersonRow(SQLModel, table=True):
    __tablename__ = "people"
    id: int | None = Field(default=None, primary_key=True)
    name: str

class Person(OntoModel):
    type_iri = "schema:Person"
    iri_template = "https://data.example.org/person/{id}"
    id: int
    name: str = onto_property("schema:name")

class PersonMap(OntoMapper[Person]):
    entity = Person
    id = Map(PersonRow.id)
    name = Map(PersonRow.name, property="schema:name")

engine = create_engine("sqlite://")
SQLModel.metadata.create_all(engine)
with Session(engine) as raw:
    raw.add(PersonRow(id=1, name="Ada Lovelace"))
    raw.commit()
# Demo seeds via SQLModel; production code typically uses session.save() — see quickstart.

with OntoSession(engine, maps=[PersonMap]) as session:
    print(session.get(Person, identity=1).name)
```

Copy the full Person/Organization walkthrough from the [quick start](https://ontosql.readthedocs.io/en/latest/getting-started/quickstart.html).

## Ecosystem

Optional RDF export uses [TripleModel](https://github.com/eddiethedean/triplemodel). Graph-native apps can pair OntoSQL with [SparqlModel](https://github.com/eddiethedean/sparqlmodel). See [Ecosystem](https://ontosql.readthedocs.io/en/latest/ECOSYSTEM.html).

## Examples (repository clone)

The `examples/` directory is **not** in the PyPI wheel:

```bash
git clone https://github.com/eddiethedean/ontosql.git
cd ontosql && pip install -e ".[dev]"
python examples/person_org_demo.py
```

| Script | What it teaches |
|--------|-----------------|
| [person_org_demo.py](examples/person_org_demo.py) | Sync CRUD round-trip |
| [person_org_async.py](examples/person_org_async.py) | Async session |
| [hybrid_person_org.py](examples/hybrid_person_org.py) | Graph sync, import |
| [person_org_api_production.py](examples/person_org_api_production.py) | Production FastAPI pattern |

See [examples/README.md](examples/README.md) for layout and how `_bootstrap.py` works.

## Development

```bash
pip install -e ".[dev]"
ruff check src tests && ty check && pytest --cov=ontosql --cov-fail-under=90
```

See [Contributing](https://ontosql.readthedocs.io/en/latest/contributing.html) and [Releasing](https://ontosql.readthedocs.io/en/latest/RELEASING.html).

## License

MIT — see [LICENSE](LICENSE).
