synology_apm_repo.sdk.storage.table module

Schema-tolerant SQLite table access: declare the columns a query needs and whether each is required, and Table.create introspects the real table (PRAGMA table_info, once per connection). A missing optional column reads back as None for every row instead of raising no such column, which differs across connector versions.

class synology_apm_repo.sdk.storage.table.Column(name, required=True)

Bases: object

One column a Table expects; required=False for a column only some connector-version schemas have.

name: str
required: bool
class synology_apm_repo.sdk.storage.table.Table(name, columns)

Bases: object

A schema-tolerant view of one real SQLite table.

Introspects PRAGMA table_info(name) in create (once per connection, see sqlite.table_columns). A missing required column raises DataCorruptError; a missing optional one is left out of the SELECT and backfilled as None in every row.

Build with await Table.create(conn, name, columns), not Table(...): introspection is a query and __init__ can’t be async.

Variables:
  • name – The table name.

  • columns – The declared Columns.

async classmethod create(conn, name, columns, *, index_hints=())

Introspect name’s real schema and return a Table bound to conn.

Parameters:
  • conn (Connection) – Connection to query through.

  • name (str) – Table name.

  • columns (Sequence[Column]) – The columns callers need.

  • index_hints (Sequence[Sequence[str]]) – Column sequences callers will filter or sort by (e.g. [["parent_folder_id"]]), each passed to apply_index_hint, which copes with a read-only conn.

Raises:

DataCorruptError – The table is missing or lacks a required column.

async static exists_in(conn, name)

Whether name exists with at least one column. Call before create for a table some repository shapes lack entirely (e.g. file_meta); create raises for a missing table.

property columns_present: frozenset[str]

The table’s actual column set, independent of the declared columns, for callers that pick a column by heuristic because its name varies across repositories.

async select(where='', params=(), *, order_by=None, limit=None, offset=0)

Run SELECT <present columns> FROM <name> [WHERE <where>] [ORDER BY <order_by>] [LIMIT ? OFFSET ?] and yield each row as {column_name: value}, with every declared-but-absent optional column backfilled as None.

Parameters:
  • where (str) – Literal SQL written by the caller, never untrusted input; pass values through params.

  • params (Sequence[object]) – Values for the ? placeholders in where.

  • order_by (str | None) – Literal SQL ORDER BY fragment.

  • limit (int | None) – Row cap; None is uncapped but still honors offset (via LIMIT -1).

  • offset (int) – Rows to skip.

async select_one(where='', params=())

The first row select(where, params) yields, or None.

synology_apm_repo.sdk.storage.table.as_int(value)

Narrow one of Table.select’s object | None values to int.

Raises:

DataCorruptError – value is not an int.

synology_apm_repo.sdk.storage.table.as_str(value)

Narrow one of Table.select’s values to str.

Raises:

DataCorruptError – value is not a str.

synology_apm_repo.sdk.storage.table.sql_placeholders(n)

A comma-joined list of n "?" placeholders for IN (...). n must be positive: an empty IN () is invalid SQL.