gecode-iris 0.1.0__cp310-abi3-win_amd64.whl

gecode_iris/__init__.py

@@ -0,0 +1,15 @@
+"""Read text instance files with Iris reader specs.
+
+Parse a reader spec with ``Spec.parse`` or ``Spec.load``, then read an
+input with ``spec.read``. Language errors raise ``Error``. Build a reader
+spec in Python with typed handles in ``gecode_iris.build``.
+
+The package also installs the ``iris`` command, the same command line as the
+Rust ``iris`` binary.
+"""
+
+from gecode_iris._data import Entry, Value
+from gecode_iris._error import CallSite, Error
+from gecode_iris._native import Data, Spec
+
+__all__ = ["CallSite", "Data", "Entry", "Error", "Spec", "Value"]

gecode_iris/_cli.py

@@ -0,0 +1,20 @@
+"""The ``iris`` console script, which runs the Rust ``iris`` command line."""
+
+from __future__ import annotations
+
+import signal
+import sys
+
+from gecode_iris._native import run_cli
+
+
+def main() -> None:
+    """Run ``iris`` on this process's arguments and exit with its status."""
+    # The Rust code writes to the process's file descriptors directly.
+    sys.stdout.flush()
+    sys.stderr.flush()
+    # Python's handler would only take effect once the Rust code returns, so
+    # restore the default; an inherited SIG_IGN or a custom handler stays.
+    if signal.getsignal(signal.SIGINT) is signal.default_int_handler:
+        signal.signal(signal.SIGINT, signal.SIG_DFL)
+    sys.exit(run_cli(sys.argv))

gecode_iris/_data.py

@@ -0,0 +1,24 @@
+"""The Python types of what ``Data`` holds."""
+
+from __future__ import annotations
+
+from typing import Literal, NamedTuple, TypeAlias
+
+Value: TypeAlias = int | float | str | list["Value"]
+"""An entry value: ``int``, ``float`` or ``str`` at depth 0, and a list of
+values one level shallower at each greater depth."""
+
+
+class Entry(NamedTuple):
+    """The name, value type and depth of one entry in ``Data``."""
+
+    name: str
+    """The entry name."""
+    value_type: Literal["int", "float", "string"]
+    """The type of the entry's scalars."""
+    depth: int
+    """The number of array levels: 0 for a scalar, 1 for a row, and so on."""
+
+
+# The package exports this class, so pickles name it there.
+Entry.__module__ = "gecode_iris"

gecode_iris/_error.py

@@ -0,0 +1,89 @@
+"""The exception for Iris language errors."""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class CallSite(NamedTuple):
+    """A place in the host program: where a builder statement was called.
+
+    ``str(site)`` is ``file:line``.
+    """
+
+    filename: str
+    """The file of the calling code, as its code object names it."""
+    line: int
+    """The line of the call, counting from 1."""
+    function: str
+    """The name of the calling function, such as ``<module>``."""
+
+    def __str__(self) -> str:
+        return f"{self.filename}:{self.line}"
+
+
+# The package exports this class, so pickles name it there.
+CallSite.__module__ = "gecode_iris"
+
+
+class Error(Exception):
+    """A language error from parsing a reader spec or reading an input.
+
+    ``str(error)`` is the full diagnostic. The location is the input
+    location when there is one, and otherwise the reader spec location;
+    ``line``, ``column`` and ``origin`` are each ``None`` when unknown.
+    ``path`` is the record path of a failed check over records.
+
+    Host failures, such as a missing file, raise built-in exceptions
+    instead and have no error code.
+    """
+
+    # The package exports this class, so pickles and tracebacks name it there.
+    __module__ = "gecode_iris"
+
+    code: str
+    """The stable error code, such as ``E-CHECK-FAILED``."""
+    message: str
+    """The message, without location or excerpt."""
+    line: int | None
+    """The line of the location, counting from 1."""
+    column: int | None
+    """The byte column of the location, counting from 1."""
+    path: tuple[int, ...] | None
+    """The record path of a failed check over records."""
+    origin: str | None
+    """The input or reader spec origin of the location, such as its path."""
+    call_site: CallSite | None
+    """Where the statement the error belongs to was called, for a spec built
+    with ``gecode_iris.build``; ``None`` for a spec parsed from text."""
+
+    def __init__(
+        self,
+        text: str,
+        code: str,
+        message: str,
+        line: int | None,
+        column: int | None,
+        path: tuple[int, ...] | None,
+        origin: str | None,
+        document: str,
+        call_site: CallSite | None = None,
+    ) -> None:
+        super().__init__(text)
+        self.code = code
+        self.message = message
+        self.line = line
+        self.column = column
+        self.path = path
+        self.origin = origin
+        self.call_site = call_site
+        self._document = document
+
+    def to_json(self) -> str:
+        """Return the canonical JSON error document."""
+        return self._document
+
+    def __reduce__(self) -> tuple[type[Error], tuple[object, ...]]:
+        text = self.args[0]
+        fields = (self.code, self.message, self.line, self.column, self.path, self.origin)
+        return type(self), (text, *fields, self._document, self.call_site)

gecode_iris/_native.pyi

@@ -0,0 +1,96 @@
+from collections.abc import Mapping, Sequence
+from os import PathLike
+from typing import Any, TypeVar, final, overload
+
+from numpy.typing import NDArray
+
+from gecode_iris._data import Entry, Value
+from gecode_iris.build import Field
+
+_T = TypeVar("_T")
+
+@final
+class Spec:
+    """A parsed and checked reader spec.
+
+    One ``Spec`` can read any number of inputs, and threads can share it.
+    """
+
+    @staticmethod
+    def parse(text: str | bytes | bytearray, origin: str = "<string>") -> Spec:
+        """Parse and check a reader spec given as ``str`` or ``bytes``."""
+
+    @staticmethod
+    def _parse_built(text: str, origin: str, call_sites: Any) -> Spec: ...
+    @property
+    def _call_sites(self) -> Any: ...
+    @staticmethod
+    def load(path: str | PathLike[str]) -> Spec:
+        """Read and parse a reader spec file; the path is the error origin."""
+
+    def read(
+        self,
+        source: bytes | bytearray | str | PathLike[str],
+        params: Mapping[str, str] | None = None,
+        *,
+        origin: str | None = None,
+    ) -> Data:
+        """Read one instance from input bytes or from a path."""
+
+    def catalog(
+        self,
+        source: bytes | bytearray | str | PathLike[str],
+        params: Mapping[str, str] | None = None,
+        *,
+        origin: str | None = None,
+    ) -> Data:
+        """List the instances in the input, with the same arguments as ``read``."""
+
+@final
+class Data:
+    """The data from one read or catalog.
+
+    ``data[name]`` returns an entry's value and ``name in data`` tests for an
+    entry. Values are copied into Python objects on each access: an ``int``,
+    ``float`` or ``str`` at depth 0, and nested lists at greater depths.
+
+    A handle from ``gecode_iris.build`` can stand for the name, and then
+    ``data[handle]`` has the handle's type: ``None`` when an optional entry is
+    absent. A handle whose entry has another value type or depth, because a
+    later statement redefined its name or the handle belongs to another reader
+    spec, raises ``TypeError``.
+    """
+
+    @property
+    def entries(self) -> tuple[Entry, ...]:
+        """The entries in the order their names were defined."""
+
+    @overload
+    def __getitem__(self, key: str, /) -> Value: ...
+    @overload
+    def __getitem__(self, key: Field[_T], /) -> _T: ...
+    def __getitem__(self, key: str | Field[Any], /) -> Any:
+        """The whole value of an entry; raises ``KeyError`` for an unknown name."""
+
+    def __contains__(self, key: object, /) -> bool: ...
+    def ints(self, key: str | Field[Any], /, *path: int) -> list[int]:
+        """The integer row of an entry at a path."""
+
+    def array(self, key: str | Field[Any], /, *path: int) -> NDArray[Any] | list[Value]:
+        """An array of an entry, or of its row at a path.
+
+        The result is a ``numpy.ndarray`` when numpy is importable and the
+        array is rectangular, and nested lists otherwise.
+        """
+
+    def to_dict(self) -> dict[str, Value]:
+        """All entries as a ``dict`` from name to value, in entry order."""
+
+    def to_json(self) -> str:
+        """The canonical JSON document, ending in a newline."""
+
+    def to_dzn(self) -> str:
+        """The MiniZinc data text defined in the Specification's appendix B."""
+
+def run_cli(argv: Sequence[str]) -> int:
+    """Run the ``iris`` command line on ``argv``, program name first; return its exit status."""

gecode_iris/build/__init__.py

@@ -0,0 +1,204 @@
+"""Build reader specs from Python code, with typed handles.
+
+A :class:`SpecBuilder` is the root scope of a spec. Each statement is a method
+call, a block is a ``with`` statement, and every definition returns a handle
+that later statements use in expressions and that ``data[handle]`` reads from
+the data with the type it promises::
+
+    import gecode_iris.build as ib
+
+    b = ib.SpecBuilder("jobshop")
+    jobs = b.read("jobs", ib.int_range(1))
+    machines = b.read("machines", ib.int_range(1))
+    with b.repeat(jobs) as job:
+        with job.repeat(machines) as task:
+            machine = task.read("machine", ib.int_range(0, machines - 1))
+            duration = task.read("duration", ib.at_least(0))
+    spec = b.build()
+
+    data = spec.read(b"1 2\\n0 3 1 4\\n")
+    data[duration]  # [[3, 4]], typed list[list[int]]
+
+Python operators build Iris expressions, except for division, remainder and
+power, which are :func:`div`, :func:`rem` and :func:`pow`, and the logical
+operators, which are ``&``, ``|`` and ``~``. Line patterns are t-strings on
+Python 3.14 and later, and tuples of text and parts on every version.
+
+A mistake that a builder can find raises :class:`BuildError` at the call that
+made it, or from ``build()``, and names the caller's file and line. Errors
+while reading a built spec name the call site of their statement in
+:attr:`gecode_iris.Error.call_site`.
+"""
+
+from typing import NoReturn
+
+from gecode_iris._error import CallSite
+from gecode_iris.build import gecode
+from gecode_iris.build._error import BuildError, BuildErrorKind
+from gecode_iris.build._expr import (
+    DynExpr,
+    DynField,
+    Expr,
+    Field,
+    FloatExpr,
+    FloatField,
+    FloatLookup,
+    IntExpr,
+    IntField,
+    IntLookup,
+    NumExpr,
+    NumField,
+    NumLookup,
+    Record,
+    RecordExpr,
+    RecordList,
+    StrExpr,
+    StrField,
+    StrLookup,
+    all,
+    any,
+    count,
+    defined,
+    distinct,
+    div,
+    lit,
+    max,
+    min,
+    over,
+    pow,
+    rem,
+    size,
+    sum,
+)
+from gecode_iris.build._pattern import (
+    Discard,
+    Part,
+    bind,
+    blank,
+    discard,
+    discard_as,
+    ref,
+    rest_of_line,
+    validate,
+)
+from gecode_iris.build._scope import (
+    ArmGuard,
+    Arms,
+    Block,
+    Scope,
+    Scope0,
+    Scope1,
+    Scope2,
+    Scope3,
+    ScopeN,
+    SectionsGuard,
+    SpecBuilder,
+    declared,
+)
+from gecode_iris.build._site import track_caller
+from gecode_iris.build._types import (
+    Alphabet,
+    Eol,
+    FloatType,
+    IntType,
+    ListReading,
+    NumType,
+    StrType,
+    Type,
+    alphabet,
+    at_least,
+    eol,
+    float_,
+    int_,
+    int_range,
+    num,
+    rest,
+    word,
+)
+
+Required = NoReturn
+"""The presence of a scope whose statements always execute."""
+
+Maybe = None
+"""The presence of a scope whose statements may not execute."""
+
+__all__ = [
+    "Alphabet",
+    "ArmGuard",
+    "Arms",
+    "Block",
+    "BuildError",
+    "BuildErrorKind",
+    "CallSite",
+    "Discard",
+    "DynExpr",
+    "DynField",
+    "Eol",
+    "Expr",
+    "Field",
+    "FloatExpr",
+    "FloatField",
+    "FloatLookup",
+    "FloatType",
+    "IntExpr",
+    "IntField",
+    "IntLookup",
+    "IntType",
+    "ListReading",
+    "Maybe",
+    "NumExpr",
+    "NumField",
+    "NumLookup",
+    "NumType",
+    "Part",
+    "Record",
+    "RecordExpr",
+    "RecordList",
+    "Required",
+    "Scope",
+    "Scope0",
+    "Scope1",
+    "Scope2",
+    "Scope3",
+    "ScopeN",
+    "SectionsGuard",
+    "SpecBuilder",
+    "StrExpr",
+    "StrField",
+    "StrLookup",
+    "StrType",
+    "Type",
+    "all",
+    "alphabet",
+    "any",
+    "at_least",
+    "bind",
+    "blank",
+    "count",
+    "declared",
+    "defined",
+    "discard",
+    "discard_as",
+    "distinct",
+    "div",
+    "eol",
+    "float_",
+    "gecode",
+    "int_",
+    "int_range",
+    "lit",
+    "max",
+    "min",
+    "num",
+    "over",
+    "pow",
+    "ref",
+    "rem",
+    "rest",
+    "rest_of_line",
+    "size",
+    "sum",
+    "track_caller",
+    "validate",
+    "word",
+]