Skip to main content

operators

The operator vocabulary a criteria-matching filter compares with.

OPERATOR_SPECS is the single source of truth: one row per operator, carrying everything the rest of the codebase used to restate in a separate map — how it is spelled in a task config, which function evaluates it, which evidence token it is recorded under, its logical opposite, and the column dtypes it is legal for. Every other structure in this module is derived from it, so adding an operator means adding one row.

Two things cannot be derived and stay hand-spelled:

  • _FilterOperatorTypes here, and ColumnCriterion.op in criteria_matching_types — a Literal cannot be built from a table at type-check time. tests/bitfount/steps/test_operator_vocabulary.py asserts each against the table, so the duplication cannot drift silently.
  • OUTPUT_ONLY_OPERATORS — see its comment for why it is declared rather than inferred from the absence of a spec.

The two config surfaces are deliberately different widths: a ColumnFilter accepts every alias (symbols and English spellings both), while a generic column_criteria entry accepts only the symbols.

Classes​

CriterionOperator​

class CriterionOperator(*args, **kwds):

The comparison an applied bound contributed, in evidence vocabulary.

A closed set. Every ColumnFilter operator alias (>, greater than, !=, not equal, ...) is normalised into one of these before it is recorded in a criterion's config_fields, so a consumer reads one token per comparison rather than the whole alias surface. IN/NIN are the membership operators, whose operand is a list of values.

StrEnum, so a member is its own JSON representation: it binds as a plain string dict key when the evidence is serialised, and reads back comparable.

Ancestors​

Variables​

  • static CODE_MATCH
  • static EQ
  • static GT
  • static GTE
  • static IN
  • static LT
  • static LTE
  • static NE
  • static NIN

OperatorSpec​

class OperatorSpec(    symbol: ForwardRef('str'),    evidence_token: ForwardRef(''codeBlockAnchor[CriterionOperator](/api/bitfount/steps/types/operators#criterionoperator)''),    legal_dtypes: ForwardRef('frozenset[str]'),    aliases: ForwardRef('tuple[str, ...]') = (),    apply: ForwardRef('Callable[[Any, Any], Any] | None') = None,    opposite_symbol: ForwardRef('str | None') = None,):

One operator, and everything the codebase needs to know about it.

Attributes

  • symbol: The canonical spelling, and the only one a generic column_criteria entry may write.
  • evidence_token: The CriterionOperator this comparison is recorded under in a criterion's config_fields.
  • legal_dtypes: The catalogued column dtypes the operator may be applied to. Inverted into ALLOWED_OPS_BY_DTYPE.
  • aliases: Additional spellings a ColumnFilter accepts. English equivalents kept for the task-config surface; not accepted by ColumnCriterion.op.
  • apply: The function evaluating column apply value, or None for a membership operator — those are evaluated by ColumnFilter's .isin branch rather than a scalar callable, which is what is_membership tests for.
  • opposite_symbol: The operator negating this one, used to phrase an exclusion reason. None for the membership operators: in/not in are each other's opposite in principle, but no caller asks for one, and inventing the entry would silently widen _OperatorOppositeMapping beyond the scalar comparisons its two call sites handle.

Variables​

  • aliases : tuple[str, ...] - Alias for field number 3
  • is_membership : bool - Whether the operator tests membership rather than comparing scalars.
  • legal_dtypes : frozenset[str] - Alias for field number 2
  • opposite_symbol : str | None - Alias for field number 5
  • spellings : tuple[str, ...] - Every string a ColumnFilter accepts for this operator.
  • symbol : str - Alias for field number 0