Errors and ownership

These guides exercise the public experimental alpha. Install with python -m pip install refpot==0.1.1 on CPython 3.11–3.14. Prebuilt wheels cover Linux x86_64 and macOS arm64; only source builds need a C++17 toolchain. The API and storage format are not stable. Do not use these examples as performance or physical power-loss qualification.

Handle validation errors without changing stored data

Save this as errors.py and run python errors.py. The program demonstrates two rejected operations and verifies the original row is intact.

from pathlib import Path
from tempfile import TemporaryDirectory

from refpot import Database, Row

with TemporaryDirectory() as directory:
    path = Path(directory) / "validation.rp"
    with Database(path) as db:
        db.insert(1, 42, "answer")
        try:
            db.insert(1, 99)
        except ValueError:
            pass
        else:
            raise AssertionError("duplicate insert was accepted")
        try:
            db.update(1, text="é" * 16)
        except ValueError:
            pass
        else:
            raise AssertionError("oversized UTF-8 text was accepted")
        assert db.get(1) == Row(1, 42, "answer")

The text limit counts encoded bytes, not characters: "é" * 16 uses 32 UTF-8 bytes. Booleans and non-integer keys/values raise TypeError; out-of-range integers raise OverflowError. Missing keys raise KeyError. Closed handles, corrupt storage, invalid ownership and I/O failures raise RuntimeError; consult the exact contract for each operation.

Keep one owner and treat uncertain writes separately

Use a private, trusted filesystem namespace. A database path names a file, not a directory; its parent must already exist. One process exclusively owns each database and only the creating thread may use its handle. Do not pass a handle to another thread or use an inherited handle after fork().

An uncertain write poisons the owner. Close it, reopen and inspect stored state before choosing whether to retry: the uncertain transaction may be entirely present or absent. A RuntimeError is not proof that nothing committed. Avoid blind retries that can duplicate application actions. Capacity/argument rejection is distinct from an uncertain I/O failure. Recovery implementation checks are bounded and do not establish broad filesystem or physical power-loss guarantees.

Continue with API reference and recovery internals.

Download this page as Markdown