pacioliscube 0.1.2__py3-none-any.whl

pacioliscube/__init__.py

@@ -0,0 +1,11 @@
+"""An open IBM Planning Analytics budgeting model and an offline engine for it."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _installed_version
+
+try:
+    __version__ = _installed_version("pacioliscube")
+except PackageNotFoundError:  # running from a source tree without installation
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

pacioliscube/cli.py

@@ -0,0 +1,320 @@
+"""The command line, being the way a shell script or a CI job drives this package.
+
+Three subcommands. ``validate`` reports what is structurally wrong with a model
+tree, ``calculate`` prints the value at named cells, and ``report`` prints a
+small profit and loss. Every run reads: nothing here writes a file, touches a
+network, or changes the model it is pointed at.
+
+Argument handling and the three subcommands live here. The statement the report
+prints is in report.py and reading a directory of CSV input is in data.py, so
+this module is the part a reader consults for what the arguments mean and which
+exit code a failure takes.
+
+Exit codes, which a shell script or a CI job can rely on:
+
+0   the command finished and found nothing wrong
+1   a usage or input error, being a directory that is not there, a CSV that
+    cannot be read, a cell reference that cannot be parsed, or a model the
+    report subcommand does not fit
+2   the model is not sound: it does not load, validation reports at least one
+    error severity finding, or a fault the structural checks do not reach
+    surfaces while a figure is being calculated. Every subcommand validates
+    before it calculates, because a figure taken from a structurally broken
+    model is worse than no figure at all
+3   a calculation failed, which is a division by zero, a circular reference, or
+    any other EvaluationError
+
+Warnings never change the exit code. A warning is a finding the engine cannot
+prove is wrong, so failing a build on one would make the check useless.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from decimal import Decimal
+from pathlib import Path
+from typing import Iterator, Optional, Sequence
+
+from pacioliscube import __version__, report
+from pacioliscube.data import load_data
+from pacioliscube.errors import (
+    EXIT_CALCULATION,
+    EXIT_INVALID_MODEL,
+    EXIT_OK,
+    EXIT_USAGE,
+    CliError,
+    element_or_error,
+)
+from pacioliscube.evaluate import CellStore, EvaluationError, consolidate_many, evaluate
+from pacioliscube.model import Cube, Model, ModelError, load_model
+from pacioliscube.validate import ERROR, Finding, validate_model
+
+DEFAULT_MODEL_ROOT = "model"
+
+
+def _directory(argument: str, what: str) -> Path:
+    path = Path(argument)
+    if not path.is_dir():
+        raise CliError(EXIT_USAGE, f"{path}: there is no {what} directory there")
+    return path
+
+
+def _model_root(args: argparse.Namespace) -> Path:
+    """The model directory, given as the positional or left at its default."""
+    return _directory(args.model_dir or DEFAULT_MODEL_ROOT, "model")
+
+
+def _load(root: Path) -> Model:
+    try:
+        return load_model(root)
+    except ModelError as error:
+        raise CliError(EXIT_INVALID_MODEL, str(error)) from error
+    except UnicodeDecodeError as error:
+        # A decode error carries the bytes and not the path, and the loader does
+        # not say which of the files it opened was being read, so the message
+        # reports the tree and the byte that stopped it.
+        raise CliError(
+            EXIT_INVALID_MODEL,
+            f"{root}: a file in the model tree is not UTF-8 text ({error}). "
+            "Every file of a model tree is read as UTF-8",
+        ) from error
+    except OSError as error:
+        raise CliError(
+            EXIT_INVALID_MODEL, f"{root}: the model could not be read, {error}"
+        ) from error
+
+
+def _cube(model: Model, name: str) -> Cube:
+    for cube in model.cubes.values():
+        if cube.name.casefold() == name.casefold():
+            return cube
+    raise CliError(
+        EXIT_USAGE,
+        f"no cube named {name!r} in model {model.name!r}. "
+        f"The model holds {', '.join(model.cubes) or 'no cubes'}",
+    )
+
+
+def _format_finding(finding: Finding) -> str:
+    return f"{finding.severity} {finding.code} {finding.location}: {finding.message}"
+
+
+def _summary(errors: int, warnings: int) -> str:
+    return (
+        f"{errors} {'error' if errors == 1 else 'errors'}, "
+        f"{warnings} {'warning' if warnings == 1 else 'warnings'}"
+    )
+
+
+def _refuse_broken_model(model: Model) -> None:
+    """Stop calculate and report before they read a model that cannot be right."""
+    errors = [finding for finding in validate_model(model) if finding.severity == ERROR]
+    if not errors:
+        return
+    for finding in errors:
+        print(_format_finding(finding), file=sys.stderr)
+    count = f"{len(errors)} {'error' if len(errors) == 1 else 'errors'}"
+    raise CliError(
+        EXIT_INVALID_MODEL,
+        f"the model has {count}, so nothing was calculated. "
+        "Run the validate subcommand for the findings in full",
+    )
+
+
+def _evaluate(model: Model, store: CellStore) -> CellStore:
+    try:
+        return evaluate(model, store)
+    except EvaluationError as error:
+        raise CliError(EXIT_CALCULATION, str(error)) from error
+    except ModelError as error:
+        # Validation has already passed, so a model error at this point is a
+        # defect the structural checks do not reach rather than a bad argument.
+        raise CliError(EXIT_INVALID_MODEL, str(error)) from error
+
+
+def _values(
+    model: Model, store: CellStore, cells: Sequence[tuple[str, tuple[str, ...]]]
+) -> Iterator[Decimal]:
+    try:
+        yield from consolidate_many(model, store, cells)
+    except EvaluationError as error:
+        raise CliError(EXIT_CALCULATION, str(error)) from error
+    except ModelError as error:
+        # The same reasoning as _evaluate, and the same exit code for the same
+        # exception. The coordinate reached here has already been resolved
+        # element by element against the model, so what is left is a fault in
+        # the model rather than a bad argument.
+        raise CliError(EXIT_INVALID_MODEL, str(error)) from error
+
+
+def _parse_cell(model: Model, text: str) -> tuple[str, tuple[str, ...]]:
+    """Turn CUBE:element,element into a cube name and a canonical coordinate."""
+    cube_name, separator, coordinate_text = text.partition(":")
+    if not separator or not cube_name.strip() or not coordinate_text.strip():
+        raise CliError(
+            EXIT_USAGE,
+            f"cell reference {text!r} is not in the form CUBE:element,element,...",
+        )
+    cube = _cube(model, cube_name.strip())
+    names = [part.strip() for part in coordinate_text.split(",")]
+    if not all(names):
+        raise CliError(EXIT_USAGE, f"cell reference {text!r} has an empty element name")
+    if len(names) != len(cube.dimensions):
+        raise CliError(
+            EXIT_USAGE,
+            f"cell reference {text!r} gives {len(names)} elements for cube {cube.name!r}, "
+            f"which takes {len(cube.dimensions)}, being {', '.join(cube.dimensions)}",
+        )
+    coordinate = tuple(
+        element_or_error(model, dimension, name, EXIT_USAGE)
+        for dimension, name in zip(cube.dimensions, names)
+    )
+    return cube.name, coordinate
+
+
+def _plain(value: Decimal) -> str:
+    """A Decimal in full, never in exponent form and never through a float."""
+    text = format(value, "f")
+    if "." in text:
+        text = text.rstrip("0").rstrip(".")
+    return text
+
+
+def _validate_command(args: argparse.Namespace) -> int:
+    model = _load(_model_root(args))
+    findings = validate_model(model)
+    errors = [finding for finding in findings if finding.severity == ERROR]
+    warnings = [finding for finding in findings if finding.severity != ERROR]
+    for finding in errors + warnings:
+        print(_format_finding(finding))
+    print(_summary(len(errors), len(warnings)))
+    return EXIT_INVALID_MODEL if errors else EXIT_OK
+
+
+def _calculate_command(args: argparse.Namespace) -> int:
+    model = _load(_model_root(args))
+    _refuse_broken_model(model)
+    data = _directory(args.data, "data")
+    # Cell references are parsed before the CSVs are read so that a typo costs
+    # a second rather than a full load and evaluation.
+    cells = [_parse_cell(model, text) for text in args.cell]
+    store = _evaluate(model, load_data(model, data))
+    values = _values(model, store, cells)
+    for (cube, coordinate), value in zip(cells, values):
+        print(f"{cube}:{','.join(coordinate)} = {_plain(value)}")
+    return EXIT_OK
+
+
+def _report_command(args: argparse.Namespace) -> int:
+    model = _load(_model_root(args))
+    _refuse_broken_model(model)
+    data = _directory(args.data, "data")
+    cube = _cube(model, report.REPORT_CUBE)
+    selections = report.rows(model, cube, args.year, args.version)
+    store = _evaluate(model, load_data(model, data))
+    cells = [
+        (cube.name, tuple(selection[dimension] for dimension in cube.dimensions))
+        for selection in selections
+    ]
+    values = list(_values(model, store, cells))
+    for line in report.lines(cube, selections, values):
+        print(line)
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pacioliscube",
+        description="Validate, calculate and report on a Planning Analytics model tree. "
+        "Reads the model and its data, never writes.",
+    )
+    parser.add_argument("--version", action="version", version=f"pacioliscube {__version__}")
+    subcommands = parser.add_subparsers(dest="command", metavar="SUBCOMMAND", required=True)
+
+    def with_model_dir(subparser: argparse.ArgumentParser) -> argparse.ArgumentParser:
+        subparser.add_argument(
+            "model_dir",
+            nargs="?",
+            default=None,
+            metavar="MODEL_DIR",
+            help=f"the directory holding tm1project.json, {DEFAULT_MODEL_ROOT} by default",
+        )
+        return subparser
+
+    validate = with_model_dir(
+        subcommands.add_parser("validate", help="report structural findings in a model")
+    )
+    validate.set_defaults(handler=_validate_command)
+
+    calculate = with_model_dir(
+        subcommands.add_parser("calculate", help="print the value at one or more cells")
+    )
+    calculate.add_argument(
+        "--data", required=True, metavar="DIR", help="directory of long format CSV input"
+    )
+    calculate.add_argument(
+        "--cell",
+        required=True,
+        action="append",
+        metavar="CUBE:ELEMENT,...",
+        help="a cell to print, given once per cell, as CUBE:element,element,...",
+    )
+    calculate.set_defaults(handler=_calculate_command)
+
+    report_parser = with_model_dir(
+        subcommands.add_parser(
+            "report",
+            help="print a profit and loss for a year and version",
+            description="Print the group profit and loss for one year and version, at the FY "
+            "period and every cost centre. A line that is taken off the result below it, being "
+            "direct costs, employment costs, overheads and depreciation, prints in brackets, as "
+            "does any figure that comes out negative, so the column reads in the direction it "
+            "adds. Each line is rounded to whole dollars on its own, so a subtotal can sit a "
+            "dollar away from the lines above it: in the shipped budget, EBITDA less "
+            "depreciation prints as 18,684,639 while EBIT prints as 18,684,640.",
+        )
+    )
+    report_parser.add_argument(
+        "--data", required=True, metavar="DIR", help="directory of long format CSV input"
+    )
+    report_parser.add_argument(
+        "--year", required=True, metavar="Y", help="an element of the Year dimension"
+    )
+    report_parser.add_argument(
+        "--version", required=True, metavar="V", help="an element of the Version dimension"
+    )
+    report_parser.set_defaults(handler=_report_command)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(list(sys.argv[1:] if argv is None else argv))
+    except SystemExit as stop:
+        # argparse has already written its own message. It exits 0 for --help
+        # and --version and 2 for a bad argument, so only the codes change here.
+        return EXIT_OK if stop.code in (0, None) else EXIT_USAGE
+    try:
+        return args.handler(args)
+    except CliError as error:
+        print(f"pacioliscube: {error}", file=sys.stderr)
+        return error.code
+    except EvaluationError as error:  # a backstop: a command line should not traceback
+        print(f"pacioliscube: {error}", file=sys.stderr)
+        return EXIT_CALCULATION
+    except ModelError as error:
+        print(f"pacioliscube: {error}", file=sys.stderr)
+        return EXIT_INVALID_MODEL
+    except (OSError, UnicodeDecodeError) as error:
+        # Another backstop. The places that read a file map their own failures,
+        # because only they know whether the file was model source or input, so
+        # anything arriving here is a path this module has not thought about and
+        # takes the input error code.
+        print(f"pacioliscube: {error}", file=sys.stderr)
+        return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pacioliscube/data.py

@@ -0,0 +1,177 @@
+"""Read long format CSV input into cube coordinates, a file or a directory at a time.
+
+The engine reads the same synthetic CSV files that the TurboIntegrator
+processes read on a real server. A row carries one leading column per cube
+dimension, in the cube's dimension order, then a value column. Every row is
+checked before it is used, and every error names the file and the row.
+
+``load_csv`` and ``load_into_store`` read one file into one cube. ``load_data``
+reads a whole directory, which is what the command line points at, and decides
+which cube each file feeds.
+"""
+
+from __future__ import annotations
+
+import csv
+from decimal import Decimal
+from pathlib import Path
+from typing import Iterator
+
+from pacioliscube.errors import EXIT_USAGE, CliError
+from pacioliscube.evaluate import CellStore
+from pacioliscube.model import Cube, Model, ModelError
+from pacioliscube.rules import decimal_or_raise
+
+Coordinate = tuple[str, ...]
+
+# The stem of a data file names the cube it feeds. The shipped example files are
+# listed rather than derived, because pnl-direct is not spelled like the cube it
+# loads. A stem that matches a cube name is taken as well, which is how a model
+# built for a test feeds cubes this map has never heard of, and load_data
+# refuses the case that makes the fallback dangerous: two files, one cube.
+CUBE_BY_STEM = {
+    "drivers": "Drivers",
+    "workforce": "Workforce",
+    "revenue": "Revenue",
+    "capex": "Capex",
+    "pnl-direct": "PnL",
+}
+
+
+def load_csv(path: Path, cube: Cube, model: Model) -> Iterator[tuple[Coordinate, Decimal]]:
+    """Yield one coordinate and value per data row of a long format CSV."""
+    path = Path(path)
+    if not path.is_file():
+        raise ModelError(f"{path}: file not found")
+    width = len(cube.dimensions) + 1
+    with path.open("r", encoding="utf-8-sig", newline="") as handle:
+        reader = csv.reader(handle)
+        try:
+            header = next(reader)
+        except StopIteration:
+            raise ModelError(f"{path}: the file is empty, expected a header row") from None
+        if len(header) != width:
+            raise ModelError(
+                f"{path} row 1: the header has {len(header)} columns but cube {cube.name!r} "
+                f"needs {width}, being {', '.join(cube.dimensions)} then a value"
+            )
+        seen: dict[Coordinate, tuple[Decimal, int]] = {}
+        for number, row in enumerate(reader, start=2):
+            if not row or all(field.strip() == "" for field in row):
+                continue
+            if len(row) != width:
+                raise ModelError(
+                    f"{path} row {number}: {len(row)} columns, expected {width}"
+                )
+            coordinate = []
+            for position, field in enumerate(row[:-1]):
+                dimension = cube.dimensions[position]
+                element = field.strip()
+                try:
+                    hierarchy = model.hierarchy(dimension)
+                    canonical = hierarchy.resolve(element)
+                    if not hierarchy.is_leaf(canonical):
+                        raise ModelError(
+                            f"{dimension}: element {canonical!r} is consolidated and cannot hold input"
+                        )
+                    coordinate.append(canonical)
+                except ModelError as error:
+                    raise ModelError(f"{path} row {number}: {error}") from None
+            text = row[-1].strip()
+            value = decimal_or_raise(text, f"{path} row {number}", ModelError, "value ")
+            if not value.is_finite():
+                raise ModelError(
+                    f"{path} row {number}: value {text!r} is not a finite number"
+                )
+            cell = tuple(coordinate)
+            previous = seen.get(cell)
+            if previous is not None and previous[0] != value:
+                raise ModelError(
+                    f"{path} row {number}: conflicting value for {cube.name!r} "
+                    f"at {list(cell)}; first supplied on row {previous[1]}"
+                )
+            if previous is not None:
+                continue
+            seen[cell] = (value, number)
+            yield cell, value
+
+
+def load_into_store(model: Model, cube_name: str, path: Path, store) -> int:
+    """Load one CSV into a cell store and return how many cells it wrote."""
+    cube = model.cubes.get(cube_name)
+    if cube is None:
+        raise ModelError(f"no cube named {cube_name!r} in model {model.name!r}")
+    written = 0
+    for coordinate, value in load_csv(path, cube, model):
+        store.set(cube.name, coordinate, value)
+        written += 1
+    return written
+
+
+def cube_for_file(model: Model, path: Path) -> Cube:
+    """Which cube a data file loads into, by its stem."""
+    stem = path.stem.casefold()
+    named = CUBE_BY_STEM.get(stem)
+    if named is not None and named in model.cubes:
+        return model.cubes[named]
+    for cube in model.cubes.values():
+        if cube.name.casefold() == stem:
+            return cube
+    raise CliError(
+        EXIT_USAGE,
+        f"{path}: no cube in model {model.name!r} matches the file name {path.stem!r}",
+    )
+
+
+def load_data(model: Model, directory: Path) -> CellStore:
+    """Load every CSV in a directory into one store, one file per cube."""
+    store = CellStore()
+    try:
+        boundary = directory.resolve()
+        files = sorted(
+            path
+            for path in directory.iterdir()
+            if path.is_file() and path.suffix.casefold() == ".csv"
+        )
+    except OSError as error:
+        raise CliError(
+            EXIT_USAGE, f"{directory}: the data directory could not be read, {error}"
+        ) from error
+    if not files:
+        raise CliError(EXIT_USAGE, f"{directory}: there are no CSV files there")
+
+    # Every file is matched to its cube before any of them is read. A cell store
+    # takes the last write, so two files feeding one cube would leave the cells
+    # they share holding whichever file sorted second, and the run would print a
+    # wrong figure and exit 0. Guessing which of the two was meant is worse than
+    # saying that both are there.
+    feeding: dict[str, list[Path]] = {}
+    for path in files:
+        if not path.resolve().is_relative_to(boundary):
+            raise CliError(EXIT_USAGE, f"{path}: this file resolves outside the data directory")
+        feeding.setdefault(cube_for_file(model, path).name, []).append(path)
+    for cube_name, paths in feeding.items():
+        if len(paths) > 1:
+            raise CliError(
+                EXIT_USAGE,
+                f"cube {cube_name!r} is fed by more than one file: "
+                f"{', '.join(str(path) for path in paths)}. "
+                "Leave the one that belongs to this run in the data directory and move "
+                "the rest out",
+            )
+
+    for cube_name, paths in feeding.items():
+        path = paths[0]
+        try:
+            load_into_store(model, cube_name, path, store)
+        except ModelError as error:
+            raise CliError(EXIT_USAGE, str(error)) from error
+        except UnicodeDecodeError as error:
+            raise CliError(
+                EXIT_USAGE,
+                f"{path}: this file is not UTF-8 text ({error}). "
+                "A spreadsheet export saves as UTF-8 from its own save dialogue",
+            ) from error
+        except OSError as error:
+            raise CliError(EXIT_USAGE, f"{path}: this file could not be read, {error}") from error
+    return store

pacioliscube/errors.py

@@ -0,0 +1,31 @@
+"""The command line's failure type, its exit codes, and one model lookup.
+
+This sits apart from cli.py so that the report and the data loader can refuse a
+bad argument the way the command line does without importing the module that
+imports them. Nothing here reads a file or prints anything.
+"""
+
+from __future__ import annotations
+
+from pacioliscube.model import Model, ModelError
+
+EXIT_OK = 0
+EXIT_USAGE = 1
+EXIT_INVALID_MODEL = 2
+EXIT_CALCULATION = 3
+
+
+class CliError(Exception):
+    """An error the command line reports, carrying the exit code it maps to."""
+
+    def __init__(self, code: int, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def element_or_error(model: Model, dimension: str, name: str, code: int) -> str:
+    """Resolve an element name, taking the exit code that fits who supplied it."""
+    try:
+        return model.hierarchy(dimension).resolve(name)
+    except ModelError as error:
+        raise CliError(code, str(error)) from error