Inbox — API reference¶

Database¶

connection ¶

connection(db_path: Path | None = None)

Context manager that opens and closes an inbox database connection.

ensure_schema ¶

ensure_schema(conn: Connection) -> None

Apply any pending migrations to the database.

Safe to call on every connection open — checks a single integer and returns immediately if the schema is current.

PARAMETER	DESCRIPTION
`conn`	Open inbox database connection. TYPE: `Connection`

get_connection ¶

get_connection(db_path: Path | None = None) -> Connection

Open an inbox database connection.

The connection has WAL journal mode enabled (for concurrent reads), foreign-key enforcement enabled, and the current schema applied via migrations.

PARAMETER	DESCRIPTION
`db_path`	Override the database path (defaults to `{data_dir}/inbox.db`). TYPE: `Path \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Connection`	A `sqlite3.Connection` ready for use. The caller must close it.

get_data_dir ¶

get_data_dir() -> Path

Return the mait-code data directory, creating it if needed.

get_db_path ¶

get_db_path() -> Path

Return the inbox database path.

get_project ¶

get_project() -> str

Return the current project identifier (basename of git root or cwd).

Delegates to mait_code.context.get_project(), falling back to the current directory name. On the inbox this is only a capture-context hint — the store itself is global.

Service¶

ItemNotFound ¶

ItemNotFound(item_id: int)

Bases: Exception

Raised by mutations when no inbox item has the given id.

add_item ¶

add_item(
    conn: Connection,
    *,
    body: str,
    project: str | None = None,
) -> int

Insert a captured item and return its new id.

count_items ¶

count_items(
    conn: Connection, *, project: str | None = None
) -> int

Return the number of items in the inbox (global unless project given).

get_item ¶

get_item(conn: Connection, item_id: int) -> dict | None

Return one item as a dict, or None if no item has that id.

list_items ¶

list_items(
    conn: Connection, *, project: str | None = None
) -> list[dict]

Return captured items oldest-first (capture order, for triage).

PARAMETER	DESCRIPTION
`conn`	Open inbox connection. TYPE: `Connection`
`project`	Restrict to one capture-context project, or `None` for the whole inbox (the default — capture is global). TYPE: `str \| None` DEFAULT: `None`

remove_item ¶

remove_item(conn: Connection, item_id: int) -> None

Delete an item permanently (triage routes it out, then removes it).

Raises :class:ItemNotFound if the id is unknown.

Entry point¶

main ¶

main()