Types & Constants

Type aliases, constants, enums, and protocols used throughout the library.

OpType

OpType

Bases: IntEnum

Operation type stored in each WAL entry.

Encoded as an integer for compact msgpack serialisation. Using IntEnum so the value is directly packable without conversion.

Constants

Type stub for app.types — type aliases, constants, enums, and protocols.

TOMBSTONE = b'\x00__tomb__\x00' module-attribute

Sentinel value written in place of a value to mark a key as deleted.

BLOCK_SIZE_DEFAULT = 4096 module-attribute

Default SSTable data-block size in bytes (4 KB).

MAX_MEMTABLE_SIZE = 67108864 module-attribute

Maximum memtable size in bytes (64 MB) before it is frozen and flushed.

L0_COMPACTION_THRESHOLD = 10 module-attribute

Number of L0 SSTables that triggers a compaction run to L1.

IMMUTABLE_QUEUE_MAX = 4 module-attribute

Maximum frozen memtable snapshots queued before backpressure kicks in.

COMPACTION_CHECK_INTERVAL = 0.5 module-attribute

Seconds between compaction worker wake-ups to check L0 file count.

PARALLELISM_MODE = _detect_parallelism_mode() module-attribute

Parallelism strategy: 'free_threaded' when GIL is disabled, else 'multiprocessing'.

Protocols

BloomFilterProtocol

BloomFilterProtocol

Bases: Protocol

Structural interface for a probabilistic bloom-filter membership set.

add(key)

Insert key into the filter.

Source code in app/types.py

def add(self, key: Key) -> None:
    """Insert *key* into the filter."""
    ...

may_contain(key)

Return True if key might be present (false positives are allowed).

Source code in app/types.py

def may_contain(self, key: Key) -> bool:
    """Return True if *key* might be present (false positives are allowed)."""
    ...

to_bytes()

Serialize the filter to a compact byte string for persistence.

Source code in app/types.py

def to_bytes(self) -> bytes:
    """Serialize the filter to a compact byte string for persistence."""
    ...

from_bytes(data) classmethod

Deserialize and return a filter instance from data.

Source code in app/types.py

@classmethod
def from_bytes(cls, data: bytes) -> Self:
    """Deserialize and return a filter instance from *data*."""
    ...

KVIteratorProtocol

KVIteratorProtocol

Bases: Protocol

Structural interface for a sorted key-value cursor (e.g. SSTable, MemTable).

seek(key)

Position the cursor at the first entry >= key.

Source code in app/types.py

def seek(self, key: Key) -> None:
    """Position the cursor at the first entry >= *key*."""
    ...

__iter__()

Return the iterator object itself.

Source code in app/types.py

def __iter__(self) -> Iterator[tuple[Key, Value]]:
    """Return the iterator object itself."""
    ...

__next__()

Advance and return the next (key, value) pair, or raise StopIteration.

Source code in app/types.py

def __next__(self) -> tuple[Key, Value]:
    """Advance and return the next (key, value) pair, or raise StopIteration."""
    ...