Skip to content

math_spec.operators

The closed set of built-in operators and their call shapes.

One home for each signature: a composition is a macro, and math the language cannot say is a declared escape:.

BUILTINS = {'sum': Builtin('sum(<expr>), sum(<expr>, over=<dim>) or sum(<expr>[, over=<relation>.<key column>][, by=<relation>[.<value column>]])', dimension_kwargs=('over',), relation_kwargs=('by',), optional_kwargs=('by', 'over')), 'at': Builtin('at(<expr>, by=<relation>[.<value column>])', relation_kwargs=('by',)), 'sum_back': Builtin("sum_back(<expr>, along=<dim>|<relation>.<key column>, window=<n|parameter>[, edge='wrap'][, within=<column>])", dimension_kwargs=('along',), role_kwargs=('within',), required_value_kwargs=('window',), edge_kwargs=('edge',), optional_kwargs=('within',)), 'shift': Builtin("shift(<expr>, along=<dim>|<relation>.<key column>, offset=<n>[, edge='wrap'|<number>][, within=<column>])", dimension_kwargs=('along',), role_kwargs=('within',), required_value_kwargs=('offset',), edge_kwargs=('edge',), optional_kwargs=('within',)), 'dual': Builtin('dual(<constraint>)')} module-attribute #

BUILTIN_NAMES = frozenset(BUILTINS) module-attribute #

EDGE_WRAP = 'wrap' module-attribute #

Builtin(usage, dimension_kwargs=(), relation_kwargs=(), role_kwargs=(), edge_kwargs=(), required_value_kwargs=(), optional_kwargs=()) dataclass #

The call shape of one built-in operator.

Keyword arguments come in five kinds, and the kind decides what resolution turns the value into: dimension_kwargs name a dimension, or a key column of a relation written after a dot (sum(x, over=generator), sum(x, over=zone_of.generator)); relation_kwargs name a relation, bare or with value columns after a dot (by=gen_bus, by=ends.bus1); role_kwargs name columns of the relation another kwarg names (within=week); edge_kwargs take a closed keyword or a number; required_value_kwargs are ordinary values that must be present — a number, never a name to resolve (shift(..., offset=1)).

Every operator takes one positional argument, the expression; every dimension or relation it names arrives in a kwarg value, which is what lets a macro pass one as a formal. usage is the wording every refusal quotes back.

dimension_kwargs = () class-attribute instance-attribute #

edge_kwargs = () class-attribute instance-attribute #

optional_kwargs = () class-attribute instance-attribute #

relation_kwargs = () class-attribute instance-attribute #

required property #

Every keyword the call must carry.

required_value_kwargs = () class-attribute instance-attribute #

role_kwargs = () class-attribute instance-attribute #

usage instance-attribute #

kind_of(kwarg) #

What resolution turns the value of kwarg into: a dimension, a relation, a column of one, an edge policy, or a plain value.

Source code in src/math_spec/operators.py 
57
58
59
60
61
62
63
64
65
66
67
def kind_of(self, kwarg: str) -> Literal['dimension', 'relation', 'role', 'edge', 'value']:
    """What resolution turns the value of *kwarg* into: a dimension, a relation, a column of one, an edge policy, or a plain value."""
    if kwarg in self.dimension_kwargs:
        return 'dimension'
    if kwarg in self.relation_kwargs:
        return 'relation'
    if kwarg in self.role_kwargs:
        return 'role'
    if kwarg in self.edge_kwargs:
        return 'edge'
    return 'value'

call_shape_error(name, positional, kwargs) #

Why a call to name does not fit its signature; None if it fits.

Source code in src/math_spec/operators.py 
124
125
126
127
128
129
130
def call_shape_error(name: str, positional: int, kwargs: Iterable[str]) -> str | None:
    """Why a call to *name* does not fit its signature; ``None`` if it fits."""
    builtin = BUILTINS[name]
    keys = set(kwargs)
    optional = {*builtin.edge_kwargs, *builtin.optional_kwargs}
    fits = positional == 1 and keys - optional == builtin.required
    return None if fits else f'{name}() expects {builtin.usage}'

edge_error(name, given) #

Why an edge= value is not one the language has.

Source code in src/math_spec/operators.py 
114
115
116
117
118
119
120
121
def edge_error(name: str, given: str) -> str:
    """Why an ``edge=`` value is not one the language has."""
    return (
        f'{name}(edge={given}) is not an edge policy.\n'
        f"Write edge='{EDGE_WRAP}' for a cyclic translation, a number for the "
        f'value the vacated positions contribute, or omit it and they are '
        f'absent — which drops the row.'
    )

unknown_operator_message(name) #

The one wording for "that is not an operator".

Source code in src/math_spec/operators.py 
133
134
135
136
137
138
139
140
def unknown_operator_message(name: str) -> str:
    """The one wording for "that is not an operator"."""
    return (
        f"Unknown operator '{name}'.\n"
        f'Available: {sorted(BUILTIN_NAMES)}\n'
        f"Define '{name}' as a macro under 'macros:' if it composes built-ins; "
        f'if the math is not sayable in the language, use a declared escape.'
    )