math_spec.resolution

Name resolution — the pass that makes the core AST fully typed.

Parsers emit unresolved names; this module rewrites each into the typed node its kind asks for, so the AST reaching a consumer holds none. The rules live in the language reference.

DeclarationKind = Literal['variable', 'parameter', 'dimension', 'lookup'] module-attribute

Namespace(variables, parameters, dimensions, lookups, dtypes, leaf_dims)

The declared names of one schema, by kind.

A name has one kind: model.py refuses one declared under two sections.

Source code in src/math_spec/resolution.py

def __init__(
    self,
    variables: Iterable[str],
    parameters: Iterable[str],
    dimensions: Iterable[str],
    lookups: Mapping[str, tuple[str, str | None]],
    dtypes: Mapping[str, DeclaredDtype],
    leaf_dims: Mapping[str, tuple[str, ...]],
) -> None:
    self.variables = frozenset(variables)
    self.parameters = frozenset(parameters)
    self.dimensions = frozenset(dimensions)
    #: name -> declared dtype, for dimensions, parameters and lookups alike;
    #: what a where comparison checks its literal against.
    self.dtypes: dict[str, DeclaredDtype] = dict(dtypes)
    #: lookup name -> ``(over, into)``; ``into`` is ``None`` for a label
    #: space, which owns its values.
    self.lookups: dict[str, tuple[str, str | None]] = dict(lookups)
    #: parameter or variable name -> the dims it is read through —
    #: parameters by their ``dims``, variables by their frame. Stamped onto
    #: each leaf a where names, the way a lookup leaf carries ``over``.
    self.leaf_dims: dict[str, tuple[str, ...]] = dict(leaf_dims)

dimensions = frozenset(dimensions) instance-attribute

dtypes = dict(dtypes) instance-attribute

leaf_dims = dict(leaf_dims) instance-attribute

lookups = dict(lookups) instance-attribute

parameters = frozenset(parameters) instance-attribute

variables = frozenset(variables) instance-attribute

groupable()

The lookups a by= may name: name -> the dimension it maps into.

A label space is absent, which is what makes naming one in a by= answerable with the promotion rewrite rather than "no such lookup".

Source code in src/math_spec/resolution.py

def groupable(self) -> dict[str, str]:
    """The lookups a ``by=`` may name: name -> the dimension it maps into.

    A label space is absent, which is what makes naming one in a ``by=``
    answerable with the promotion rewrite rather than "no such lookup".
    """
    return {n: into for n, (_, into) in self.lookups.items() if into is not None}

into_of(lookup)

The dimension lookup's values are labels of, None for a label space.

Source code in src/math_spec/resolution.py

def into_of(self, lookup: str) -> str | None:
    """The dimension *lookup*'s values are labels of, ``None`` for a label space."""
    return self.lookups[lookup][1]

kind(name)

What name was declared as, or None where the file declares it nowhere.

Source code in src/math_spec/resolution.py

def kind(self, name: str) -> DeclarationKind | None:
    """What *name* was declared as, or ``None`` where the file declares it nowhere."""
    if name in self.variables:
        return 'variable'
    if name in self.parameters:
        return 'parameter'
    if name in self.dimensions:
        return 'dimension'
    if name in self.lookups:
        return 'lookup'
    return None

of(schema) classmethod

Build the namespace of schema, the whole of what a file may name.

A targeted lookup's values are labels of its target, so its dtype is the target's.

Source code in src/math_spec/resolution.py

@classmethod
def of(cls, schema: Spec) -> Namespace:
    """Build the namespace of *schema*, the whole of what a file may name.

    A targeted lookup's values are labels of its target, so its dtype is
    the target's.
    """
    return cls(
        schema.variables,
        schema.parameters,
        schema.dimensions,
        {n: (lk.over, lk.into) for n, lk in schema.lookups.items()},
        {
            **{p: pd.dtype for p, pd in schema.parameters.items()},
            **{d: dd.dtype for d, dd in schema.dimensions.items()},
            **{n: schema.dimensions[lk.into].dtype for n, lk in schema.lookups.items() if lk.into is not None},
            **{n: lk.dtype for n, lk in schema.lookups.items() if lk.dtype is not None},
        },
        {
            **{p: tuple(pd.dims) for p, pd in schema.parameters.items()},
            **{v: tuple(vd.foreach) for v, vd in schema.variables.items()},
        },
    )

over_of(lookup)

The dimension lookup maps out of, whichever kind it is.

Source code in src/math_spec/resolution.py

def over_of(self, lookup: str) -> str:
    """The dimension *lookup* maps out of, whichever kind it is."""
    return self.lookups[lookup][0]

unknown(name, context, *, allow_dims, formals=())

The refusal for a name declared nowhere, listing what it could have been.

PARAMETER	DESCRIPTION
name	The name the file wrote. TYPE: str
context	The declaration it was found in. TYPE: str
allow_dims	Whether a dimension would have been accepted there. TYPE: bool
formals	A macro's formals, listed first when there are any. TYPE: Iterable[str] DEFAULT: ()

Source code in src/math_spec/resolution.py

def unknown(self, name: str, context: str, *, allow_dims: bool, formals: Iterable[str] = ()) -> str:
    """The refusal for a *name* declared nowhere, listing what it could have been.

    Args:
        name: The name the file wrote.
        context: The declaration it was found in.
        allow_dims: Whether a dimension would have been accepted there.
        formals: A macro's formals, listed first when there are any.
    """
    shown: list[tuple[str, Iterable[str]]] = [('Formals', formals)] if formals else []
    shown += (
        [('Parameters', self.parameters), ('Dimensions', self.dimensions)]
        if allow_dims
        else [('Variables', self.variables), ('Parameters', self.parameters)]
    )
    listing = '\n'.join(f'  {kind}: {sorted(names)}' for kind, names in shown)
    return f"{context}: '{name}' not found.\n{listing}\nCheck for typos, or ensure '{name}' is declared."

expression_of(text, schema, ns, context)

Parse, expand and resolve text — the only way a consumer gets an AST.

RAISES	DESCRIPTION
LanguageError	Listing every problem the text has.

Source code in src/math_spec/resolution.py

def expression_of(text: str, schema: Spec, ns: Namespace, context: str) -> ParsedNode:
    """Parse, expand and resolve *text* — the only way a consumer gets an AST.

    Raises:
        LanguageError: Listing every problem the text has.
    """
    errors: list[str] = []
    resolved = resolve_expression(parse_and_expand(text, schema, context), ns, context, errors)
    if errors:
        raise LanguageError('\n'.join(errors))
    assert resolved is not None
    return resolved

resolve_expression(node, ns, context, errors)

Rewrite every NameNode under node to a typed node, checking operator call shapes on the way.

RETURNS	DESCRIPTION
ParsedNode | None	The typed tree, or None once anything failed — appending to
ParsedNode | None	errors rather than raising, so a caller collecting problems across a
ParsedNode | None	whole schema reports them together.

Source code in src/math_spec/resolution.py

def resolve_expression(
    node: ParsedNode,
    ns: Namespace,
    context: str,
    errors: list[str],
) -> ParsedNode | None:
    """Rewrite every ``NameNode`` under *node* to a typed node, checking operator call shapes on the way.

    Returns:
        The typed tree, or ``None`` once anything failed — appending to
        *errors* rather than raising, so a caller collecting problems across a
        whole schema reports them together.
    """
    before = len(errors)
    resolved = _Resolver(ns, context, errors).expression(node)
    return None if len(errors) > before else resolved

resolve_where(node, ns, context, errors, self_variable=None)

Rewrite a parsed where AST into typed predicates, folded as :class:~math_spec.program.Mask folds.

RETURNS	DESCRIPTION
WhereNode | None	The typed tree — a mask admitting every row or none comes back as the
WhereNode | None	one BooleanLiteralNode — or None once anything failed, with the
WhereNode | None	problems appended to errors.

Source code in src/math_spec/resolution.py

def resolve_where(
    node: WhereNode | UnresolvedWhereNode,
    ns: Namespace,
    context: str,
    errors: list[str],
    self_variable: str | None = None,
) -> WhereNode | None:
    """Rewrite a parsed where AST into typed predicates, folded as :class:`~math_spec.program.Mask` folds.

    Returns:
        The typed tree — a mask admitting every row or none comes back as the
        one ``BooleanLiteralNode`` — or ``None`` once anything failed, with the
        problems appended to *errors*.
    """
    before = len(errors)
    resolved = _Resolver(ns, context, errors, self_variable).where(node)
    return None if len(errors) > before else Mask(cast('WhereNode', resolved)).root

resolve_where_text(text, ns, context, errors, self_variable=None)

Parse and resolve one where string as :func:resolve_where does, a parse failure appended to errors.

RETURNS	DESCRIPTION
WhereNode | None	None where there is no mask to read, and where reading it failed.

Source code in src/math_spec/resolution.py

def resolve_where_text(
    text: str | None,
    ns: Namespace,
    context: str,
    errors: list[str],
    self_variable: str | None = None,
) -> WhereNode | None:
    """Parse and resolve one where string as :func:`resolve_where` does, a parse failure appended to *errors*.

    Returns:
        ``None`` where there is no mask to read, and where reading it failed.
    """
    if text is None:
        return None
    try:
        node = parse_where(text)
    except ValueError as e:
        errors.append(f'{context}: {e}')
        return None
    return resolve_where(node, ns, context, errors, self_variable)

where_of(text, ns, context, self_variable=None)

Parse and resolve a where string into the :class:~math_spec.program.Mask a declaration carries.

None for no mask, however the file spelled it: a mask that admits every row is dropped, and one that admits none arrives as a mask over BooleanLiteralNode(False).

RAISES	DESCRIPTION
LanguageError	Listing every problem the predicate has.

Source code in src/math_spec/resolution.py

def where_of(text: str | None, ns: Namespace, context: str, self_variable: str | None = None) -> Mask | None:
    """Parse and resolve a where string into the :class:`~math_spec.program.Mask` a declaration carries.

    ``None`` for no mask, however the file spelled it: a mask that admits every
    row is dropped, and one that admits none arrives as a mask over
    ``BooleanLiteralNode(False)``.

    Raises:
        LanguageError: Listing every problem the predicate has.
    """
    errors: list[str] = []
    resolved = resolve_where_text(text, ns, context, errors, self_variable)
    if errors:
        raise LanguageError('\n'.join(errors))
    if resolved is None or (isinstance(resolved, BooleanLiteralNode) and resolved.value):
        return None
    return Mask(resolved)