httk.core.storage.stored_properties¶

Backend-neutral declarations for properties of durable entry backings.

An entry family may have several concrete durable representations. Each backing declares its own served-property map with StoredPropertyProjection; the declaration remains entirely in the domain package while a storage implementation translates its query callbacks to its native query language. Nothing here assumes SQL, OPTIMADE, or a particular record family.

The query protocols deliberately describe expression construction, rather than expression evaluation. A domain callback only receives a QueryContext; the storage backend supplies its implementation and is therefore free to use SQL, a document query, or an in-memory evaluator.

Attributes¶

`STORED_PROPERTY_PROJECTIONS_ATTRIBUTE`	Exact-class attribute holding a backing's property-projection mapping.
`StoredPropertyResponse`	Extract one served property value from one concrete backing record.
`StoredPropertyQuery`	Build one predicate from a context, protocol operator, and parsed literal.
`StoredPropertySort`	Select one sortable backing value from a query context.

Exceptions¶

QueryLiteralError

A query literal cannot represent the property value requested.

Classes¶

`QueryExpression`	One backend-neutral boolean predicate.
`QueryValue`	A scalar or aggregate value participating in a query expression.
`QueryField`	A durable field selected from a `QueryScope`.
`QueryScope`	A record or correlated child/reference scope.
`QueryContext`	Factory and algebra used by domain-owned property query callbacks.
`StoredPropertyProjection`	One domain-owned projection of a served property for one backing.

Functions¶

stored_property_projections(cls)

Return a validated property's projection map declared on cls.

Module Contents¶

httk.core.storage.stored_properties.STORED_PROPERTY_PROJECTIONS_ATTRIBUTE: Final = '__httk_stored_properties__'¶: Exact-class attribute holding a backing’s property-projection mapping.

exception httk.core.storage.stored_properties.QueryLiteralError[source]¶

Bases: ValueError

A query literal cannot represent the property value requested.

This is intentionally distinct from a query expression which simply matches no records. Protocol layers can translate it into their user-facing invalid-filter-value error without depending on a domain package’s parser exception.

class httk.core.storage.stored_properties.QueryExpression[source]¶

Bases: Protocol

One backend-neutral boolean predicate.

Query callbacks compose predicates with the ordinary boolean operators; the backend decides how to retain SQL’s three-valued null semantics (or an equivalent semantics in another storage engine).

class httk.core.storage.stored_properties.QueryValue[source]¶

Bases: Protocol

A scalar or aggregate value participating in a query expression.

class httk.core.storage.stored_properties.QueryField[source]¶

Bases: QueryValue, Protocol

A durable field selected from a QueryScope.

class httk.core.storage.stored_properties.QueryScope[source]¶

Bases: Protocol

A record or correlated child/reference scope.

scope(name) follows a durable reference or child relationship while retaining correlation to this scope. It intentionally does not say whether that relationship is one-to-one or a collection: exists and the aggregate methods on QueryContext give both cases a single, portable vocabulary. Every scope call creates a distinct peer scope, even for the same relationship name, so a callback can compare correlated child rows without an accidental self-alias.

field(name)[source]¶

Return the durable scalar field named name in this scope.

Parameters:: name (str) – The durable field name.
Returns:: A query value representing that field.
Return type:: QueryField

scope(name)[source]¶

Return the correlated child or reference scope named name.

Parameters:: name (str) – The durable relationship name.
Returns:: A distinct correlated peer scope.
Return type:: QueryScope

class httk.core.storage.stored_properties.QueryContext[source]¶

Bases: QueryScope, Protocol

Factory and algebra used by domain-owned property query callbacks.

field and scope start at the backing record. scope can be called again on a child/reference scope, so callbacks can express correlated nested predicates without seeing storage tables or joins. exact_equal requests equality in the property’s exact stored domain; it is the operation to use for fractions and other values for which a presentation float would be lossy.

constant(value)[source]¶

Return a query value for an already validated literal constant.

Parameters:: value (object) – The validated literal to place in the query.
Returns:: A query value for the literal.
Return type:: QueryValue

null()[source]¶

Return the explicit null query value.

Returns:: A query value representing null.
Return type:: QueryValue

always_true()[source]¶

Return the predicate which matches every backing record.

Returns:: A predicate that always matches.
Return type:: QueryExpression

always_false()[source]¶

Return the predicate which matches no backing record.

Returns:: A predicate that never matches.
Return type:: QueryExpression

compare(left, operator, right)[source]¶

Compare values with a backend-supported comparison operator.

Domain callbacks normally use equal(), exact_equal(), or explicit operator dispatch for a protocol’s filter grammar. The operator is deliberately a string so this contract does not own an external query language’s token enum.

Parameters:

left (QueryValue) – The left query value.
operator (str) – The backend-supported comparison operator.
right (QueryValue) – The right query value.

Returns:

The comparison predicate.

Return type:

QueryExpression

equal(left, right)[source]¶

Compare values using the backing’s ordinary stored semantics.

Parameters:

left (QueryValue) – The left query value.
right (QueryValue) – The right query value.

Returns:

The equality predicate.

Return type:

QueryExpression

exact_equal(left, right)[source]¶

Compare values in their exact canonical stored representation.

Parameters:

left (QueryValue) – The left query value.
right (QueryValue) – The right query value.

Returns:

The exact equality predicate.

Return type:

QueryExpression

is_null(value)[source]¶

Test a value for null; invert this predicate for a known-value test.

Parameters:: value (QueryValue) – The query value to test.
Returns:: The null-test predicate.
Return type:: QueryExpression

exists(scope, predicate)[source]¶

Test whether a correlated scope contains a row satisfying predicate.

Parameters:

scope (QueryScope) – The correlated scope to inspect.
predicate (QueryExpression) – The predicate required of a matching row.

Returns:

The existence predicate.

Return type:

QueryExpression

filtered(scope, predicate)[source]¶

Return the correlated subset of scope satisfying predicate.

The returned scope is usable by aggregate operations. In particular, it lets a declaration compare a required multiplicity with the exact number of matching child values rather than reusing one exists witness for repeated values.

Parameters:

scope (QueryScope) – The correlated scope to filter.
predicate (QueryExpression) – The predicate required of retained rows.

Returns:

A correlated scope containing only matching rows.

Return type:

QueryScope

count(scope)[source]¶

Return the number of rows in a correlated child/reference scope.

Parameters:: scope (QueryScope) – The correlated scope to count.
Returns:: A query value containing the row count.
Return type:: QueryValue

distinct_count(scope, value)[source]¶

Return the count of distinct value values in scope.

Parameters:

scope (QueryScope) – The correlated scope to count.
value (QueryValue) – The value whose distinct occurrences are counted.

Returns:

A query value containing the distinct count.

Return type:

QueryValue

scaled_exact_equal(left, left_factor, right, right_factor)[source]¶

Compare two exact values after cross multiplication.

This is the portable, exact form of a proportional comparison. It avoids requiring a backend to divide fractions or approximate a ratio through a presentation float: it asserts left * left_factor == right * right_factor in the backing’s canonical exact domain.

Parameters:

left (QueryValue) – The first exact value.
left_factor (QueryValue) – The factor applied to the first value.
right (QueryValue) – The second exact value.
right_factor (QueryValue) – The factor applied to the second value.

Returns:

The cross-multiplied equality predicate.

Return type:

QueryExpression

and_(*predicates)[source]¶

Conjoin predicates; an empty conjunction is always_true().

Parameters:: *predicates (QueryExpression) – The predicates to conjoin.
Returns:: The conjunction predicate.
Return type:: QueryExpression

or_(*predicates)[source]¶

Disjoin predicates; an empty disjunction is always_false().

Parameters:: *predicates (QueryExpression) – The predicates to disjoin.
Returns:: The disjunction predicate.
Return type:: QueryExpression

not_(predicate)[source]¶

Negate a predicate without relying on a backend’s Python truthiness.

Parameters:: predicate (QueryExpression) – The predicate to negate.
Returns:: The negated predicate.
Return type:: QueryExpression

when_known(known, predicate)[source]¶

Evaluate predicate only when known is true, else return unknown.

This is the backend-neutral three-valued-logic form of CASE WHEN known THEN predicate ELSE NULL END. It keeps incomplete nullable domain data unknown under both a predicate and its negation instead of silently treating the missing representation as a non-match.

Parameters:

known (QueryExpression) – The predicate establishing that the value is available.
predicate (QueryExpression) – The predicate evaluated only when known matches.

Returns:

The conditional three-valued predicate.

Return type:

QueryExpression

type httk.core.storage.stored_properties.StoredPropertyResponse = Callable[[object], object]¶: Extract one served property value from one concrete backing record.

type httk.core.storage.stored_properties.StoredPropertyQuery = Callable[[QueryContext, str, object], QueryExpression]¶: Build one predicate from a context, protocol operator, and parsed literal.

type httk.core.storage.stored_properties.StoredPropertySort = Callable[[QueryContext], QueryValue]¶: Select one sortable backing value from a query context.

class httk.core.storage.stored_properties.StoredPropertyProjection[source]¶

One domain-owned projection of a served property for one backing.

response is called with a concrete backing record and returns its protocol-boundary value. query receives a backend-neutral context, the protocol comparison operator, and its parsed literal; it returns a predicate or raises QueryLiteralError when the literal has no valid representation for this property. None means that a property is response-only for this backing. sort identifies a direct sortable value and is intentionally separate from filtering because not every predicate has a meaningful total ordering.

Parameters:

response – The operation that extracts the served value from a backing record.
query – The optional operation that builds filtering predicates.
sort – The optional operation that selects a value for ordering.

Raises:

TypeError – If a supplied projection operation cannot be invoked.

response: StoredPropertyResponse¶

query: StoredPropertyQuery | None = None¶

sort: StoredPropertySort | None = None¶

httk.core.storage.stored_properties.stored_property_projections(cls)[source]¶

Return a validated property’s projection map declared on cls.

The lookup deliberately uses vars() rather than getattr(). A representation-specific property mapping must be opted into by the exact backing class; subclasses never inherit a parent’s mapping by accident. A class without the declaration serves no stored properties.

Parameters:

cls (type[Any]) – The exact frozen dataclass backing class to inspect.

Returns:

Its validated projection map, or an empty map when undeclared.

Raises:

TypeError – If cls is not a directly declared frozen dataclass or its map is invalid.
ValueError – If a projection name is invalid.

Return type:

collections.abc.Mapping[str, StoredPropertyProjection]