lacing.adapters.annot#

.annot portable file format adapter.

The .annot file is a SQLite database with the schema defined in lacing.store.sqlite. It’s the recommended portable handoff and archive format (BACK-DOC §3.1: “SQLite-as-app-format” — Git-trackable, email-attachable, single-file).

Unlike text-based adapters (TextGrid, WebVTT, JSON-LD), this one is non-lossy: the full annotation envelope, references, body, body schema URI, provenance, and confidence all round-trip exactly.

When loading, returns an in-memory MemoryStore for compatibility with the rest of the adapter API. To open an .annot file as a persistent store you can mutate, use SqliteStore(path) directly:

>>> from lacing.store import SqliteStore
>>> store = SqliteStore("project.annot")  # writes go straight to disk

Functions

dump(store[, target, overwrite])

Write store as an .annot SQLite file.

load(source, *[, persistent, migrate])

Open an .annot file.
lacing.adapters.annot.dump(store, target=None, *, overwrite=True, **_kwargs)[source]#

Write store as an .annot SQLite file.

Parameters:

  • store (IntervalAnnotationStore) – Source store. Can be any IntervalAnnotationStore.

  • target (str | PathLike | None) – Output path. None = return bytes.

  • overwrite (bool) – If True (default), replace any existing file at target. If False and the file exists, raise FileExistsError.

Return type:

bytes | None

lacing.adapters.annot.load(source, *, persistent=False, migrate=False, **_kwargs)[source]#

Open an .annot file.

Parameters:

  • source (str | bytes | PathLike) – Path to an .annot file. Bytes input is supported by writing to a temp file first.

  • persistent (bool) – If True, return an open SqliteStore (writes go to the file). If False (default), return a MemoryStore snapshot.

  • migrate (bool) – Opt-in to upgrading a file written at an older store schema_version on open (see lacing.store.migrations). A stale file otherwise refuses with SchemaMismatchError — same contract as SqliteStore. For bytes input the copy in the temp file is migrated regardless: it is not the caller’s file, and refusing to read bytes that cannot be re-pointed at the migration CLI would be a dead end.

Return type:

IntervalAnnotationStore

Returns:

MemoryStore (default) or SqliteStore (if persistent=True).