Python API reference

The public API of the gecode_iris package. pdoc 16.0.0 generates it during each site build from the package's type stubs and docstrings. The Python guide shows the API in use, and the spec builder's reference covers gecode_iris.build.

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.

CallSite

class CallSite(typing.NamedTuple):

CallSite(filename: str, line: int, function: str)

A place in the host program: where a builder statement was called.

str(site) is file:line.

CallSite.filename

filename: str

The file of the calling code, as its code object names it.

CallSite.line

line: int

The line of the call, counting from 1.

CallSite.function

function: str

The name of the calling function, such as <module>.

Data

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.

Data.ints

def ints( self, key: str | gecode_iris.build.Field[Any], /, *path: int) -> list[int]:

The integer row of an entry at a path.

Data.array

def array( self, key: str | gecode_iris.build.Field[Any], /, *path: int) -> numpy.typing.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.

Data.to_dict

def to_dict(self) -> dict[str, Value]:

All entries as a dict from name to value, in entry order.

Data.to_json

def to_json(self) -> str:

The canonical JSON document, ending in a newline.

Data.to_dzn

def to_dzn(self) -> str:

The MiniZinc data text defined in the Specification's appendix B.

Data.entries

entries: tuple[Entry, ...]

The entries in the order their names were defined.

Entry

class Entry(typing.NamedTuple):

Entry(name: str, value_type: Literal['int', 'float', 'string'], depth: int)

The name, value type and depth of one entry in Data.

Entry.name

name: str

The entry name.

Entry.value_type

value_type: Literal['int', 'float', 'string']

The type of the entry's scalars.

Entry.depth

depth: int

The number of array levels: 0 for a scalar, 1 for a row, and so on.

Error

class Error(builtins.Exception):

Error( 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)

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.

Error.code

code: str

The stable error code, such as E-CHECK-FAILED.

Error.message

message: str

The message, without location or excerpt.

Error.line

line: int | None

The line of the location, counting from 1.

Error.column

column: int | None

The byte column of the location, counting from 1.

Error.path

path: tuple[int, ...] | None

The record path of a failed check over records.

Error.origin

origin: str | None

The input or reader spec origin of the location, such as its path.

Error.call_site

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.

Error.to_json

def to_json(self) -> str:

Return the canonical JSON error document.

Spec

class Spec:

A parsed and checked reader spec.

One Spec can read any number of inputs, and threads can share it.

Spec.parse

def parse( text: str | bytes | bytearray, origin: str = '<string>') -> Spec:

Parse and check a reader spec given as str or bytes.

Spec.load

def load(path: str | os.PathLike[str]) -> Spec:

Read and parse a reader spec file; the path is the error origin.

Spec.read

def read( self, source: bytes | bytearray | str | os.PathLike[str], params: Mapping[str, str] | None = None, *, origin: str | None = None) -> Data:

Read one instance from input bytes or from a path.

Spec.catalog

def catalog( self, source: bytes | bytearray | str | os.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.

Value

Value = 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.

The iris command

The iris console script, which runs the Rust iris command line.

def main() -> None:

Run iris on this process's arguments and exit with its status.