daitum-test 0.5.2__py3-none-any.whl

daitum_test/__init__.py

@@ -0,0 +1,107 @@
+# Copyright 2026 Daitum
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+daitum_test - Test Daitum models from Python
+============================================
+
+Load a model, feed it data, run it, and make plain assertions about the results — tables,
+named values, and diagnostics — locally, without the platform. Use it to unit-test a formula
+against crafted inputs, check an optimisation result, assert an output table has no error
+cells, or compare several scenarios in one run.
+
+.. code-block:: python
+
+    from daitum_test import Evaluator, Model, Run
+
+    model = Model.from_archive("MyModel.zip")
+    evaluator = Evaluator()
+
+    result = evaluator.evaluate(model, runs=[
+        Run(scenario="Initial", id="high-demand", mode="OPTIMISER",
+            tables={"Items": "fixtures/items_high_demand.csv"},
+            named_values={"Budget": 50_000}),
+    ])
+
+    run = result["high-demand"]
+    assert run.errors == []
+    assert run.named_value("TotalCost") <= 50_000
+    assert run.table("Output").row_count >= 1
+    assert run.table("Output").error_cells() == []
+
+Load a model with :meth:`Model.from_archive`, :meth:`Model.from_directory`, or
+:meth:`Model.from_definition` (daitum-core builders work directly). Feed data as CSV files or
+inline rows — cells are typed from the model's own field definitions. A pytest plugin provides
+a ready-made ``evaluator`` fixture.
+
+Install with ``pip install daitum-test`` (no runtime dependencies beyond the standard
+library). Evaluation runs against the Daitum model engine, which is obtained separately and
+located via the ``EVALUATOR_JAR`` environment variable, with a Java 25+ runtime available; see
+the README. Each evaluation loads the whole model once, so batch a module's runs into a single
+``evaluate`` call (e.g. from a module-scoped fixture) rather than calling per test.
+"""
+
+from daitum_test.data import ERROR, INDEX_KEY, REF_KEY
+from daitum_test.errors import (
+    ContractError,
+    DaitumTestError,
+    DataConversionError,
+    EvaluatorCrashError,
+    EvaluatorNotFoundError,
+    ModelInspectionError,
+    UnknownFieldError,
+    UnknownNamedValueError,
+    UnknownRunError,
+    UnknownTableError,
+)
+from daitum_test.evaluator import Evaluator
+from daitum_test.model import Model
+from daitum_test.result import (
+    Diagnostic,
+    ErrorCell,
+    EvaluationResult,
+    RunResult,
+    TableResult,
+    ValidationReport,
+    is_error_cell,
+)
+from daitum_test.run import Options, Run, TableLike
+
+__all__ = [
+    "ERROR",
+    "INDEX_KEY",
+    "REF_KEY",
+    "ContractError",
+    "DaitumTestError",
+    "DataConversionError",
+    "Diagnostic",
+    "ErrorCell",
+    "EvaluationResult",
+    "Evaluator",
+    "EvaluatorCrashError",
+    "EvaluatorNotFoundError",
+    "Model",
+    "ModelInspectionError",
+    "Options",
+    "Run",
+    "RunResult",
+    "TableLike",
+    "TableResult",
+    "UnknownFieldError",
+    "UnknownNamedValueError",
+    "UnknownRunError",
+    "UnknownTableError",
+    "ValidationReport",
+    "is_error_cell",
+]

daitum_test/data.py

@@ -0,0 +1,253 @@
+# Copyright 2026 Daitum
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Conversion of Python data into the evaluator's JSON encodings.
+
+Encodings in the request contract:
+
+- **Table rows** are plain JSON values (``"#ERROR"`` marks an error cell; a missing field
+  is null).
+- **Named values** are typed objects: ``{"@type": "DECIMAL", "value": 0.5}``.
+- **Object references** (``OBJECT`` / ``OBJECT_ARRAY`` fields) are the **row index** of the
+  referenced row within the referenced table, as supplied in the same request (0-based). The
+  harness resolves a natural key (the referenced table's key-column value) to that index for
+  you.
+- **Maps** (``*_MAP`` fields) are objects keyed by the referenced row index as a string:
+  ``{"0": true, "1": false}``. The harness resolves natural keys here too.
+
+CSV files are converted using the model's declared field types — never by guessing from the
+cell text (``"0123"`` silently becoming ``123`` would corrupt STRING data).
+"""
+
+import csv
+import datetime
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+from daitum_test.errors import DataConversionError
+
+ERROR = "#ERROR"
+"""Sentinel for an error cell in input rows."""
+
+#: Escape hatch: wrap a cell as ``{"@ref": key}`` to force resolution by natural key (no
+#: row-index fallback) — use when a key is an integer and might be mistaken for a row index.
+REF_KEY = "@ref"
+
+#: Escape hatch: wrap a cell as ``{"@index": n}`` to pass an explicit 0-based row index
+#: without any key lookup.
+INDEX_KEY = "@index"
+
+# Python type → evaluator DataType, used when the model's declared type is unknown.
+# bool must be checked before int (bool subclasses int).
+_PYTHON_TYPE_NAMES = (
+    (bool, "BOOLEAN"),
+    (int, "INTEGER"),
+    (float, "DECIMAL"),
+    (Decimal, "DECIMAL"),
+    (str, "STRING"),
+    (datetime.datetime, "DATETIME"),  # before date (datetime subclasses date)
+    (datetime.date, "DATE"),
+    (datetime.time, "TIME"),
+)
+
+
+def convert_cell(value: Any) -> Any:
+    """Convert one Python value to the plain JSON cell encoding."""
+    if isinstance(value, (datetime.datetime, datetime.date, datetime.time)):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return float(value)
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, (list, tuple)):
+        return [convert_cell(v) for v in value]
+    raise DataConversionError(f"Cannot encode {value!r} ({type(value).__name__}) as a table cell.")
+
+
+class ReferenceResolver:
+    """Resolves natural keys of referenced tables to the 0-based row indices the evaluator
+    expects for OBJECT / MAP fields.
+
+    A row's index is its position in the referenced table **as supplied in the same request**
+    (an override's rows if the table is overridden, else the model's base scenario rows). The
+    resolver is built from exactly those rows, so the indices it emits match what the evaluator
+    assigns when it loads them.
+
+    A bare value is treated as a natural key and looked up. If the key is not found **and** it
+    is an integer, it falls back to being used as a row index directly — so integer-keyed
+    tables resolve by key, while a hand-supplied row index still works where there is no
+    ambiguity. Use ``{"@ref": k}`` to force a key lookup (no fallback) or ``{"@index": n}`` to
+    force a raw row index.
+    """
+
+    def __init__(self, key_indexes: dict[str, dict[Any, int]]):
+        self._key_indexes = key_indexes
+
+    def _lookup(self, table: str, key: Any, *, allow_index_fallback: bool) -> int:
+        if isinstance(key, bool):  # bool is an int subclass; never a key or index
+            raise DataConversionError(f"A boolean is not a valid reference into {table!r}.")
+        index = self._key_indexes.get(table, {})
+        if key in index:
+            return index[key]
+        if allow_index_fallback and isinstance(key, int):
+            return key  # no row has this key, but a bare int is a usable row index
+        known = ", ".join(repr(k) for k in list(index)[:10])
+        raise DataConversionError(
+            f"Cannot resolve reference {key!r} into table {table!r}: no row with that key. "
+            f"Known keys: {known or '(the table has no rows in this run)'}. Provide the "
+            f"referenced table's rows in the same run, or pass {{'@index': n}} for a row index."
+        )
+
+    def resolve(self, table: str, value: Any) -> int:
+        """Row index for a cell value: a bare key (with int-index fallback), ``{"@ref": k}``
+        (key lookup only), or ``{"@index": n}`` (raw row index)."""
+        if isinstance(value, dict) and set(value) == {INDEX_KEY}:
+            n = value[INDEX_KEY]
+            if not isinstance(n, int) or isinstance(n, bool):
+                raise DataConversionError(f"{INDEX_KEY} requires an integer row index, got {n!r}.")
+            return n
+        if isinstance(value, dict) and set(value) == {REF_KEY}:
+            return self._lookup(table, value[REF_KEY], allow_index_fallback=False)
+        return self._lookup(table, value, allow_index_fallback=True)
+
+
+def encode_object_cell(
+    value: Any, table: str, resolver: ReferenceResolver, *, is_array: bool
+) -> Any:
+    """Encode an OBJECT / OBJECT_ARRAY cell to row index/indices (None passes through)."""
+    if value is None or value == ERROR:
+        return value
+    if is_array:
+        if not isinstance(value, (list, tuple)):
+            raise DataConversionError(
+                f"{table!r} object-array field expects a list of keys, got {value!r}."
+            )
+        return [resolver.resolve(table, key) for key in value]
+    return resolver.resolve(table, value)
+
+
+def encode_map_cell(value: Any, table: str, resolver: ReferenceResolver) -> Any:
+    """Encode a map cell ``{key: v}`` to ``{"<row index>": v}`` (None passes through).
+
+    Map keys are natural keys of the referenced table (integer keys resolve by key too).
+    """
+    if value is None or value == ERROR:
+        return value
+    if not isinstance(value, dict):
+        raise DataConversionError(
+            f"{table!r} map field expects a dict of key→value, got {value!r}."
+        )
+    return {str(resolver.resolve(table, key)): convert_cell(v) for key, v in value.items()}
+
+
+def _convert_csv_cell(table: str, field: str, data_type: str, text: str) -> Any:
+    if text == ERROR:
+        return ERROR
+    try:
+        if data_type == "INTEGER":
+            return int(text)
+        if data_type == "DECIMAL":
+            return float(text)
+        if data_type == "BOOLEAN":
+            lowered = text.lower()
+            if lowered not in ("true", "false"):
+                raise ValueError(f"expected 'true' or 'false', got {text!r}")
+            return lowered == "true"
+        if data_type in ("STRING", "DATE", "DATETIME", "TIME"):
+            return text  # dates are ISO-8601 strings; the evaluator validates them
+        if data_type == "OBJECT":
+            # A single reference: the raw natural key, resolved to a row index later.
+            return text
+    except ValueError as exc:
+        raise DataConversionError(
+            f"{table}[{field}]: cannot convert {text!r} to {data_type}: {exc}"
+        ) from exc
+    raise DataConversionError(
+        f"{table}[{field}] has type {data_type}, which is not supported from CSV "
+        "(object-array and map fields use commas ambiguously); pass inline rows for this "
+        "table instead."
+    )
+
+
+def csv_rows(path: Path, field_types: dict[str, str], table: str = "") -> list[dict[str, Any]]:
+    """Read a CSV file into typed JSON rows using the model's declared field types.
+
+    An empty cell omits the field from the row (null per the contract); an unknown header
+    fails immediately, before any JVM is paid for.
+    """
+    table = table or path.stem
+    # utf-8-sig transparently strips a BOM, common in Excel-exported CSVs.
+    with open(path, newline="", encoding="utf-8-sig") as handle:
+        reader = csv.DictReader(handle)
+        headers = reader.fieldnames or []
+        unknown = [header for header in headers if header not in field_types]
+        if unknown:
+            raise DataConversionError(
+                f"{path}: unknown field(s) {unknown} for table {table!r}. "
+                f"Model fields: {', '.join(sorted(field_types))}"
+            )
+        rows = []
+        for row in reader:
+            converted = {
+                field: _convert_csv_cell(table, field, field_types[field], text)
+                for field, text in row.items()
+                if text is not None and text != ""
+            }
+            rows.append(converted)
+    return rows
+
+
+def _infer_type(value: Any) -> str:
+    for python_type, name in _PYTHON_TYPE_NAMES:
+        if isinstance(value, python_type):
+            return name
+    raise DataConversionError(
+        f"Cannot encode {value!r} ({type(value).__name__}) as a named value; pass a dict "
+        'with an explicit "@type" instead.'
+    )
+
+
+def encode_named_value(value: Any, declared_type: str | None = None) -> dict[str, Any]:
+    """Encode a Python value as the evaluator's ``{"@type": ..., "value": ...}`` object.
+
+    The model's declared type wins when known: the Python value is coerced to it (e.g. ``40``
+    for a DECIMAL named value becomes ``40.0``). A dict already carrying ``"@type"`` passes
+    through verbatim as an escape hatch for types this module does not model.
+    """
+    if isinstance(value, dict):
+        if "@type" in value:
+            return value
+        raise DataConversionError(
+            f'A dict named value must carry "@type"; got keys {sorted(value)}.'
+        )
+
+    if isinstance(value, (list, tuple)):
+        if not value:
+            if declared_type is None:
+                raise DataConversionError(
+                    "Cannot infer the element type of an empty list; the model's declared "
+                    "type is required."
+                )
+            element_type = declared_type
+        else:
+            element_type = declared_type or f"{_infer_type(value[0])}_ARRAY"
+        return {"@type": element_type, "value": [convert_cell(v) for v in value]}
+
+    type_name = declared_type or _infer_type(value)
+    converted = convert_cell(value)
+    # Coerce numerics to the declared type so 40 for a DECIMAL becomes 40.0.
+    if type_name == "DECIMAL" and isinstance(converted, int) and not isinstance(converted, bool):
+        converted = float(converted)
+    return {"@type": type_name, "value": converted}

daitum_test/errors.py

@@ -0,0 +1,59 @@
+# Copyright 2026 Daitum
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Exception hierarchy for daitum-test."""
+
+
+class DaitumTestError(Exception):
+    """Base class for all daitum-test errors."""
+
+
+class EvaluatorNotFoundError(DaitumTestError):
+    """The evaluator jar or a usable Java runtime could not be located."""
+
+
+class ContractError(DaitumTestError):
+    """The evaluator rejected the request (exit 2), or it was invalid pre-flight.
+
+    This signals a bug in daitum-test or bad caller input — never a model error.
+    Model errors are returned on the :class:`~daitum_test.result.EvaluationResult`.
+    """
+
+
+class EvaluatorCrashError(DaitumTestError):
+    """The evaluator crashed unexpectedly (exit 3 or an unrecognised exit code)."""
+
+
+class ModelInspectionError(DaitumTestError):
+    """The model definition could not be read, so typed conversion is unavailable."""
+
+
+class DataConversionError(DaitumTestError):
+    """Input data could not be converted to the evaluator's JSON encoding."""
+
+
+class UnknownRunError(DaitumTestError):
+    """A run id was not present in the evaluation response."""
+
+
+class UnknownTableError(DaitumTestError):
+    """A table id was not present in a run's results."""
+
+
+class UnknownFieldError(DaitumTestError):
+    """A field id was not present in a table's results."""
+
+
+class UnknownNamedValueError(DaitumTestError):
+    """A named value was not present in a run's results."""