mathspec 0.1.0__tar.gz → 0.2.0__tar.gz

{mathspec-0.1.0 → mathspec-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: mathspec
-Version: 0.1.0
-Summary: Write an optimisation model as a YAML file. Check it and print it as math, with no data and no solver.
+Version: 0.2.0
+Summary: Write the specification (spec) of an optimisation model as a YAML file. Check it and print it as math, with no data and no solver.
 Project-URL: Documentation, https://mathspec.readthedocs.io
 Project-URL: Repository, https://github.com/energy-models/mathspec
 Project-URL: Issues, https://github.com/energy-models/mathspec/issues
@@ -40,36 +40,36 @@ SPDX-License-Identifier: CC-BY-4.0
 
 <!--- --8<-- [end:badges] -->
 
-**Write an optimisation model as a YAML file. Check it and print it as math,
-with no data and no solver.**
+**Write the specification (spec) of an optimisation model as a YAML file. Check it and print it
+as math, with no data and no solver.**
 
-A mathspec file declares four things: the axes the model runs over, such as
-`snapshot` and `generator`; the data it expects, such as `load` and `cost`; the
-decisions the solver makes, such as `dispatch`; and the rules those decisions
-obey, such as `sum(dispatch, over=generator) == load`. The file
-[below](#example) is a complete model.
+A mathspec file states a specification, or spec. A spec declares four things: the axes it runs
+over, such as `snapshot` and `generator`; the data it expects, such as `load`
+and `cost`; the decisions the solver makes, such as `dispatch`; and the rules
+those decisions obey, such as `sum(dispatch, over=generator) == load`. The file
+[below](#example) is a complete spec.
 
 <!--- --8<-- [start:engines] -->
 
 mathspec builds nothing and solves nothing itself.
 [specsolve](https://github.com/fluxopt/specsolve) and
-[linopy](https://github.com/PyPSA/linopy) build and solve a mathspec model.
-Support in both is work in progress.
+[linopy](https://github.com/PyPSA/linopy) build a model from a spec and its
+data, and solve it. Support in both is work in progress.
 
 <!--- --8<-- [end:engines] -->
 
 <!--- --8<-- [start:benefits] -->
 
-- **Check models in CI, with no data.** A wrong name or
+- **Check specs in CI, with no data.** A wrong name or
   dimension fails when the file loads, and the error names the fix.
   [Errors →](https://mathspec.readthedocs.io/en/latest/reference/language/errors/)
 - **Publish the math you solve.** The equations in the paper
   print from the file the solver reads.
   [Typeset →](https://mathspec.readthedocs.io/en/latest/reference/typeset/)
-- **One model, many tools.** Engines, renderers and analysers read the model
+- **One spec, many tools.** Engines, renderers and analysers read the spec
   through one public API, so no two of them can read the file differently.
   [Program API →](https://mathspec.readthedocs.io/en/latest/reference/program/)
-- **Write full-size models.** PyPSA's `n.optimize()` model is
+- **Write full-size specs.** The spec of PyPSA's `n.optimize()` model is
   one file, with stochastic, multi-period and quadratic variants.
   [PyPSA in one file →](https://mathspec.readthedocs.io/en/latest/examples/pypsa/)
 
@@ -206,7 +206,7 @@ ms.to_typst(spec)
 
 A [symbol table](https://mathspec.readthedocs.io/en/latest/reference/typeset/#symbol-tables) gives the names their
 conventional spelling, as in the folded block.
-[Print a model as math](https://mathspec.readthedocs.io/en/latest/howto/print/) does the same from a shell.
+[Print a spec as math](https://mathspec.readthedocs.io/en/latest/howto/print/) does the same from a shell.
 
 ## Documentation
 

{mathspec-0.1.0 → mathspec-0.2.0}/README.md

@@ -15,36 +15,36 @@ SPDX-License-Identifier: CC-BY-4.0
 
 <!--- --8<-- [end:badges] -->
 
-**Write an optimisation model as a YAML file. Check it and print it as math,
-with no data and no solver.**
+**Write the specification (spec) of an optimisation model as a YAML file. Check it and print it
+as math, with no data and no solver.**
 
-A mathspec file declares four things: the axes the model runs over, such as
-`snapshot` and `generator`; the data it expects, such as `load` and `cost`; the
-decisions the solver makes, such as `dispatch`; and the rules those decisions
-obey, such as `sum(dispatch, over=generator) == load`. The file
-[below](#example) is a complete model.
+A mathspec file states a specification, or spec. A spec declares four things: the axes it runs
+over, such as `snapshot` and `generator`; the data it expects, such as `load`
+and `cost`; the decisions the solver makes, such as `dispatch`; and the rules
+those decisions obey, such as `sum(dispatch, over=generator) == load`. The file
+[below](#example) is a complete spec.
 
 <!--- --8<-- [start:engines] -->
 
 mathspec builds nothing and solves nothing itself.
 [specsolve](https://github.com/fluxopt/specsolve) and
-[linopy](https://github.com/PyPSA/linopy) build and solve a mathspec model.
-Support in both is work in progress.
+[linopy](https://github.com/PyPSA/linopy) build a model from a spec and its
+data, and solve it. Support in both is work in progress.
 
 <!--- --8<-- [end:engines] -->
 
 <!--- --8<-- [start:benefits] -->
 
-- **Check models in CI, with no data.** A wrong name or
+- **Check specs in CI, with no data.** A wrong name or
   dimension fails when the file loads, and the error names the fix.
   [Errors →](https://mathspec.readthedocs.io/en/latest/reference/language/errors/)
 - **Publish the math you solve.** The equations in the paper
   print from the file the solver reads.
   [Typeset →](https://mathspec.readthedocs.io/en/latest/reference/typeset/)
-- **One model, many tools.** Engines, renderers and analysers read the model
+- **One spec, many tools.** Engines, renderers and analysers read the spec
   through one public API, so no two of them can read the file differently.
   [Program API →](https://mathspec.readthedocs.io/en/latest/reference/program/)
-- **Write full-size models.** PyPSA's `n.optimize()` model is
+- **Write full-size specs.** The spec of PyPSA's `n.optimize()` model is
   one file, with stochastic, multi-period and quadratic variants.
   [PyPSA in one file →](https://mathspec.readthedocs.io/en/latest/examples/pypsa/)
 
@@ -181,7 +181,7 @@ ms.to_typst(spec)
 
 A [symbol table](https://mathspec.readthedocs.io/en/latest/reference/typeset/#symbol-tables) gives the names their
 conventional spelling, as in the folded block.
-[Print a model as math](https://mathspec.readthedocs.io/en/latest/howto/print/) does the same from a shell.
+[Print a spec as math](https://mathspec.readthedocs.io/en/latest/howto/print/) does the same from a shell.
 
 ## Documentation
 

{mathspec-0.1.0 → mathspec-0.2.0}/pyproject.toml

@@ -20,7 +20,7 @@ only-include = ["src", "README.md", "LICENSE", "LICENSES"]
 
 [project]
 name = "mathspec"
-description = "Write an optimisation model as a YAML file. Check it and print it as math, with no data and no solver."
+description = "Write the specification (spec) of an optimisation model as a YAML file. Check it and print it as math, with no data and no solver."
 authors = [
   { name = "Felix Bumann", email = "117816358+FBumann@users.noreply.github.com" },
   { name = "Bryn Pickering", email = "17178478+brynpickering@users.noreply.github.com" },

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/__init__.py

@@ -4,18 +4,18 @@
 
 """The language: what a YAML file may say, and what it means.
 
-Two public states — a :class:`~mathspec.model.Spec` is what the file *says*,
-and its :attr:`~mathspec.model.Spec.program` is what it *means* — and
-:func:`to_spec`, the one door to both. Everything between them — both grammars
+Two public states — a [`Spec`][] is what the file *says*,
+and its [`program`][mathspec.spec.Spec.program] is what it *means* — and
+[`to_spec`][], the one door to both. Everything between them — both grammars
 and the tree they build — is package-private, because a consumer reads a
 program instead.
 """
 
 from mathspec import program
-from mathspec.advice import advice
+from mathspec.advising import advice
 from mathspec.errors import Advice, AdviceKind, DimensionError, LanguageError, MathSpecError, SchemaError, did_you_mean
-from mathspec.model import Spec
 from mathspec.operators import BUILTIN_NAMES
+from mathspec.spec import Spec
 from mathspec.typesetting import (
     FORMATS,
     SymbolTable,

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/__main__.py

@@ -2,13 +2,13 @@
 #
 # SPDX-License-Identifier: MIT
 
-"""``python -m mathspec <verb> model.yaml`` — the shell front.
+"""``python -m mathspec <verb> spec.yaml`` — the shell front.
 
 ``check`` loads the file and prints the language's advice; one further verb
-per typeset format, read off :data:`mathspec.typesetting.FORMATS`. Every verb
+per typeset format, read off [`mathspec.typesetting.FORMATS`][]. Every verb
 reads the file as written, and nothing here writes a formulation out unasked.
 The typeset verbs take ``--expand``, because a shell cannot compose
-:meth:`~mathspec.model.Spec.expand` the way a caller does and the rows are a
+[`expand`][mathspec.spec.Spec.expand] the way a caller does and the rows are a
 different document; ``check`` has no such flag, because advice reads a block
 as the rows it states.
 """
@@ -19,7 +19,7 @@ import argparse
 import sys
 from pathlib import Path
 
-from mathspec.advice import advice
+from mathspec.advising import advice
 from mathspec.errors import MathSpecError
 from mathspec.typesetting import FORMATS, typeset
 from mathspec.validation import to_spec
@@ -30,12 +30,12 @@ def parser() -> argparse.ArgumentParser:
     front = argparse.ArgumentParser(prog='python -m mathspec')
     verbs = front.add_subparsers(dest='verb', required=True)
 
-    check = verbs.add_parser('check', help='load a model, and print what the language advises')
-    check.add_argument('model', help='path to a mathspec YAML model')
+    check = verbs.add_parser('check', help='load a spec, and print what the language advises')
+    check.add_argument('spec', help='path to a mathspec YAML file')
 
     for name in FORMATS:
-        verb = verbs.add_parser(name, help=f'render a model as {name}')
-        verb.add_argument('model', help='path to a mathspec YAML model')
+        verb = verbs.add_parser(name, help=f'render a spec as {name}')
+        verb.add_argument('spec', help='path to a mathspec YAML file')
         verb.add_argument('-o', '--out', help='write here instead of stdout')
         verb.add_argument('--symbols', help='sidecar YAML saying how names should print')
         verb.add_argument('--standalone', action='store_true', help='emit a compilable document')
@@ -60,15 +60,15 @@ def main(argv: list[str] | None = None) -> int:
     args = parser().parse_args(argv)
     if args.verb == 'check':
         try:
-            notes = advice(args.model)
+            notes = advice(args.spec)
         except MathSpecError as e:
             sys.stderr.write(f'{e}\n')
             return 1
         sys.stdout.write(''.join(f'{note}\n' for note in notes))
         return 0
-    model = to_spec(args.model).expand() if args.expand else args.model
+    spec = to_spec(args.spec).expand() if args.expand else args.spec
     text = typeset(
-        model,
+        spec,
         args.verb,
         symbols=args.symbols,
         standalone=args.standalone,

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/_expression_parser.py

@@ -5,7 +5,7 @@
 """The syntax tree the expression grammar builds, and the grammar — package-private.
 
 Only expansion and resolution read it: resolution rewrites it into the
-:mod:`mathspec.program` vocabulary, which every pass after reads. Arithmetic
+[`mathspec.program`][] vocabulary, which every pass after reads. Arithmetic
 nests anywhere; a comparison appears only at the top of a parsed expression.
 """
 
@@ -31,7 +31,7 @@ ComparisonOperator = Literal['<=', '>=', '==']
 UnaryOperator = Literal['+', '-']
 
 #: The arithmetic a binary operator may spell. Closed by the grammar, and the
-#: vocabulary a renderer dispatching on :attr:`BinaryOperatorNode.op`
+#: vocabulary a renderer dispatching on [`BinaryOperatorNode.op`][]
 #: switches over — it keeps no list of its own.
 BinaryOperator = Literal['+', '-', '*', '/', '**']
 
@@ -145,7 +145,7 @@ class ComparisonNode:
     right: ArithmeticNode
 
     def __str__(self) -> str:
-        """Both sides bare: a comparison is not an :data:`ArithmeticNode`, so nothing can take one as an operand."""
+        """Both sides bare: a comparison is not an [`ArithmeticNode`][], so nothing can take one as an operand."""
         return f'{self.left} {self.op} {self.right}'
 
 
@@ -191,7 +191,7 @@ def nodes(*roots: ParsedNode) -> Iterator[ParsedNode]:
     """Every node under *roots*, each root itself included, parents first.
 
     The traversal a question about a tree is a filter of, the way
-    :func:`mathspec.program.walk` is for a program.
+    [`mathspec.program.walk`][] is for a program.
     """
     for root in roots:
         yield root
@@ -199,7 +199,7 @@ def nodes(*roots: ParsedNode) -> Iterator[ParsedNode]:
 
 
 def with_children(node: ArithmeticNode, recurse: Callable[[ArithmeticNode], ArithmeticNode]) -> ArithmeticNode:
-    """*node* rebuilt with *recurse* applied to each of its :func:`children`; a leaf comes back as is."""
+    """*node* rebuilt with *recurse* applied to each of its [`children`][]; a leaf comes back as is."""
     if isinstance(node, NumberNode | NameNode | NameListNode | KeywordNode):
         return node
     if isinstance(node, UnaryOperatorNode):
@@ -346,11 +346,11 @@ def parse_text[T](
     child_of: Callable[[T], tuple[T, ...]],
     deep_rewrite: str,
 ) -> T:
-    """Parse the whole of *text* with *grammar*, or raise :class:`SchemaError` naming *what* failed to parse.
+    """Parse the whole of *text* with *grammar*, or raise [`SchemaError`][] naming *what* failed to parse.
 
     *rewrite* is asked for the predictable mistake at the failure position; its
     sentence, if any, precedes the grammar's own complaint. A tree nesting past
-    :data:`MAX_DEPTH`, measured through *child_of*, is refused with
+    [`MAX_DEPTH`][], measured through *child_of*, is refused with
     *deep_rewrite* — and so is one the parser itself ran out of stack on. The
     node comes back as the type *child_of* walks, which is the grammar's word
     for what it builds.

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/_expression_resolver.py

@@ -4,9 +4,9 @@
 
 """The expression walk of name resolution: an arithmetic syntax tree into the program's expression nodes.
 
-Every operator call is read here — its shape against :data:`~mathspec.operators.BUILTINS`,
+Every operator call is read here — its shape against [`BUILTINS`][],
 its dimension and relation arguments against the namespace — and the node it
-stands for is built. :mod:`mathspec.resolution` holds the namespace and the
+stands for is built. [`mathspec.resolution`][] holds the namespace and the
 doors that call this.
 """
 
@@ -32,7 +32,6 @@ from mathspec._expression_parser import (
 )
 from mathspec.dimensions import dims_of
 from mathspec.errors import DimensionError, SchemaError, did_you_mean
-from mathspec.model import NUMERIC_DTYPES
 from mathspec.operators import (
     AMOUNTS,
     BUILTINS,
@@ -62,6 +61,7 @@ from mathspec.program import (
     carries_variable,
     children,
 )
+from mathspec.spec import NUMERIC_DTYPES
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -101,7 +101,7 @@ class ExpressionResolver:
         return isinstance(value, NameNode) and value.name in self.formals
 
     def build(self, node: ArithmeticNode) -> Expression | None:
-        """The program tree *node* stands for, held to :data:`MAX_RESOLVED_DEPTH` before anything walks it.
+        """The program tree *node* stands for, held to [`MAX_RESOLVED_DEPTH`][] before anything walks it.
 
         The depth is measured with every named expression written in, since
         that is the tree every later pass recurses over, and measured with an
@@ -175,9 +175,9 @@ class ExpressionResolver:
     def _name(self, node: NameNode) -> Expression | None:
         """A bare name as the variable, parameter or named expression it declares; a dimension or relation is not a value.
 
-        A named expression arrives as the one node :meth:`Namespace.named`
+        A named expression arrives as the one node [`Namespace.named`][]
         built for it; the cast is the one place a
-        :class:`~mathspec.program.Named` enters a tree typed as a program's,
+        [`Named`][mathspec.program.Named] enters a tree typed as a program's,
         which lowering makes true.
         """
         if node.name in self.formals:
@@ -360,7 +360,7 @@ class ExpressionResolver:
     def _amount(self, value: ArithmeticNode, operator: str, key: str) -> int | str | None:
         """``offset=`` or ``window=``: a whole number in the operator's range, or the name of a parameter.
 
-        Closed so that :func:`mathspec.dimensions._check_named_amount` sees
+        Closed so that [`mathspec.dimensions._check_named_amount`][] sees
         every parameter an amount carries, and so that a program's
         ``offset`` and ``width`` are the ``int | str`` they say.
         """
@@ -441,7 +441,7 @@ class ExpressionResolver:
         Constraints sit outside the flat namespace, so this store is consulted
         only here — a bare name in arithmetic never reaches it. A dual standing
         where the math is built is refused separately
-        (:mod:`mathspec.degree`); this pass only types the name.
+        ([`mathspec.degree`][]); this pass only types the name.
         """
         (value,) = node.args
         if self._formal(value):

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/_sealed.py

@@ -19,7 +19,7 @@ class Sealed[K, V](Mapping[K, V]):
     What every group a program hands out is held behind, and a node's
     keyword arguments with them: a consumer cannot rewrite what another
     consumer reads, and the whole crosses a process — which is the one thing
-    :class:`types.MappingProxyType` cannot do. Equal to any mapping with the
+    [`types.MappingProxyType`][] cannot do. Equal to any mapping with the
     same items, and hashable over them where they are, so a dataclass may
     hold one as a default.
     """

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/_where_parser.py

@@ -8,8 +8,8 @@ A where string is a boolean algebra over comparisons, and a comparison's
 sides are the expression grammar's own arithmetic. What a side *is* — a
 parameter, a dimension, a relation column, a ``position()`` — only the schema
 knows, so the grammar hands both sides over bare and
-:mod:`mathspec.resolution` reads them. The resolved vocabulary lives in
-:mod:`mathspec.program`.
+[`mathspec.resolution`][] reads them. The resolved vocabulary lives in
+[`mathspec.program`][].
 """
 
 from __future__ import annotations
@@ -71,7 +71,7 @@ class UnresolvedPredicateCallNode:
     arithmetic arguments, and a predicate is not arithmetic. So the where
     grammar reads it, and resolution decides which operator the name is and
     what the kwargs mean. ``kwargs`` is held and hashed as
-    :class:`~mathspec._expression_parser.FunctionCallNode` holds its own.
+    [`FunctionCallNode`][mathspec._expression_parser.FunctionCallNode] holds its own.
     """
 
     name: str
@@ -86,7 +86,7 @@ class UnresolvedPredicateCallNode:
 class UnresolvedCountNode:
     """``count(<predicate>, over=<dim>) <op> <number>`` — a count against a literal.
 
-    Its own node rather than an :class:`UnresolvedComparisonNode` with a call
+    Its own node rather than an [`UnresolvedComparisonNode`][] with a call
     on the left: every other comparison has arithmetic on both sides, and
     widening that one to carry a predicate would widen every reader of a side
     with it.
@@ -103,7 +103,7 @@ class UnresolvedComparisonNode:
 
     A side is the expression grammar's arithmetic, so a name, a number and a
     ``position(...)`` call all arrive as the nodes an expression would carry
-    them in, a quoted label as the :class:`KeywordNode` a quoted kwarg is, and a
+    them in, a quoted label as the [`KeywordNode`][] a quoted kwarg is, and a
     relation column in a node of its own.
     """
 
@@ -272,8 +272,8 @@ def parse_where(text: str) -> Predicate | UnresolvedWhereNode:
     """Parse a where string into an AST, its leaves still unresolved.
 
     The connectives and literals are the resolved vocabulary's own; the leaves
-    naming declarations are a bare :class:`NameNode` or an ``Unresolved*``
-    node, which only :func:`~mathspec.resolution.resolve_where` takes.
+    naming declarations are a bare [`NameNode`][] or an ``Unresolved*``
+    node, which only [`resolve_where`][mathspec.resolution.resolve_where] takes.
 
     Raises:
         SchemaError: If *text* is not a where string of the language. A

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/_where_resolver.py

@@ -7,7 +7,7 @@
 A bare name, a comparison, a count and a predicate read through a relation
 or along a dimension are each typed here against the namespace, and a
 comparison of expressions hands its sides to the expression walk.
-:mod:`mathspec.resolution` holds the namespace and the doors that call this.
+[`mathspec.resolution`][] holds the namespace and the doors that call this.
 """
 
 from __future__ import annotations
@@ -90,7 +90,7 @@ class WhereResolver:
     appended to ``errors``; every sibling is still read, so a mask with two
     faults reports both. ``self_variable`` is the variable whose own
     ``where`` is being read, which may not ask whether it exists. A side
-    that is an expression is built by an :class:`ExpressionResolver` over
+    that is an expression is built by an [`ExpressionResolver`][] over
     the same namespace.
     """
 
@@ -169,7 +169,7 @@ class WhereResolver:
         """``shift(<predicate>, along=, offset=)`` or ``at(<predicate>, by=, over=, into=)`` — the two operators that read a predicate and answer one.
 
         ``count`` answers a number, so it stands on a comparison's side and
-        :meth:`_count` reads it there. Anything else naming a predicate is
+        [`_count`][] reads it there. Anything else naming a predicate is
         refused here rather than resolved into arithmetic it cannot be.
 
         An operand that failed to resolve is handed straight back: resolution

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/_yaml.py

@@ -94,10 +94,10 @@ def read_yaml(path: Path | str) -> dict[str, object]:
     return parse_yaml(Path(path).read_text(encoding='utf-8'), str(path))
 
 
-def read_model(model: str | Path) -> dict[str, object]:
-    """A model from a file or from its text — a newline decides which a ``str`` is.
+def read_spec(spec: str | Path) -> dict[str, object]:
+    """A spec from a file or from its text — a newline decides which a ``str`` is.
 
-    A :class:`~pathlib.Path` names a file, and so does a ``str`` with no
+    A [`Path`][] names a file, and so does a ``str`` with no
     newline in it, since no path holds one; a ``str`` with a newline is the
     YAML itself, which every file and every ``to_yaml()`` ends with. Nothing
     else is read off the content and nothing is read off the disk to decide.
@@ -106,15 +106,15 @@ def read_model(model: str | Path) -> dict[str, object]:
         FileNotFoundError: A ``str`` with no newline that names no file — a
             one-line text is told to end with one.
     """
-    if isinstance(model, str) and '\n' not in model and not Path(model).is_file():
+    if isinstance(spec, str) and '\n' not in spec and not Path(spec).is_file():
         msg = (
-            f'no file named {model!r}. A str with no newline in it is read as a path, and YAML text '
+            f'no file named {spec!r}. A str with no newline in it is read as a path, and YAML text '
             f'is told apart by one — end the text with a newline, or pass a Path.'
         )
         raise FileNotFoundError(msg)
-    if isinstance(model, Path) or '\n' not in model:
-        return read_yaml(Path(model))
-    return parse_yaml(model, 'YAML text')
+    if isinstance(spec, Path) or '\n' not in spec:
+        return read_yaml(Path(spec))
+    return parse_yaml(spec, 'YAML text')
 
 
 def parse_yaml(text: str, origin: str = '<string>') -> dict[str, object]:
@@ -136,6 +136,6 @@ def parse_yaml(text: str, origin: str = '<string>') -> dict[str, object]:
     if not data:
         return {}
     if not isinstance(data, dict):
-        msg = f'{origin}: a model file must be a mapping of sections (dimensions:, variables:, …), got {type(data).__name__}.'
+        msg = f'{origin}: a spec file must be a mapping of sections (dimensions:, variables:, …), got {type(data).__name__}.'
         raise SchemaError(msg)
     return data

mathspec-0.1.0/src/mathspec/advice.py → mathspec-0.2.0/src/mathspec/advising.py

@@ -4,7 +4,7 @@
 
 """Advice — what is decidable without data and is a note rather than a refusal.
 
-One door, :func:`advice`, over every pass of that kind.
+One door, [`advice`][], over every pass of that kind.
 """
 
 from __future__ import annotations
@@ -20,23 +20,29 @@ if TYPE_CHECKING:
     from collections.abc import Mapping
     from pathlib import Path
 
-    from mathspec.model import Spec
+    from mathspec.spec import Spec
 
 
-def advice(model: str | Path | Mapping[str, object] | Spec | Program) -> tuple[Advice, ...]:
-    """Everything the language advises about *model* — never an error, decidable without data.
+def advice(spec: str | Path | Mapping[str, object] | Spec | Program) -> tuple[Advice, ...]:
+    """Everything the language advises about *spec*, decided without data.
+
+    Advice is a note, not a refusal: a file with advice still loads.
 
     Args:
-        model: A YAML path, a mapping, a loaded :class:`Spec`, or a
-            :class:`Program`, read as it arrived. A ``piecewise:`` or ``sos:``
-            block is read as the rows it states, so the answer is the one its
-            expansion gets, with nothing expanded.
+        spec: Anything [`to_spec`][] accepts, or a [`Program`][], read as
+            it arrived. A ``piecewise:`` or ``sos:`` block is read as the rows
+            it states, so the answer is the one its expansion gets, with
+            nothing expanded.
 
     Returns:
         The never-an-axis advice in declaration order, then the unboundedness
         advice; ``str()`` of each is its sentence.
+
+    Raises:
+        LanguageError: *spec* does not load; [`to_spec`][] says why.
+        FileNotFoundError: A ``str`` with no newline that names no file.
     """
-    program = model if isinstance(model, Program) else to_spec(model).program
+    program = spec if isinstance(spec, Program) else to_spec(spec).program
     return tuple(_never_an_axis(program) + unbounded_notes(program))
 
 

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/boundedness.py

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: MIT
 
-"""Provably unbounded models, named before a solver says a bare ``unbounded``.
+"""Provably unbounded specs, named before a solver says a bare ``unbounded``.
 
 A variable unbounded on the side its objective term improves toward, and named
 by no constraint, runs to infinity for any data. Which side is read off the
@@ -84,7 +84,7 @@ def unbounded_notes(program: Program) -> list[Advice]:
                 Advice(
                     'unbounded',
                     vname,
-                    f"Variable '{vname}' makes this model unbounded: no constraint names it, and "
+                    f"Variable '{vname}' makes this spec unbounded: no constraint names it, and "
                     f'bounds.{side} is open, which is the direction a {sign}{vname} term '
                     f'improves a {program.objective.sense} objective in. No data can change that, so '
                     f'the solve would answer `unbounded` and name nothing.\n'

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/degree.py

@@ -103,7 +103,7 @@ def _degree(node: Expression) -> int:
     """The polynomial degree *node* stands for, counted structurally.
 
     A product adds its factors' degrees and a division keeps the dividend's
-    (:func:`check_binary` has already refused a divisor carrying a variable);
+    ([`check_binary`][] has already refused a divisor carrying a variable);
     everything else — a sum, a reduction, a shape operator — is the highest
     degree beneath it. No data, so this answers at ``check`` time, which is
     what stops a cubic from reaching a consumer to be refused by whichever one
@@ -184,7 +184,7 @@ def _joins_terms(node: Expression) -> bool:
 
 
 def check_expression(node: Expression, context: str, *, ceiling: int = 1) -> None:
-    """What the math admits at one position: no dual anywhere under *node*, then :func:`check_binary` everywhere in it.
+    """What the math admits at one position: no dual anywhere under *node*, then [`check_binary`][] everywhere in it.
 
     Asked of the resolved tree, so a dual or a product reached through a
     macro or a named expression is caught alongside one written in place.
@@ -192,7 +192,7 @@ def check_expression(node: Expression, context: str, *, ceiling: int = 1) -> Non
 
     Raises:
         LanguageError: A dual, which exists only after a solve; or what
-            :func:`check_binary` refuses.
+            [`check_binary`][] refuses.
     """
     for found in walk(node):
         if isinstance(found, Dual):
@@ -205,5 +205,5 @@ def check_expression(node: Expression, context: str, *, ceiling: int = 1) -> Non
 
 
 def calls_dual(node: Expression) -> bool:
-    """Whether a :class:`~mathspec.program.Dual` stands anywhere under *node*."""
+    """Whether a [`Dual`][mathspec.program.Dual] stands anywhere under *node*."""
     return any(isinstance(found, Dual) for found in walk(node))

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/dimensions.py

@@ -53,8 +53,8 @@ from mathspec.program import (
 )
 
 if TYPE_CHECKING:
-    from mathspec.model import Spec
     from mathspec.program import Program
+    from mathspec.spec import Spec
 
 
 def dims_of(node: Expression, schema: Spec, context: str) -> frozenset[str]:
@@ -343,7 +343,7 @@ def _check_where_dims(
     """A predicate may only test dims the frame carries; reducing an outside dim to fit would fail open.
 
     The refusal names the leaf that left the frame, reading its dims as
-    :attr:`~mathspec.program.Mask.dims` does.
+    [`dims`][mathspec.program.Mask.dims] does.
     """
     if mask is None:
         return

{mathspec-0.1.0 → mathspec-0.2.0}/src/mathspec/errors.py

@@ -16,7 +16,7 @@ if TYPE_CHECKING:
     from pydantic import ValidationError
 
 
-#: Which pass an :class:`Advice` comes from. Closed, like the operator set: a
+#: Which pass an [`Advice`][] comes from. Closed, like the operator set: a
 #: consumer filtering on it can enumerate every value.
 AdviceKind = Literal['never-an-axis', 'unbounded']
 
@@ -25,7 +25,7 @@ AdviceKind = Literal['never-an-axis', 'unbounded']
 class Advice:
     """One thing the language advises about a file it accepts.
 
-    Never an error: each is what a half-written model looks like too. A
+    Never an error: each is what a half-written spec looks like too. A
     consumer prints it, or filters on ``kind`` and ``subject``; the text is the
     language's, so no consumer writes its own.
 
@@ -48,7 +48,7 @@ class MathSpecError(ValueError):
 
 
 class LanguageError(MathSpecError):
-    """The model is not sayable in the language, or does not obey its rules."""
+    """The spec is not sayable in the language, or does not obey its rules."""
 
 
 class SchemaError(LanguageError):
@@ -71,8 +71,8 @@ def did_you_mean(name: str, known: Iterable[str], *, label: str = 'Declared') ->
 def schema_error(exc: ValidationError) -> LanguageError:
     """A pydantic ``ValidationError`` as one of ours.
 
-    Returns the original :class:`LanguageError` subclass where exactly one
-    error carries one, and a :class:`SchemaError` otherwise.
+    Returns the original [`LanguageError`][] subclass where exactly one
+    error carries one, and a [`SchemaError`][] otherwise.
     """
     errors = exc.errors()
     lines = []