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>, by=<lookup>)', dimension_kwargs=('over',), lookup_kwargs=('by',), at_most_one_of=('over', 'by')), 'at': Builtin('at(<expr>, by=<lookup>)', lookup_kwargs=('by',)), 'sum_back': Builtin("sum_back(<expr>, over=<dim>, within=<n|parameter>[, edge='wrap'][, by=<lookup>])", dimension_kwargs=('over',), lookup_kwargs=('by',), required_value_kwargs=('within',), edge_kwargs=('edge',), optional_kwargs=('by',)), 'shift': Builtin("shift(<expr>, over=<dim>, offset=<n>[, edge='wrap'|<number>][, by=<lookup>])", dimension_kwargs=('over',), lookup_kwargs=('by',), required_value_kwargs=('offset',), edge_kwargs=('edge',), optional_kwargs=('by',))} module-attribute

BUILTIN_NAMES = frozenset(BUILTINS) module-attribute

EDGE_WRAP = 'wrap' module-attribute

Builtin(usage, dimension_kwargs=(), lookup_kwargs=(), at_most_one_of=(), edge_kwargs=(), required_value_kwargs=(), optional_kwargs=()) dataclass

The call shape of one built-in operator.

Keyword arguments come in four kinds, and the kind decides what resolution turns the value into: dimension_kwargs name a dimension (sum(x, over=generator)); lookup_kwargs name a lookup, which carries its own dimensions, so it needs no sibling kwarg; 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 lookup 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.

at_most_one_of = () class-attribute instance-attribute

dimension_kwargs = () class-attribute instance-attribute

edge_kwargs = () class-attribute instance-attribute

lookup_kwargs = () class-attribute instance-attribute

optional_kwargs = () class-attribute instance-attribute

required property

Every keyword the call must carry.

required_value_kwargs = () class-attribute instance-attribute

usage instance-attribute

kind_of(kwarg)

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

Source code in src/math_spec/operators.py

def kind_of(self, kwarg: str) -> Literal['dimension', 'lookup', 'edge', 'value']:
    """What resolution turns the value of *kwarg* into: a dimension, a lookup, an edge policy, or a plain value."""
    if kwarg in self.dimension_kwargs:
        return 'dimension'
    if kwarg in self.lookup_kwargs:
        return 'lookup'
    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

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)
    if len(keys & set(builtin.at_most_one_of)) > 1:
        alternatives = ' or '.join(f'{k}=' for k in builtin.at_most_one_of)
        return (
            f'{name}() takes at most one of {alternatives} — a lookup carries '
            f'its own dimensions, so by= leaves over= nothing to add.\n'
            f'Write: {builtin.usage}'
        )
    optional = {*builtin.edge_kwargs, *builtin.at_most_one_of, *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

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

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.'
    )