mud_server.db.errors

Typed database/domain exceptions for the DB package.

This module defines a small, explicit exception hierarchy used by repository modules to signal infrastructure failures (for example SQLite connection/query errors) without collapsing all failures into boolean return values.

Design intent:

Domain outcomes like “row not found” can still be represented by None/False where contracts already use those values.
Infrastructure failures should raise typed exceptions so API boundaries can map them to deterministic HTTP 5xx responses and logs.

Exceptions

`DatabaseError`	Base exception for DB-layer failures.
`DatabaseOperationError`	Base exception for repository operation failures.
`DatabaseReadError`	Repository read/query failure.
`DatabaseWriteError`	Repository mutation/transaction failure.

Classes

DatabaseOperationContext

Structured operation metadata carried by repository exceptions.

Module Contents

class mud_server.db.errors.DatabaseOperationContext[source]

Structured operation metadata carried by repository exceptions.

operation: Stable operation identifier (for example "sessions.create_session").

details: Optional human-readable context for logs and debugging.

operation: str

details: str | None = None

exception mud_server.db.errors.DatabaseError[source]

Bases: RuntimeError

Base exception for DB-layer failures.

Initialize self. See help(type(self)) for accurate signature.

exception mud_server.db.errors.DatabaseOperationError(*, context, cause=None)[source]

Bases: DatabaseError

Base exception for repository operation failures.

Parameters:

context (DatabaseOperationContext) – Structured operation metadata.
cause (Exception | None) – Optional underlying exception.

Initialize self. See help(type(self)) for accurate signature.

context

cause = None

exception mud_server.db.errors.DatabaseReadError(*, context, cause=None)[source]

Bases: DatabaseOperationError

Repository read/query failure.

Initialize self. See help(type(self)) for accurate signature.

exception mud_server.db.errors.DatabaseWriteError(*, context, cause=None)[source]

Bases: DatabaseOperationError

Repository mutation/transaction failure.

Initialize self. See help(type(self)) for accurate signature.