calendaring_sync.store.sqlite module#

A store kept in a SQLite database file.

class calendaring_sync.store.sqlite.SQLiteStore(path, *, timeout=5.0)[source]#

Bases: StateStore

A store in a SQLite database file, shared between threads and processes.

Writes take one connection, one transaction at a time, and SQLite’s write lock for their whole transaction, so two processes on one file never interleave. Reads take a second connection, one at a time, so a read in one thread doesn’t wait for another thread’s write. A database at ":memory:" or an empty path belongs to one connection, so it has only that one, and its transactions take turns.

In SQLite’s default journal mode, a commit locks reads out of the file. So it waits for the reads open in this process, and reads in another process make it wait up to timeout seconds, then raise StoreBusyError; the store keeps reads short for that. A write also keeps what it changes in memory until it commits, so that reads aren’t locked out before then: a full listing takes about as much memory again as its change set holds. In WAL mode reads and a commit don’t lock each other out, so a commit waits for no read and a write keeps nothing extra in memory. The mode is kept in the file, so set it once with PRAGMA journal_mode = WAL; WAL doesn’t work on a network filesystem.

Parameters:

path (str | PathLike[str]) – The database file. It’s created, with the schema, if missing.
timeout (float) – Seconds to wait for another process before giving up.

Raises:

TypeError – If path or timeout has the wrong type.
StoreVersionError – If a newer calendaring-sync wrote the file.
StoreBusyError – If another process kept the file busy past timeout.
StoreError – If the file can’t be opened or isn’t a store.