This project has been archived by its maintainers, and is no longer receiving any updates.
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.
| Resource | Link |
|---|---|
| Repository | github.com/eddiethedean/typra |
| Rust crates | typra on crates.io |
| Full Python guide | docs/guide_python.md |
| Getting started | docs/guide_getting_started.md |
| Migrating 0.4 → 0.5 | docs/migration_0.4_to_0.5.md |
| Migrating 0.5 → 0.6 | docs/migration_0.5_to_0.6.md |
| Migrating 0.6 → 0.7 | docs/migration_0.6_to_0.7.md |
| Rust module layout | docs/03_rust_crate_and_module_layout.md |
| Changelog | CHANGELOG.md |
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
| Member | Description |
|---|---|
typra.__version__ |
Package version (matches the Rust workspace release). |
Database.open(path: str) |
Create or open a database file. Raises OSError if the path cannot be opened (e.g. missing parent directory, path is a directory). |
db.path() -> str |
Path used to open the database. |
db.register_collection(name, fields_json, primary_field, indexes_json=None) -> tuple[int, int] |
Register a new collection (schema version 1). Optional indexes_json: JSON array of {"name", "path", "kind"} objects ("unique" or "index" / "non_unique"). Returns (collection_id, schema_version). Names are trimmed; duplicates or bad JSON raise ValueError. |
db.collection(name) -> Collection |
Query handle: where, and_where, limit, explain, all / all(fields=[...]). |
db.insert(collection_name, row: dict) -> None |
Insert or replace the latest row (required fields + optional keys per schema). |
db.get(collection_name, pk) -> dict | None |
Latest row or missing. |
Database.open_in_memory() / Database.open_snapshot_bytes(data) / db.snapshot_bytes() |
In-memory DB and byte snapshots. |
db.collection_names() -> list[str] |
All registered names, sorted alphabetically. |
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).
Metadata
Release files for typra 0.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| typra-0.13.0.tar.gz | 125.2 kB | Without provenance | Details for typra-0.13.0.tar.gz |
Built distributions (wheels)
Total release size: 9.9 MB
Release files / typra-0.13.0.tar.gz
| Download URL | typra-0.13.0.tar.gz |
|---|---|
| Size | 125.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b838db62f027ada2514e72876928adb0a72dd5d7187a1a01662b778dea8220d1
|
|
BLAKE2b-256 checksum How to use checksums |
58ce76f26b7ac52f512483ba4a20a27f09be9881e63042691cec50c1a0f69374
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.12.3
|
Release files / typra-0.13.0-cp39-abi3-win_arm64.whl
| Download URL | typra-0.13.0-cp39-abi3-win_arm64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.9 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
13dc8f0fbb12575e2cab45459738a12bba9de36a054ce3af0f08dd24a8005531
|
|
BLAKE2b-256 checksum How to use checksums |
da6be57b6120385c0497fcd58eefb6672b977ba6519dc85a4ad5258568ada171
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.11.9
|
Release files / typra-0.13.0-cp39-abi3-win_amd64.whl
| Download URL | typra-0.13.0-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
d2b0b49cbda56d97875caaf41d8c0afb2db2991eb9409c5ec6a7a5486b7a50ed
|
|
BLAKE2b-256 checksum How to use checksums |
6ca65631d3b022aa02a1a0f72c3ed18aa4078c472f8a9994608ec25a30510fde
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.9.13
|
Release files / typra-0.13.0-cp39-abi3-musllinux_1_2_x86_64.whl
| Download URL | typra-0.13.0-cp39-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.9 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
a624939495f2b24f4bbcc548940053fae20f7c57f7494620b093be7290f8626c
|
|
BLAKE2b-256 checksum How to use checksums |
a21b090a005cdfd47e5c40e1cd6e2c9c0592bdb8a92a4d45c5ee9db81f9a6d16
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.9.25
|
Release files / typra-0.13.0-cp39-abi3-musllinux_1_2_aarch64.whl
| Download URL | typra-0.13.0-cp39-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.9 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
3cb59e48647551492e17802f213840f84849fab1745b89076fa4baf8d63e771a
|
|
BLAKE2b-256 checksum How to use checksums |
45351fc246dd36ccf0d9480e58d0a8bbbab64017b36f84acd4718909ce3bf2a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.9.25
|
Release files / typra-0.13.0-cp39-abi3-manylinux_2_28_aarch64.whl
| Download URL | typra-0.13.0-cp39-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
bd138235970105e588c00256714b24f7f495e5ef4553316d0fa0d7313bba737a
|
|
BLAKE2b-256 checksum How to use checksums |
4bb1687e3639b6b262ac4f9476db62f1cdb9f3d6ddf2303e171b24c1a710b22e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.12.3
|
Release files / typra-0.13.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | typra-0.13.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
0bd73de911a712b2964435dbb2a5b89911f3847a509e49c154f9769b12162e28
|
|
BLAKE2b-256 checksum How to use checksums |
f8604fc361053fe4b427892d3a02472c45b16e36fd7efffe67ce7637bb9be15d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.12.3
|
Release files / typra-0.13.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | typra-0.13.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
95738fc6a0ab676b595c91cb2c160bd7bed889012300b525f81a1b7d7f5c2186
|
|
BLAKE2b-256 checksum How to use checksums |
2bfa0e61fac7d0adb40675d0692fdcc15c31deb2901f21ab8fafd51156a45c4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.14.4
|
Release files / typra-0.13.0-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | typra-0.13.0-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
148c50ff097ba026532aea97c197d5ca2770ecae27e312abd812da5c18d3d9a4
|
|
BLAKE2b-256 checksum How to use checksums |
bf2324f27e95a064d368a212176ad785e73a7bcdcc13126bbd7089d08f630498
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.14.4
|
Security for typra 0.13.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.