httk.serve.optimade.backend.handlers

Re-exports of the generic OPTIMADE filter handlers.

The handler tables and generic handlers are implemented in httk.store.query.optimade_filters and exposed here under the httk.serve.optimade.backend.handlers namespace.

The handlers raise FilterTranslationError (which carries a neutral failure category instead of HTTP semantics); translate_filter() wraps it into TranslatorError with the appropriate HTTP status. simple_property_handlers() takes a plain property-name -> fulltype mapping as its third argument. A 'HAS' handler is called as handler(property, ops, values, search_variable, has_type) and returns a plain SearchExpression; the caller applies NOT as ~, and the backend determines whether the resulting expression also needs post-filter evaluation.

Attributes

HandlerTable

Per-property translation callables, keyed by property name.

invert_op

Comparison operators after swapping a constant from left to right.

Functions

constant_comparison_handler(val1, op, val2, ...)

Fold val1 <op> val2 (both constants) to a constant expression.

constant_set_handler(val1, ops, val2, has_type, ...)

Fold a HAS-family operation over two constant sets.

constant_stringmatching_handler(val1, val2, ...)

Fold val1 <CONTAINS|STARTS|ENDS> val2 (both constants) to a constant expression.

false_handler(search_variable)

Build a constant-false expression over search_variable.

known_unknown_handler(entry, search_variable, unknown_type)

Translate known-value tests for a property with known nullability.

number_handler(entry, op, value, search_variable)

Translate a numeric comparison onto a backend field.

set_handler(entry, ops, values, has_type, search_variable)

Translate one HAS family node over the list-valued field entry.

simple_property_handlers(entry_type, property_keys, ...)

Build a filter handler table for an entry type from a property-key map.

string_handler(entry, op, value, search_variable)

Translate a scalar comparison onto a backend field.

stringmatching_handler(entry, value, ...)

Translate CONTAINS/STARTS/ENDS onto the field's literal matchers.

timestamp_handler(entry, op, value, search_variable)

Normalize an RFC 3339 timestamp and translate its comparison.

true_handler(search_variable)

Build a constant-true expression over search_variable.

unknown_comparison_handler(entry, ops, values, ...)

Build a false expression for comparison on an unknown property.

unknown_has_handler(entry, op, value, search_variable, ...)

Build a false expression for set filtering on an unknown property.

unknown_length_handler(entry, op, value, search_variable)

Build a false expression for length filtering on an unknown property.

unknown_stringmatching_handler(entry, values, ...)

Build a false expression for string matching on an unknown property.

unknown_unknown_handler(entry, search_variable, ...)

Translate unknown-value tests for an unrecognized property.

Module Contents

type httk.serve.optimade.backend.handlers.HandlerTable = Mapping[str, Mapping[str, Callable[..., Any]]]

Per-property translation callables, keyed by property name.

The inner mapping’s keys name the filter-operation families: 'comparison' (=, !=, <, <=, >, >=), 'stringmatching' (CONTAINS/STARTS/ENDS), 'HAS' (the set operations), 'length' (LENGTH), and 'unknown' (IS KNOWN/IS UNKNOWN). A 'HAS' handler is called as handler(property, ops, values, search_variable, has_type) and returns a plain SearchExpression. The caller applies NOT as ~; handlers do not receive negation state or report post-filter placement. Dotted '<type>.id' entries provide relationship-id filtering (see relationship_id_handler()).

httk.serve.optimade.backend.handlers.constant_comparison_handler(val1, op, val2, search_variable)

Fold val1 <op> val2 (both constants) to a constant expression.

val1 is the value being compared and val2 the filter constant, the same left-to-right convention as constant_set_handler(); translate_filter_ast() has already inverted op for constant-on-the-left filters, so this ordering is the filter’s own.

Parameters:

  • val1 (Any) – The value being compared.

  • op (str) – The comparison operator.

  • val2 (Any) – The filter constant.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

A constant expression representing the comparison result.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.constant_set_handler(val1, ops, val2, has_type, search_variable)

Fold a HAS-family operation over two constant sets.

Parameters:

  • val1 (Any) – The list value being tested.

  • ops (Any) – The parsed set comparison operators.

  • val2 (Any) – The filter values.

  • has_type (str) – The HAS-family operator.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

A constant expression representing the set result.

Raises:

FilterTranslationError – If has_type is not supported.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.constant_stringmatching_handler(val1, val2, stringmatching_type, search_variable)

Fold val1 <CONTAINS|STARTS|ENDS> val2 (both constants) to a constant expression.

val1 is the value being matched and val2 the filter text, the same left-to-right convention as constant_set_handler().

Parameters:

  • val1 (Any) – The value being matched.

  • val2 (Any) – The filter text.

  • stringmatching_type (str) – The CONTAINS, STARTS, or ENDS operator.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

A constant expression representing the match result.

Raises:

FilterTranslationError – If stringmatching_type is not supported.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.false_handler(search_variable)

Build a constant-false expression over search_variable.

Parameters:

search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

An expression that matches no row.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.invert_op

Comparison operators after swapping a constant from left to right.

httk.serve.optimade.backend.handlers.known_unknown_handler(entry, search_variable, unknown_type)

Translate known-value tests for a property with known nullability.

Parameters:

  • entry (str) – The property name, retained for handler compatibility.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

  • unknown_type (str) – The IS_KNOWN or IS_UNKNOWN operator.

Returns:

The corresponding constant expression.

Raises:

FilterTranslationError – If unknown_type is not supported.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.number_handler(entry, op, value, search_variable)

Translate a numeric comparison onto a backend field.

Parameters:

  • entry (str) – The backend field name.

  • op (str) – The comparison operator.

  • value (Any) – The converted numeric filter value.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

The field comparison expression.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.set_handler(entry, ops, values, has_type, search_variable)

Translate one HAS family node over the list-valued field entry.

HAS ALL becomes a conjunction of one-value has_any calls (each constraining an independently joined child row); HAS ANY and HAS ONLY map straight onto has_any/has_only. Negation is not the handler’s business: a surrounding NOT inverts the returned expression, and the backend’s ~ knows how to negate a set predicate.

Parameters:

  • entry (str) – The backend list-valued field name.

  • ops (Any) – The parsed set comparison operators.

  • values (Any) – The converted set values.

  • has_type (str) – The HAS-family operator.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

The list-membership expression.

Raises:

FilterTranslationError – If has_type is not supported.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.simple_property_handlers(entry_type, property_keys, property_fulltypes)

Build a filter handler table for an entry type from a property-key map.

Provides default handlers for standard id (matched against the ID_FIELD field) and type (a constant equal to entry_type). Entries in property_keys replace those defaults when their names overlap. For every property named in property_keys (which maps property names to backend field names), handlers are generated from the property’s fulltype in property_fulltypes (default "string"): string properties get comparison and stringmatching handlers; integer and float properties get a numeric comparison handler; list of ... properties get a HAS (set membership) handler. Every generated property also gets a known unknown handler.

Parameters:
Returns:

A handler table keyed by served property name.

Return type:

dict[str, collections.abc.Mapping[str, collections.abc.Callable[Ellipsis, Any]]]

httk.serve.optimade.backend.handlers.string_handler(entry, op, value, search_variable)

Translate a scalar comparison onto a backend field.

Parameters:

  • entry (str) – The backend field name.

  • op (str) – The comparison operator.

  • value (Any) – The converted filter value.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

The field comparison expression.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.stringmatching_handler(entry, value, stringmatching_type, search_variable)

Translate CONTAINS/STARTS/ENDS onto the field’s literal matchers.

The filter constant is passed through unescaped: the search-field protocol’s contains/startswith/endswith take literal text, so % and _ match themselves (as OPTIMADE requires). Any escaping a backend’s pattern language needs is that backend’s own business.

Parameters:

  • entry (str) – The backend field name.

  • value (str) – The literal filter text.

  • stringmatching_type (str) – The CONTAINS, STARTS, or ENDS operator.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

The literal string-matching expression.

Raises:

FilterTranslationError – If stringmatching_type is not supported.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.timestamp_handler(entry, op, value, search_variable)

Normalize an RFC 3339 timestamp and translate its comparison.

Parameters:

  • entry (str) – The backend field name.

  • op (str) – The comparison operator.

  • value (Any) – The RFC 3339 timestamp filter value.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

The normalized timestamp comparison expression.

Raises:

FilterTranslationError – If value is not an offset-aware RFC 3339 timestamp.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.true_handler(search_variable)

Build a constant-true expression over search_variable.

Parameters:

search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

An expression that matches every row.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.unknown_comparison_handler(entry, ops, values, search_variable)

Build a false expression for comparison on an unknown property.

Parameters:

  • entry (str) – The unknown property name.

  • ops (Any) – The parsed comparison operators.

  • values (Any) – The parsed comparison values.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

An expression that matches no row.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.unknown_has_handler(entry, op, value, search_variable, has_type)

Build a false expression for set filtering on an unknown property.

Parameters:

  • entry (str) – The unknown property name.

  • op (Any) – The parsed set operators.

  • value (Any) – The parsed set values.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

  • has_type (str) – The parsed HAS-family operator.

Returns:

An expression that matches no row.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.unknown_length_handler(entry, op, value, search_variable)

Build a false expression for length filtering on an unknown property.

Parameters:

  • entry (str) – The unknown property name.

  • op (str) – The parsed length comparison operator.

  • value (Any) – The parsed length value.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

An expression that matches no row.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.unknown_stringmatching_handler(entry, values, stringmatching_type, search_variable)

Build a false expression for string matching on an unknown property.

Parameters:

  • entry (str) – The unknown property name.

  • values (Any) – The parsed match value.

  • stringmatching_type (str) – The parsed string-matching operator.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

Returns:

An expression that matches no row.

Return type:

httk.store.query.SearchExpression

httk.serve.optimade.backend.handlers.unknown_unknown_handler(entry, search_variable, unknown_type)

Translate unknown-value tests for an unrecognized property.

Parameters:

  • entry (str) – The property name, retained for handler compatibility.

  • search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.

  • unknown_type (str) – The IS_KNOWN or IS_UNKNOWN operator.

Returns:

The corresponding constant expression.

Raises:

FilterTranslationError – If unknown_type is not supported.

Return type:

httk.store.query.SearchExpression