Installation¶

pip install semantido

That's it. There is no server, no daemon, no configuration file, and nothing to connect to.

Requirements¶


Python	≥ 3.11
SQLAlchemy	≥ 2.0
Also installs	`typing-extensions ≥ 4.5`

The core install is deliberately dependency-light — SQLAlchemy and nothing else — because semantido is meant to sit in the dependency tree of applications that already have opinions about their dependencies.

SQLAlchemy 2.0 is a hard floor. semantido reads the 2.0 mapper API and does not support the 1.x declarative style.

Extras¶

`osi` — OSI YAML export¶

The core install covers the JSON and Markdown exporters, plus to_osi_dict(). Serialising to OSI YAML needs PyYAML:

pip install 'semantido[osi]'

If you call to_osi_yaml() without it, you get a clear ImportError telling you to install the extra — not a stack trace.

Note the split: to_osi_dict() works without the extra, because producing the OSI document structure needs no YAML. Only serialisation does. If you are handing the dict to something else — a JSON API, your own writer — you don't need PyYAML at all.

`dev` — contributing¶

pip install 'semantido[dev]'

Pins the toolchain used in CI: pytest, pytest-cov, mypy, pylint, ruff, PyYAML, python-dotenv. Pinned exactly, so a green run locally means a green run in CI. See CONTRIBUTING.md.

Verifying¶

import semantido
print(semantido.__version__)

A fuller smoke test — no database required:

from sqlalchemy import Column, Integer
from semantido import semantic_table, SemanticDeclarativeBase
from semantido.exporters import to_markdown

@semantic_table(description="Smoke test.")
class Thing(SemanticDeclarativeBase):
    __tablename__ = "things"
    id = Column(Integer, primary_key=True)

print(to_markdown(SemanticDeclarativeBase.sync_semantic_layer()))

If that prints a Markdown document, you are done.

Stability¶

semantido is classified alpha. In practice:

The authoring surface — @semantic_table and the <column>_* conventions — is what production code depends on and is not expected to break without a deprecation path.
The exporter output is less settled. The OSI exporter tracks a spec that is itself pre-1.0 (0.2.0.dev0); its output will move as the spec does.

If you snapshot-test exports (and you should — see Versioning and CI), pin the semantido version.

Next¶

Quickstart — annotate and export in five minutes