API reference

Auto-generated from the TinyStore source. Every public class, method, and exception is documented here directly from its docstring.

The top-level package re-exports the public API:

tinystore

TinyStore — a lightweight, Pydantic-native relational database.

Persists data as human-readable JSON files. No external server.

Example

.. code-block:: python

from tinystore import Database, Model, Field

db = Database("./app_data")


class User(Model):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    email: str = Field(unique=True, index=True)


db.register(User)
user = db.insert(User(name="Alice", email="alice@example.com"))
print(db.select(User).where(User.name == "Alice").first())  # Phase 2+

Database

Database(
    path: str | Path,
    *,
    lock_timeout: float = 30.0,
    optimistic_concurrency: bool = True,
    debug: bool = False,
    storage: JsonStorage | None = None,
    lock_manager: LockManager | None = None,
)

A TinyStore database rooted at a filesystem directory.

Parameters:

Name	Type	Description	Default
path	str | Path	Database directory. Created if missing.	required
lock_timeout	float	Seconds to wait for the database-wide lock before raising :class:~tinystore.exceptions.LockTimeoutError.	30.0
optimistic_concurrency	bool	If True (default), writes check a hidden row version and raise :class:~tinystore.exceptions.StaleDataError on stale updates.	True
debug	bool	Enable debug logging.	False

lock

lock(
    *, timeout: float | None = None
) -> Iterator[LockHandle]

Acquire the database-wide write lock for the duration of the block.

register

register(model_cls: type[T]) -> type[T]

Register a model class with this database.

Creates its table file if missing, validates schema compatibility with any previously-persisted schema, and updates metadata.json.

reset_schema

reset_schema() -> None

Discard all stored schema metadata (destructive — does NOT delete data).

related

related(obj: Model, name: str) -> Any

Explicitly load a related model or list of models for a relationship.

For a many-to-one / one-to-one relationship (the FK lives on this side) returns a single instance, or None when the FK is null or the referenced row is gone. For a one-to-many relationship (the FK lives on the related side) returns a list of instances.

The side is inferred from the declared foreign_key: if it names a local FK field, this is the "one" end (follow the FK to its parent); otherwise the related model is found by scanning registered models for one whose field named foreign_key points back at this table.

check

check() -> list[str]

Validate on-disk state. Returns a list of problem descriptions.

Checks that every table file parses, primary keys are unique, next_id exceeds the largest id in use, and registered foreign keys resolve to an existing row in the referenced table. An empty list means the database is consistent; problems are also logged at WARNING level.

backup

backup(target: str | Path) -> Path

Snapshot the database (excluding the lock file and journals).

DoesNotExist

DoesNotExist(message: str = 'Object does not exist')

Bases: TinyStoreError

Exactly one row was expected but none was found.

ForeignKeyError

Bases: IntegrityError

A foreign-key reference is invalid or would orphan a row.

IntegrityError

Bases: TinyStoreError

A data-integrity constraint was violated.

LockTimeoutError

Bases: TinyStoreError

The lock could not be acquired within the configured timeout.

MultipleObjectsReturned

MultipleObjectsReturned(
    message: str = "Multiple objects returned; expected one",
)

Bases: TinyStoreError

Exactly one row was expected but several matched.

QueryError

Bases: TinyStoreError

A query expression is invalid (e.g. incompatible-type comparison).

RelationshipError

Bases: TinyStoreError

A relationship could not be resolved (unknown name, ambiguous target, etc.).

SchemaError

Bases: TinyStoreError

The on-disk schema is missing, incompatible, or corrupt.

StaleDataError

StaleDataError(table: str, pk: object)

Bases: IntegrityError

The row was modified by another writer since it was loaded (optimistic concurrency).

StorageError

Bases: TinyStoreError

The underlying storage layer reported a failure (I/O, corruption).

TinyStoreError

Bases: Exception

Base class for every TinyStore error.

TransactionError

Bases: TinyStoreError

A transaction was used incorrectly (e.g. nested transactions).

UniqueConstraintError

UniqueConstraintError(
    table: str, field: str, value: object
)

Bases: IntegrityError

A unique constraint would be violated by this write.

Model

Bases: BaseModel

Base class for all TinyStore models.

Subclass it, declare Pydantic fields, and optionally a nested Meta class to override the table name::

class User(Model):
    id: int | None = Field(default=None, primary_key=True)
    name: str

    class Meta:
        table_name = "accounts"

Relationship dataclass

Relationship(
    foreign_key: str,
    to: Any = None,
    cardinality: str = CARDINALITY_MANY,
)

Declarative marker used as the default value of a relationship field.

to may be omitted when the relationship target can be inferred from the field's type annotation (resolved after all models are registered).

TableSchema dataclass

TableSchema(
    name: str,
    model_qualname: str,
    fields: tuple[FieldMetadata, ...] = field(
        default_factory=tuple
    ),
    relationships: tuple[
        tuple[str, str, str, str], ...
    ] = field(default_factory=tuple),
)

Serializable schema snapshot for one table.

Table

Table(database: Database, model_cls: type[T])

Bases: Generic[T]

CRUD interface for a single model.

ensure_created

ensure_created() -> None

Create the table file if missing, with the empty-table skeleton.

Field

Field(
    default: Any = ...,
    *,
    primary_key: bool = False,
    autoincrement: bool | None = None,
    unique: bool = False,
    index: bool = False,
    nullable: bool | None = None,
    foreign_key: str | None = None,
    on_delete: OnDelete = "RESTRICT",
    **kwargs: Any,
) -> Any

Declare a model field with TinyStore metadata.

See the project plan for the full semantics of each keyword.

Modules

Module	Purpose
database	Database — the main entry point.
model	Model and Field — defining tables.
relationships	Relationship and db.related().
schema	TableSchema, field metadata, schema evolution.
table	Table — the in-memory collection backing a model.
query	SelectQuery, joins, expressions.
transaction	Transaction context manager.
storage	Storage backends (JsonStorage).
indexes	In-memory hash indexes.
locking	File / thread locking.
serialization	Row serialization internals.
exceptions	The TinyStoreError hierarchy.