threeway 1.1.0__py3-none-any.whl

threeway/__init__.py

@@ -0,0 +1,3 @@
+"""Package marker; version lives here so cli.py has a single source of truth for --version."""
+
+__version__ = "1.1.0"

threeway/cli.py

@@ -0,0 +1,247 @@
+"""Entry point module: turns argv into a reconcile() call and an exit code, and
+is the one place that knows about the CI-gating exit code contract (0/1/2).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date
+from decimal import Decimal, InvalidOperation
+from typing import Any, Dict, Optional, cast
+
+from . import __version__
+from .config import ConfigError, discover_config_path, load_config, load_uom_map
+from .core import (
+    DEFAULT_CUTOFF_DAYS,
+    DEFAULT_PCT_TOLERANCE,
+    DEFAULT_QTY_TOLERANCE,
+    DEFAULT_VALUE_TOLERANCE,
+    reconcile,
+)
+from .csvio import ColumnNotFoundError, read_goods_received, read_invoices, read_purchase_orders
+from .report import render
+
+EXIT_OK = 0
+EXIT_EXCEPTIONS = 1
+EXIT_USAGE_ERROR = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="threeway",
+        description=(
+            "Reconcile purchase orders, goods received, and supplier invoices, and "
+            "report which lines disagree and why."
+        ),
+        epilog=(
+            "Exit codes: 0 = no exceptions found, 1 = one or more exceptions found "
+            "(useful for gating CI), 2 = usage or input error. "
+            "Precedence, highest first: an explicit flag, then --config (or an "
+            "auto-discovered threeway.toml/threeway.json in the current directory), "
+            "then the built-in default."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--po", required=True, help="path to the purchase orders CSV")
+    parser.add_argument("--grn", required=True, help="path to the goods received CSV")
+    parser.add_argument("--invoice", required=True, help="path to the supplier invoices CSV")
+    parser.add_argument(
+        "--qty-tolerance",
+        type=str,
+        default=None,
+        help=f"allowed quantity variance for a match (default {DEFAULT_QTY_TOLERANCE})",
+    )
+    parser.add_argument(
+        "--value-tolerance",
+        type=str,
+        default=None,
+        help=f"allowed value variance for a match (default {DEFAULT_VALUE_TOLERANCE})",
+    )
+    parser.add_argument(
+        "--pct-tolerance",
+        type=str,
+        default=None,
+        help=f"allowed invoice/PO price difference, in percent (default {DEFAULT_PCT_TOLERANCE})",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["table", "json", "csv"],
+        default="table",
+        help="output format (default table)",
+    )
+    parser.add_argument(
+        "--only-exceptions",
+        action="store_true",
+        help="show only lines with status 'exception'",
+    )
+    parser.add_argument("--output", help="write the report to this file instead of stdout")
+    parser.add_argument("--quiet", action="store_true", help="suppress the report; exit code only")
+    parser.add_argument(
+        "--uom-map",
+        help=(
+            "path to a JSON (or TOML, on Python 3.11+) file mapping units of "
+            "measure to a base unit, globally or per item code"
+        ),
+    )
+    parser.add_argument(
+        "--as-of",
+        help="ignore any row dated after this date (YYYY-MM-DD)",
+    )
+    parser.add_argument(
+        "--cutoff-days",
+        type=str,
+        default=None,
+        help=(
+            "downgrade an exception to 'check' when it is explained by a "
+            f"receipt/invoice date gap within this many days (default {DEFAULT_CUTOFF_DAYS})"
+        ),
+    )
+    parser.add_argument(
+        "--config",
+        help=(
+            "path to a JSON or TOML settings file (qty_tolerance, value_tolerance, "
+            "pct_tolerance, cutoff_days, uom_map, columns). If not given, "
+            "threeway.toml or threeway.json in the current directory is used "
+            "automatically when present."
+        ),
+    )
+    return parser
+
+
+def _resolve_decimal(
+    flag_value: Optional[str],
+    config: Dict[str, object],
+    config_key: str,
+    default: Decimal,
+    flag_name: str,
+) -> Decimal:
+    """Explicit flag > config file > built-in default."""
+    raw: object
+    if flag_value is not None:
+        raw = flag_value
+    elif config_key in config:
+        raw = config[config_key]
+    else:
+        return default
+    try:
+        # raw is a CLI string or an already-Decimalized config value; either
+        # way Decimal() itself validates it, and a bad value is caught below.
+        return Decimal(cast(Any, raw))
+    except (InvalidOperation, TypeError):
+        raise ValueError(f"{flag_name} must be a number, got {raw!r}") from None
+
+
+def _resolve_int(
+    flag_value: Optional[str],
+    config: Dict[str, object],
+    config_key: str,
+    default: int,
+    flag_name: str,
+) -> int:
+    raw: object
+    if flag_value is not None:
+        raw = flag_value
+    elif config_key in config:
+        raw = config[config_key]
+    else:
+        return default
+    try:
+        return int(Decimal(cast(Any, raw)))
+    except (InvalidOperation, TypeError, ValueError):
+        raise ValueError(f"{flag_name} must be a whole number, got {raw!r}") from None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        config_path = discover_config_path(args.config)
+        config = load_config(config_path)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE_ERROR
+
+    try:
+        qty_tolerance = _resolve_decimal(
+            args.qty_tolerance, config, "qty_tolerance", DEFAULT_QTY_TOLERANCE, "--qty-tolerance"
+        )
+        value_tolerance = _resolve_decimal(
+            args.value_tolerance,
+            config,
+            "value_tolerance",
+            DEFAULT_VALUE_TOLERANCE,
+            "--value-tolerance",
+        )
+        pct_tolerance = _resolve_decimal(
+            args.pct_tolerance, config, "pct_tolerance", DEFAULT_PCT_TOLERANCE, "--pct-tolerance"
+        )
+        cutoff_days = _resolve_int(
+            args.cutoff_days, config, "cutoff_days", DEFAULT_CUTOFF_DAYS, "--cutoff-days"
+        )
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE_ERROR
+
+    as_of = None
+    if args.as_of is not None:
+        try:
+            as_of = date.fromisoformat(args.as_of)
+        except ValueError:
+            print(
+                f"error: --as-of must be a date in YYYY-MM-DD format, got {args.as_of!r}",
+                file=sys.stderr,
+            )
+            return EXIT_USAGE_ERROR
+
+    uom_map_path = args.uom_map
+    try:
+        uom_map = load_uom_map(uom_map_path)
+        if uom_map is None and "uom_map" in config:
+            # config values are untyped external data; the shape is validated
+            # (or not) downstream in core.py exactly as it was before typing.
+            uom_map = cast(Optional[Dict[str, object]], config["uom_map"])
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE_ERROR
+
+    extra_aliases = cast(Optional[Dict[str, object]], config.get("columns"))
+
+    try:
+        po_rows = read_purchase_orders(args.po, extra_aliases=extra_aliases)
+        grn_rows = read_goods_received(args.grn, extra_aliases=extra_aliases)
+        invoice_rows = read_invoices(args.invoice, extra_aliases=extra_aliases)
+    except (ColumnNotFoundError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE_ERROR
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE_ERROR
+
+    result = reconcile(
+        po_rows,
+        grn_rows,
+        invoice_rows,
+        qty_tolerance=qty_tolerance,
+        value_tolerance=value_tolerance,
+        pct_tolerance=pct_tolerance,
+        uom_map=uom_map,
+        as_of=as_of,
+        cutoff_days=cutoff_days,
+    )
+
+    if not args.quiet:
+        output_text = render(result, args.format, only_exceptions=args.only_exceptions)
+        if args.output:
+            with open(args.output, "w", encoding="utf-8", newline="") as handle:
+                handle.write(output_text)
+        else:
+            print(output_text, end="")
+
+    exception_count = sum(1 for line in result.lines if line.status == "exception")
+    return EXIT_EXCEPTIONS if exception_count > 0 else EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

threeway/config.py

@@ -0,0 +1,116 @@
+"""Loading for the two optional structured-file inputs - the settings config
+(`--config`) and the unit-of-measure map (`--uom-map`) - kept apart from cli.py
+because parsing JSON/TOML into plain, Decimal-safe Python objects has nothing to
+do with argument handling, and apart from core.py because it is I/O.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from decimal import Decimal
+from typing import Dict, List, Optional, Union
+
+try:
+    # mypy is run with python_version = 3.9, and typeshed has no stub for
+    # tomllib below 3.11 regardless of this runtime try/except, so the import
+    # itself is unresolvable to the type checker on the pinned target version.
+    import tomllib  # type: ignore[import-not-found]
+except ImportError:  # Python < 3.11: TOML is optional, JSON always works.
+    tomllib = None
+
+# An empty tuple as an except target catches nothing; this lets the shared
+# try/except below name `_TOML_DECODE_ERRORS` unconditionally even when tomllib
+# itself is unavailable.
+_TOML_DECODE_ERRORS = (tomllib.TOMLDecodeError,) if tomllib is not None else ()
+
+CONFIG_FILENAMES = ("threeway.toml", "threeway.json")
+
+
+class ConfigError(ValueError):
+    """Raised when a config or uom-map file is missing, unreadable, or malformed.
+    Always names the file and the problem, so the CLI can surface it and exit 2."""
+
+
+JSONValue = Union[str, int, float, bool, None, Dict[str, "JSONValue"], List["JSONValue"]]
+Decimalized = Union[str, bool, None, Decimal, Dict[str, "Decimalized"], List["Decimalized"]]
+
+
+def _decimalize(value: JSONValue) -> Decimalized:
+    """Turn every int/float leaf in a parsed JSON/TOML structure into a Decimal,
+    via its string form, so a factor or tolerance read from a config file never
+    passes through a binary float. `bool` is checked first because it is a
+    subclass of `int` in Python."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return Decimal(str(value))
+    if isinstance(value, dict):
+        return {key: _decimalize(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_decimalize(item) for item in value]
+    return value
+
+
+def load_structured_file(path: str) -> Dict[str, object]:
+    """Read a JSON or TOML file (by extension) into a plain dict, with every
+    number converted to Decimal. Raises ConfigError naming the file and the
+    problem on anything that goes wrong - missing file, bad syntax, wrong type,
+    or a `.toml` file on a Python without `tomllib`."""
+    _, ext = os.path.splitext(path)
+    ext = ext.lower()
+
+    try:
+        if ext == ".toml":
+            if tomllib is None:
+                raise ConfigError(
+                    f"{path}: TOML config needs Python 3.11 or newer for tomllib. "
+                    "Use a JSON config file instead."
+                )
+            with open(path, "rb") as handle:
+                data = tomllib.load(handle)
+        elif ext == ".json":
+            with open(path, encoding="utf-8-sig") as handle:
+                data = json.load(handle)
+        else:
+            raise ConfigError(
+                f"{path}: unrecognised config format {ext or '(none)'!r}; use .json or .toml"
+            )
+    except OSError as exc:
+        raise ConfigError(f"{path}: {exc.strerror or exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{path}: invalid JSON ({exc.msg} at line {exc.lineno})") from exc
+    except _TOML_DECODE_ERRORS as exc:
+        raise ConfigError(f"{path}: invalid TOML ({exc})") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: expected a table/object at the top level")
+
+    return {key: _decimalize(item) for key, item in data.items()}
+
+
+def discover_config_path(explicit: Optional[str]) -> Optional[str]:
+    """Resolve which config file to use: an explicit `--config` path wins outright
+    (even if the file turns out not to exist - that's a load-time error, not a
+    discovery miss); otherwise look for threeway.toml then threeway.json in the
+    current directory."""
+    if explicit is not None:
+        return explicit
+    for name in CONFIG_FILENAMES:
+        if os.path.isfile(name):
+            return name
+    return None
+
+
+def load_config(path: Optional[str]) -> Dict[str, object]:
+    """Load the settings config, or return {} if there is none to load."""
+    if path is None:
+        return {}
+    return load_structured_file(path)
+
+
+def load_uom_map(path: Optional[str]) -> Optional[Dict[str, object]]:
+    """Load the uom-map file, or None if none was given."""
+    if path is None:
+        return None
+    return load_structured_file(path)