Skip to content

math_spec.operators

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

Closed: there is no Python registry, so every consumer accepts exactly the same language. Compositions belong in macros:; math the language cannot say belongs in a declared escape: island (#38), not in an operator that reads like a built-in.

The language side of an operator — its name and signature, nothing else. The signature lives here because more than one pass needs it (resolution types the dimension arguments, validation name-checks macro bodies, a consumer builds the call), and an arity spelled out once per pass is one the passes can disagree about. Dependency-free on purpose: counts and keyword names, no AST.

BUILTINS = {'sum': Builtin(1, '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(1, 'at(<expr>, by=<lookup>)', lookup_kwargs=('by',)), 'sum_back': Builtin(1, "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(1, "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(positional, 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 dimension or lookup an operator 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 #

keywords property #

Every keyword the call must carry, when they are named at all.

lookup_kwargs = () class-attribute instance-attribute #

optional property #

Every keyword the call may carry but need not.

optional_kwargs = () class-attribute instance-attribute #

positional instance-attribute #

required_value_kwargs = () class-attribute instance-attribute #

usage instance-attribute #

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 
133
134
135
136
137
138
139
140
141
142
143
144
145
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}'
        )
    fits = positional == builtin.positional and keys - builtin.optional == builtin.keywords
    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 
123
124
125
126
127
128
129
130
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 
148
149
150
151
152
153
154
155
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.'
    )