mpedb-py — Python bindings for mpedb

CPython 3.12+ extension module (PyO3 0.29, abi3-py312: one wheel/.so for all 3.12+ versions). Module name: mpedb. Free-threading friendly by design: no module-level mutable state, and the GIL is released around every engine call, so point reads from multiple Python threads run truly in parallel.

Building

Manual (no extra tooling):

cargo build --release -p mpedb-py
mkdir -p /path/to/pymod
cp target/release/libmpedb_py.so /path/to/pymod/mpedb.so   # the rename is required
PYTHONPATH=/path/to/pymod python3.12 -c "import mpedb; print(mpedb.Database)"

The cdylib is built as libmpedb_py.so but must be importable as mpedb.so (the #[pymodule] is named mpedb, so its init symbol is PyInit_mpedb).

With maturin (builds a proper wheel):

pip install maturin && maturin build --release -m crates/mpedb-py/Cargo.toml

Tests (plain Python, no pytest; run it twice against the same directory to also exercise persistence across process restarts):

PYTHONPATH=/path/to/pymod python3.12 crates/mpedb-py/pytest/test_mpedb.py /tmp/mpedb-pytest
PYTHONPATH=/path/to/pymod python3.12 crates/mpedb-py/pytest/test_mpedb.py /tmp/mpedb-pytest

API

import mpedb
db = mpedb.Database("app.toml")   # open/create from a TOML config file

Value mapping (both directions)

Exceptions

mpedb.Error (Exception)
├── mpedb.IntegrityError     primary-key / UNIQUE / NOT NULL / CHECK violations
├── mpedb.ProgrammingError   parse, bind, type mismatch, wrong param count,
│                            unknown/invalidated plan, unsupported statement
└── mpedb.OperationalError   I/O, corruption, DbFull, ReadersFull, evicted
                             snapshot, config/schema mismatch, poisoned write
                             session, engine internals

Messages carry the engine's Display text. Binding-level misuse (bad params container, non-convertible value) raises the ordinary TypeError/OverflowError.

Locking rules (inherited from the Rust facade)

• Never call db.prepare(...), db.verify(), or db.query(...) for a not-yet-cached statement while a Transaction from the same handle is open on the same thread. They may need the single writer lock the transaction already holds; the ERRORCHECK mutex turns the relock into an error rather than a deadlock. Prepare the statements you need before db.begin(); inside the transaction, tx.query/tx.execute are always safe.
• Sessions poison on partially-applied statements. Statements are not internally atomic: if e.g. a multi-row UPDATE fails on its third row, the first two are already modified and the session becomes poisoned — every further tx.execute/tx.query and tx.commit() raises mpedb.OperationalError ("… poisoned …") and commit rolls back instead of persisting the torn statement. Only tx.rollback() (or leaving the with block via the exception) is valid. A statement that fails before any side effect (single-row constraint violation, type error) does not poison the session.
• One writer at a time, process-wide and machine-wide: db.begin() blocks on (or errors for re-entry into) the single writer lock. Readers never block.
• Use a Transaction from the thread that created it; the writer lock is a pthread mutex with thread affinity.