Python API reference

Records and operations

A database starts empty; callers supply records. Keys and integer values are signed 64-bit integers. Text is UTF-8 limited to 31 encoded bytes. The public Python entry points are from refpot import Database, Row, with CRUD operations and explicit transactions. The database path names a file, not a directory; its parent directory must already exist.

SQL, ORM, arbitrary Python values, secondary indexes, migrations, and existing-format compatibility are not provided. No independent physical replicas are maintained.

Python API

from refpot import Database, Row

• Database(path) opens or creates a database at a file path. The parent directory must exist.
• insert(key, value, text="") creates a row; returns None.
• get(key) returns an immutable, detached Row(key, value, text).
• update(key, *, value=None, text=None) updates an existing row. Omitted fields and None leave that field unchanged; there is no NULL value in this schema.
• delete(key) deletes an existing row; returns None.
• len(db) counts the visible rows, including the current transaction’s staged changes.
• transaction() returns a context manager. Normal exit commits; an uncaught exception rolls back. Nested transactions are rejected. A caught validation/missing/duplicate error does not undo earlier valid staged operations or apply a partial offending operation.
• checkpoint() publishes committed state and reclaims redo; it is rejected inside an explicit transaction.
• close() releases ownership and discards any staged transaction. It is idempotent. Do not close a database inside a transaction’s context; that context cannot subsequently commit.
• with Database(path) as db: releases ownership on exit; individual acknowledged mutations do not depend on destructor or close-time checkpointing.

Duplicate inserts raise ValueError; missing get/update/delete raises KeyError. Booleans, floats and strings are not coerced to integers (TypeError); integers outside signed 64-bit range raise OverflowError. Oversized, invalid-UTF-8 text raises ValueError. Exceeding serialized snapshot or transaction redo capacity raises ValueError before writing. Closed handles, nested transactions, wrong ownership, corruption and I/O failures raise RuntimeError.

Ownership and concurrency

Only the creating process and creating thread may use or close a database handle; inherited handles cannot be used after fork(). Database-path symlinks and hard links are rejected. Parent-directory aliases still refer to the same lock-file inode. Do not delete or replace a held .lock, alias the sidecar files, or mutate database files outside the engine. This preview assumes a private, trusted local filesystem namespace.

A process obtains exclusive ownership of a database. The public API is thread-affine; concurrent readers, multiwriter operation, and Windows support are not claimed.

Performance and maturity

The historical 3.04–5.95× result belongs only to the audited experimental update harness, not this Python package. Package performance has not been qualified. The known reopen result remains 16/16 losses in the historical comparison. The transaction change set and checked encoded-size accounting avoid full-map copies during staging and commit preparation. This is not presented as benchmark-fast, and CPU optimization is future work.

There is no stable API, general performance claim, or production durability guarantee. See the recommendation, roadmap, and experimental methodology.

Download this page as Markdown