sekejap for Python

An embedded, disk-first, multi-model database: documents addressed by collection and key, SQL with $n parameters over the same rows, typed edges between them, and vector and spatial fields in the one store.

This package is pure Python. It compiles nothing and it contains no Rust: it loads libsekejap — the shared library built from dist/ffi, whose contract is docs/dist/C_ABI.md — and calls its 59 entry points through ctypes. A platform wheel ships that library inside the package; an install from the source distribution finds one on the machine.

from sekejap import Db

with Db("./data") as db:
    db.create_collection("venues", [
        {"name": "name", "kind": "text"},
        {"name": "suburb", "kind": "text"},
        {"name": "capacity", "kind": "int"},
    ])
    db.put("venues", "the_tote", {"name": "The Tote", "suburb": "Collingwood"})

    for row in db.query("SELECT _key, name FROM venues WHERE suburb = $1",
                        ["Collingwood"]):
        print(row["_key"], row["name"])

Install

pip install sekejap

A wheel for your platform carries the library and needs nothing else. If you installed from the source distribution, or you want to run against a library you built yourself:

cargo build --release -p sekejap-capi          # in the sekejap repository
export SEKEJAP_LIBRARY=/path/to/libsekejap.dylib

SEKEJAP_LIBRARY is looked at first, then sekejap/_lib/ inside the package, then the platform loader path (DYLD_LIBRARY_PATH, LD_LIBRARY_PATH, PATH, and wherever make install in dist/ffi put it). sekejap.library_path() says which one this process loaded.

The handles

One class per opaque pointer in the C ABI. Each is a context manager, and closing a Db closes every handle taken from it first, because each of them borrows it.

Errors

A failure raises. The exception carries code, a Status enumeration member, so you branch on the code and never on the text of message.

from sekejap import Db, Refused, Status

try:
    db.compact()
except Refused as refusal:
    print(refusal.code is Status.REFUSED, refusal.message)

SekejapError is the base; Refused, Corrupt, Unsupported, IoFailure, Invalid, Busy and UnknownRow are the named ones. A miss is not a failure and does not raise: db.get and db.describe answer None, a walk answers None at its end, and db.next_change answers None when nothing arrived.

Every C function, and the call that reaches it

The four refusals keep their names so the reason arrives as a sentence rather than as an AttributeError.

Service mode

Db.open_service(path) is one writer, parallel readers on a published snapshot, and the commit-time change feed. Every service call on a single-mode handle is refused by name.

db = Db.open_service("./data")
subscription = db.subscribe()
db.put("venues", "the_tote", {"name": "The Tote"})
event = db.next_change(subscription, timeout_ms=1000)
print(event["sequence"], event["keys"])

pandas

db.df is a namespace, and pandas is imported only when you touch it.

frame = db.df.query("SELECT _key, name, capacity FROM venues")
db.df.put(frame, "venues")          # the index is the key

A shell

python -m sekejap ./data                    # a prompt
python -m sekejap ./data "SELECT * FROM venues"

Running the tests

SEKEJAP_LIBRARY=/path/to/libsekejap.dylib make test

What changed from 0.16

The 0.16 package was a PyO3 extension module over CoreDB, and its API is gone rather than renamed:

• DB, Hit and EdgeHit are gone. A row is addressed by collection and key, not by one collection/key slug string, and a query answers plain dict rows keyed by column name.
• DB() with no argument opened an in-memory database. There is none: sekejap.open_memory() exists only to refuse, by name, with the reason.
• db.show("SHOW TABLES") is refused; db.collections() and db.describe(name) answer the same questions as data.
• trim_memory and memory_report are refused: the buffer pool is bounded at open and there is nothing proportional to rows to give back.
• FROM MATCH, PATH_*, SHORTEST and the rest of the 0.16 graph dialect are SQL questions now, answered or refused by name by sekejap-lang.

Code written against 0.16 fails at import rather than silently meaning something else.