typra (Python)

Official CPython bindings for Typra (PyO3 native extension): a typed, embedded database with a Rust core.

Status

You get a durable schema catalog, validation, nested row values (record v2 on insert; v1 segments still replay), and constraints in a single .typra file, plus in-memory databases and snapshot bytes.

Queries and secondary indexes (0.7+): register optional indexes_json on register_collection, then use db.collection("name").where("field", value).and_where(...).limit(n).explain() and all() / all(fields=[...]) for subset rows. A longer on-disk + reopen example lives in the Python user guide — Realistic workflow. Typra also ships an experimental, read-only DB-API 2.0 adapter (typra.dbapi) with a minimal SELECT subset—see the Python guide.

Requirements

• CPython 3.9+
• Wheels use the stable ABI (cp39-abi3): one wheel per platform, compatible with Python 3.9+ on that platform.

Install

pip install "typra>=0.13.0,<0.14"

Pin the minor range you test against; pre-1.0 releases may still change APIs or the on-disk format between minors.

Quick start

# Setup: module, in-memory DB, and `books` collection (PK `title`).
import typra

db = typra.Database.open_in_memory()
cid, ver = db.register_collection(
    "books",
    '[{"path": ["title"], "type": "string"}]',
    "title",
)
# Example: insert one row, read it back, print package version.
print("registered", cid, ver)
db.insert("books", {"title": "Typra"})
print(db.get("books", "Typra"))
print(typra.__version__)

Output (the version line matches the installed wheel):

registered 1 1
{'title': 'Typra'}
0.13.0

On disk, use Database.open("app.typra") instead; registrations are persisted across process restarts for that path.

Indexed query (sketch)

# Setup: in-memory DB, indexed collection, one row.
import typra

db = typra.Database.open_in_memory()
fields = '[{"path": ["id"], "type": "int64"}, {"path": ["sku"], "type": "string"}]'
indexes = '[{"name": "sku_idx", "path": ["sku"], "kind": "index"}]'
db.register_collection("items", fields, "id", indexes)
db.insert("items", {"id": 1, "sku": "abc"})
# Example: equality query on indexed `sku`.
print(db.collection("items").where("sku", "abc").all())

Output:

[{'id': 1, 'sku': 'abc'}]

See docs/guide_python.md for and_where, limit, explain, and subset projections.

API overview

For behavior details (errors, edge cases, development), see the Python user guide.

fields_json (schema descriptor)

register_collection expects fields_json to be a JSON array of objects. Each object describes one field:

• path: JSON array of strings (path segments), e.g. ["profile", "name"].
• type: either a primitive name or a composite object.

Primitives: "bool", "int64", "uint64", "float64", "string", "bytes", "uuid", "timestamp".

Composites:

• Optional: {"optional": <inner>}
• List: {"list": <inner>}
• Object: {"object": [ … same shape as top-level field objects … ]}
• Enum: {"enum": ["a", "b"]} (variants must be strings)
• constraints (optional): JSON array of constraint objects, e.g. {"min_i64": 0}, {"max_length": 100}, {"email": true}, {"regex": "^[a-z]+$"}.

Example (nested)

# Setup: in-memory DB and a collection whose PK uses an optional int field.
import typra

db = typra.Database.open_in_memory()
db.register_collection(
    "items",
    '[{"path": ["x"], "type": {"optional": "int64"}}]',
    "x",
)
# Example: confirm registration.
print("nested:", db.collection_names())

Output:

nested: ['items']

Example (multiple fields)

# Setup: in-memory DB and a multi-field `books` schema (PK `title`).
import typra

db = typra.Database.open_in_memory()
schema = """[
  {"path": ["title"], "type": "string"},
  {"path": ["year"], "type": "int64"},
  {"path": ["tags"], "type": {"list": "string"}}
]"""
db.register_collection("books", schema, "title")
# Example: confirm registration.
print("multi:", db.collection_names())

Output:

multi: ['books']

Exceptions

• ValueError: invalid JSON, wrong shape, unknown type, invalid collection name, duplicate collection name, validation failures, or format/schema errors from the engine when registering.
• OSError: I/O failures when opening the database file.
• RuntimeError: reserved for engine “not implemented” paths (unexpected for supported API paths).

Building from source

You need Rust, Python 3.9+, and maturin. From the repo’s python/typra directory:

maturin develop --release
pytest -q

From the repository root, make check-full runs Rust + Python checks, tests, and make verify-doc-examples (validates documented command output). See also python/README.md (workspace layout for contributors).