API reference

The typed public surface of the lexindex Python package.

StringIndex

lexindex.StringIndex

Ordered string↔id index (FST) with prefix / range / fuzzy / subsequence queries.

__doc__ class-attribute

__doc__ = "Ordered string↔id index (FST) with prefix / range / fuzzy / subsequence queries."

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__module__ class-attribute

__module__ = 'lexindex._core'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__contains__ method descriptor

__contains__(key: str) -> bool

Return bool(key in self).

__iter__ method descriptor

__iter__() -> Iterator[tuple[str, int]]

Implement iter(self).

__len__ method descriptor

__len__() -> int

Return len(self).

__new__ builtin

__new__(*args, **kwargs) -> StringIndex

Create and return a new object. See help(type) for accurate signature.

contains method descriptor

contains(key: str) -> bool

Whether key is present.

from_bytes staticmethod

from_bytes(data: bytes) -> StringIndex

Reconstruct from a [PyStringIndex::to_bytes] blob.

fuzzy method descriptor

fuzzy(
    query: str, max_distance: int, limit: int | None = None
) -> list[tuple[str, int]]

(key, id) pairs within Levenshtein edit distance max_distance of query.

id method descriptor

id(key: str) -> int | None

Id of key, or None if absent.

ids_of method descriptor

ids_of(keys: Sequence[str]) -> list[int | None]

Batched id: one call for many keys, looping in Rust to amortise the Python↔Rust boundary. Returns a list aligned with keys, None where a key is absent. (Named ids_of, not ids/keys, so the class is not mistaken for a mapping by dict(index).)

key method descriptor

key(id: int) -> str | None

Key for id, or None if out of range.

keys_of method descriptor

keys_of(ids: Sequence[int]) -> list[str | None]

Batched key: one call for many ids. Returns a list aligned with ids, None where an id is out of range.

load staticmethod

load(path: str | PathLike[str]) -> StringIndex

Load an index previously written with save.

load_mmap staticmethod

load_mmap(path: str | PathLike[str]) -> StringIndex

Zero-copy load: memory-map the file and borrow the index from it — no read into RAM, so a multi-gigabyte index is ready instantly and its pages are shared across processes.

The mapped file must not be modified or truncated by any process while the index is alive: the bytes are borrowed, not copied, so a concurrent write is undefined behaviour rather than a stale answer. Python cannot express that obligation in the type system the way the Rust API does (where this is an unsafe fn), so it is the caller's contract. Use load if the file may change.

predecessor method descriptor

predecessor(query: str) -> tuple[str, int] | None

The largest (key, id) with key <= query, or None if every key is larger.

prefix method descriptor

prefix(
    prefix: str, limit: int | None = None
) -> list[tuple[str, int]]

(key, id) pairs whose key starts with prefix, lexicographically ordered. limit stops after that many matches, walking no further — what autocomplete wants, since it needs ten of them, not every match.

range method descriptor

range(
    lo: str, hi: str, limit: int | None = None
) -> list[tuple[str, int]]

(key, id) pairs with lo <= key < hi, lexicographically ordered. limit stops after that many matches.

save method descriptor

save(path: str | PathLike[str]) -> None

Write the index to path.

subsequence method descriptor

subsequence(
    query: str, limit: int | None = None
) -> list[tuple[str, int]]

(key, id) pairs whose key contains query as a subsequence. limit stops after that many matches.

successor method descriptor

successor(query: str) -> tuple[str, int] | None

The smallest (key, id) with key >= query, or None if every key is smaller.

to_bytes method descriptor

to_bytes() -> bytes

Serialise to a bytes blob.

CompactHashIndex

lexindex.CompactHashIndex

Fingerprint minimal-perfect-hash dictionary: the smallest string -> dense id map. Membership is probabilistic (false-positive rate 2 ** -fingerprint_bits) and there is no reverse id -> key.

__doc__ class-attribute

__doc__ = "Fingerprint minimal-perfect-hash dictionary: the smallest `string -> dense id` map. Membership is\nprobabilistic (false-positive rate `2 ** -fingerprint_bits`) and there is no reverse `id -> key`."

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__module__ class-attribute

__module__ = 'lexindex._core'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

fingerprint_bits property

fingerprint_bits: int

Width of the stored fingerprints in bits; the false-positive rate is 2 ** -fingerprint_bits.

__contains__ method descriptor

__contains__(key: str) -> bool

Return bool(key in self).

__len__ method descriptor

__len__() -> int

Return len(self).

__new__ builtin

__new__(*args, **kwargs) -> CompactHashIndex

Create and return a new object. See help(type) for accurate signature.

contains method descriptor

contains(key: str) -> bool

Whether key is present (subject to the false-positive rate).

from_bytes staticmethod

from_bytes(data: bytes) -> CompactHashIndex

Reconstruct from a [PyCompactHashIndex::to_bytes] blob.

The blob must have been produced by this library. Its framing is validated, but the embedded perfect hash cannot be — a deliberately crafted blob is undefined behaviour.

id method descriptor

id(key: str) -> int | None

Dense id of key (membership checked against the fingerprint), or None.

id_unchecked method descriptor

id_unchecked(key: str) -> int

Dense id of key without the fingerprint check — key must be a member, or the result is an arbitrary valid slot. Fastest lookup for a fixed vocabulary.

ids_of method descriptor

ids_of(keys: Sequence[str]) -> list[int | None]

Batched id: one call for many keys, aligned with keys (None where absent).

load staticmethod

load(path: str | PathLike[str]) -> CompactHashIndex

Load a dictionary previously written with save.

The file must have been written by this library — see from_bytes for why a crafted blob cannot be rejected.

load_mmap staticmethod

load_mmap(path: str | PathLike[str]) -> CompactHashIndex

Zero-copy load: memory-map the file and borrow the fingerprint table.

The mapped file must not be modified or truncated by any process while the dictionary is alive — the bytes are borrowed, so a concurrent write is undefined behaviour. See StringIndex.load_mmap for the full contract; use load if the file may change.

save method descriptor

save(path: str | PathLike[str]) -> None

Write the dictionary to path.

to_bytes method descriptor

to_bytes() -> bytes

Serialise to a bytes blob.

PerfectHashIndex

lexindex.PerfectHashIndex

Minimal-perfect-hash dictionary: fastest exact string → dense id, with persistence.

__doc__ class-attribute

__doc__ = "Minimal-perfect-hash dictionary: fastest exact `string → dense id`, with persistence."

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__module__ class-attribute

__module__ = 'lexindex._core'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__contains__ method descriptor

__contains__(key: str) -> bool

Return bool(key in self).

__len__ method descriptor

__len__() -> int

Return len(self).

__new__ builtin

__new__(*args, **kwargs) -> PerfectHashIndex

Create and return a new object. See help(type) for accurate signature.

contains method descriptor

contains(key: str) -> bool

Whether key is present.

from_bytes staticmethod

from_bytes(data: bytes) -> PerfectHashIndex

Reconstruct from a [PyPerfectHashIndex::to_bytes] blob.

The blob must have been produced by this library. Its framing is validated, but the embedded perfect hash cannot be — a deliberately crafted blob is undefined behaviour.

id method descriptor

id(key: str) -> int | None

Dense id of key (membership verified), or None if absent.

id_unchecked method descriptor

id_unchecked(key: str) -> int

Dense id of key without membership verification — key must be in the dictionary, or the result is an arbitrary valid slot. Fastest lookup for a fixed vocabulary.

ids_of method descriptor

ids_of(keys: Sequence[str]) -> list[int | None]

Batched id: one call for many keys, aligned with keys (None where absent).

key method descriptor

key(id: int) -> str | None

Key for id, or None if out of range.

keys_of method descriptor

keys_of(ids: Sequence[int]) -> list[str | None]

Batched key: one call for many ids, aligned with ids (None where out of range).

load staticmethod

load(path: str | PathLike[str]) -> PerfectHashIndex

Load a dictionary previously written with save.

The file must have been written by this library — see from_bytes for why a crafted blob cannot be rejected.

load_mmap staticmethod

load_mmap(path: str | PathLike[str]) -> PerfectHashIndex

Memory-map the file and borrow the key arena zero-copy (only the small MPH is read into RAM).

The mapped file must not be modified or truncated by any process while the dictionary is alive — the bytes are borrowed, so a concurrent write is undefined behaviour. See StringIndex.load_mmap for the full contract; use load if the file may change.

save method descriptor

save(path: str | PathLike[str]) -> None

Write the dictionary to path.

to_bytes method descriptor

to_bytes() -> bytes

Serialise to a bytes blob.