httk.store.query.protocols

Typed protocols for the store/searcher query contract.

These protocols define the backend-agnostic query interface shared by httk data stores: the database layer in httk-store implements them over SQL, and serving modules (such as httk-serve, whose in-memory store also conforms) program against them. They mirror the query interface of the httk v1 database layer (httk.db FilteredCollection searchers), so lightweight fakes can stand in for a real store in tests.

Attributes

ID_FIELD

The backend field name used for the served entry identifier.

Exceptions

UnsupportedQueryError	Report that a valid query operation is outside a store's supported profile.
CountUnavailableError	Report that a store cannot provide an exact query count.
NoResultError	Report that a result-set one() operation found no matching result.
MultipleResultsError	Report that a result-set one() operation found multiple results.
PaginationCursorError	Report that a continuation cursor is malformed, expired, or belongs to another result plan.

Classes

PageOrder	Order a continuation page by one named scalar result projection.
ContinuationToken	Carry an opaque URL-safe continuation value.
ResultPage	Represent an immutable continuation-page result.
PageableResultSetLike	Expose optional continuation-page capability on a frozen result set.
ResultRow	Represent one named result row by position, name, or attribute.
ResultRowLike	Require named access to one result row.
ResultSetLike	Require the common operations of a materialized result set.
SearchExpression	Require composable backend search expressions.
SearchField	Expose a queryable field of a search variable.
SearchVariable	Bind a query variable to a target type whose attributes yield fields.
SearchResult	Represent one match with declared output values and names.
Searcher	Build one query and iterate its results.
Store	Require a store that can create a query searcher.

Module Contents

httk.store.query.protocols.ID_FIELD: Final = '__id'

The backend field name used for the served entry identifier.

exception httk.store.query.protocols.UnsupportedQueryError

Bases: ValueError

Report that a valid query operation is outside a store’s supported profile.

exception httk.store.query.protocols.CountUnavailableError

Bases: RuntimeError

Report that a store cannot provide an exact query count.

exception httk.store.query.protocols.NoResultError

Bases: LookupError

Report that a result-set one() operation found no matching result.

exception httk.store.query.protocols.MultipleResultsError

Bases: LookupError

Report that a result-set one() operation found multiple results.

exception httk.store.query.protocols.PaginationCursorError

Bases: ValueError

Report that a continuation cursor is malformed, expired, or belongs to another result plan.

class httk.store.query.protocols.PageOrder

Order a continuation page by one named scalar result projection.

name identifies the name supplied to results() (or Searcher.output()), never a backend column object. The result-set implementation validates that it is a root scalar projection before it generates SQL.

Parameters:

• name – The declared scalar output name used for ordering.

• descending – Whether to order this field in descending order.

• nulls – Whether null values sort first or last.

name: str

descending: bool = False

nulls: Literal['first', 'last'] = 'last'

class httk.store.query.protocols.ContinuationToken

Bases: str

Carry an opaque URL-safe continuation value.

It is a str subclass so normal JSON serializers preserve it as a scalar value. Applications should pass a token returned by a page back unchanged; data backends validate its version, structure, and result-plan fingerprint before using any decoded value as a bound parameter.

Parameters:

value – The opaque continuation value.

class httk.store.query.protocols.ResultPage

Represent an immutable continuation-page result.

rows is always a tuple. Returned rows are ordinary persistent result rows, not the expiring proxies produced by SqlResultSet.cursor(). total is populated only when the caller explicitly asks for it.

Parameters:

• rows – The persistent rows returned by the page.

• next – The token for the next page, if one exists.

• previous – The token for the previous page, if one exists.

• total – The exact result count when requested, otherwise None.

rows: tuple[ResultRowLike, Ellipsis]

next: ContinuationToken | None

previous: ContinuationToken | None

total: int | None = None

class httk.store.query.protocols.PageableResultSetLike

Bases: Protocol

Expose optional continuation-page capability on a frozen result set.

This deliberately extends neither ResultSetLike nor Searcher: stores that do not support seek pagination remain fully conforming to the required portable contracts.

page(*, size, order_by, cursor=None, include_total=False)

Return one ordered continuation page.

class httk.store.query.protocols.ResultRow(values, names, resolver=None, guard=None)

Represent one named result row by position, name, or attribute.

Parameters:

• values (tuple[Any, Ellipsis]) – The row values in declaration order.

• names (tuple[str, Ellipsis]) – The corresponding output names.

• resolver (Any) – An optional lazy value resolver.

• guard (Any) – An optional callback that rejects access to expired values.

property names: tuple[str, Ellipsis]

Return the declared output names.

property values: tuple[Any, Ellipsis]

Return the row values in declaration order.

class httk.store.query.protocols.ResultRowLike

Bases: Protocol

Require named access to one result row.

property names: tuple[str, Ellipsis]

Return the row’s declared output names.

class httk.store.query.protocols.ResultSetLike

Bases: Protocol

Require the common operations of a materialized result set.

first()

Return the first row, or None when no row matches.

one()

Return the only row, or raise when the count is not one.

scalars(name=None)

Iterate over one named scalar output.

class httk.store.query.protocols.SearchExpression

Bases: Protocol

Require composable backend search expressions.

class httk.store.query.protocols.SearchField

Bases: Protocol

Expose a queryable field of a search variable.

In addition to the methods below, fields support the rich comparison operators (==, !=, <, <=, >, >=), returning SearchExpression. The handlers invoke those via getattr(field, '__eq__')(value) since the comparison dunders cannot be typed as expression-returning.

The three string-matching methods take literal text: no wildcard or pattern syntax whatsoever crosses this contract, so % and _ (and any other metacharacter) match themselves. A backend is therefore free to implement them with SQL LIKE over an escaped pattern, with a regular expression, or with a full-text index — the choice is invisible here.

has(value)

Match a list field containing value.

has_any(*values)

Match a list field containing any of values.

has_only(*values)

Match a list field containing no values outside values.

is_in(*values)

Match a root scalar field whose value is one of values.

None is an explicit member: it matches a null field value, and its negation excludes nulls rather than inheriting SQL’s three-valued NOT IN (..., NULL) behavior.

Backends define the corresponding semantics for child or set fields; for example, a backend may use the existing has_only-style all-values reading for a child field.

contains(text)

Match values containing text as a literal substring.

startswith(prefix)

Match values beginning with the literal prefix.

endswith(suffix)

Match values ending with the literal suffix.

class httk.store.query.protocols.SearchVariable

Bases: Protocol

Bind a query variable to a target type whose attributes yield fields.

always_true/always_false are reserved names: they are real methods of the variable, never stored fields resolved through __getattr__. They exist so a translation layer can express a constant truth value without inventing a probe field. A field == field probe is NULL-unsound, since it yields NULL (not true) for a NULL field.

always_true()

An expression that matches every row.

always_false()

An expression that matches no row.

class httk.store.query.protocols.SearchResult

Bases: NamedTuple

Represent one match with declared output values and names.

values holds one entry per Searcher.output() call in declaration order; it is a tuple, so values, names = result and result[0][0] both work.

values: tuple[Any, Ellipsis]

names: tuple[str, Ellipsis]

class httk.store.query.protocols.Searcher

Bases: Protocol

Build one query and iterate its results.

Iteration yields one SearchResult per match, so item[0][0] is the first declared output of the match (typically the matched row object). The expressions received by add are always ones produced by this same backend’s search variables, so implementations may type them as their own expression class; a backend that needs a second (post-filter) evaluation position decides that from the expression itself, not from the caller.

offset: int

variable(target)

Bind a query variable to target.

output(variable, name)

Declare variable as a named result output.

add(expression)

Add a filter expression to the query.

count()

Return the exact count of the current query.

set_limit(limit)

Set the query limit.

add_offset(offset)

Add an offset to the query.

add_sort(field, descending)

Add a field sort to the query.

results(**outputs)

Return a result set for the requested named outputs.

class httk.store.query.protocols.Store

Bases: Protocol

Require a store that can create a query searcher.

searcher()

Create an empty searcher.