diffmonkey 1.0.0__tar.gz

diffmonkey-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RexBytes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diffmonkey-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: diffmonkey
+Version: 1.0.0
+Summary: Type-aware, key-based structural diffing of tabular datasets with human- and machine-readable reports.
+Author-email: RexBytes <pythonic@rexbytes.com>
+License: MIT License
+        
+        Copyright (c) 2026 RexBytes
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/RexBytes/diffmonkey
+Project-URL: Issues, https://github.com/RexBytes/diffmonkey/issues
+Keywords: diff,csv,tabular,compare,dataset,changes,reconciliation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cleanmonkey
+Requires-Dist: typemonkey
+Requires-Dist: datemonkey
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.0; extra == "excel"
+Provides-Extra: dsv
+Requires-Dist: dsvmonkey; extra == "dsv"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Dynamic: license-file
+
+# diffmonkey
+
+Type-aware, key-based structural diffing of tabular datasets — answer "what
+changed between last month's export and this month's?" in one call, with
+human- and machine-readable reports.
+
+diffmonkey matches rows by a key column (or composite key), compares the
+remaining columns *with type awareness* (numbers by value, dates by calendar
+date, booleans by truth, strings whitespace-normalised, nulls unified), and
+buckets the result into **added / removed / changed / unchanged** with summary
+statistics. It is built on the rexbytes ecosystem — [`typemonkey`] for type
+inference and number parsing, [`datemonkey`] for date parsing, [`cleanmonkey`]
+for whitespace and invisible-character normalisation — so it does not re-derive
+those wheels.
+
+In scope: structural comparison, change detection, change reporting. Out of
+scope: merge/reconciliation, text diffing, schema migration, version control.
+
+## Install
+
+```bash
+pip install diffmonkey            # CSV/TSV/pipe input built in
+pip install "diffmonkey[excel]"   # add .xlsx reading (openpyxl)
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+from diffmonkey import compare
+
+old = [{"id": "1", "name": "Widget", "price": "1,234"},
+       {"id": "2", "name": "Gadget", "price": "50"}]
+new = [{"id": "1", "name": "Widget", "price": "1234"},   # price reformatted, not changed
+       {"id": "3", "name": "Gizmo",  "price": "9"}]       # id 2 removed, id 3 added
+
+result = compare(old, new, key="id")
+
+print(result.summary.one_line())
+# 1 added, 1 removed, 0 changed (of 2 current), 0 unchanged
+
+print(result.to_markdown())   # human report
+result.to_dict()              # machine-readable
+result.write_csv("changes.csv")
+```
+
+`"1,234"` vs `"1234"` is **not** reported as a change — type-aware numeric
+comparison sees one number. The same applies to `"01/02/2025"` vs `"2025-01-02"`
+(dates, with a `locale` hint), `" foo "` vs `"foo"` (whitespace), and
+`None`/`""`/`"NA"` (nulls).
+
+## CLI
+
+```bash
+diffmonkey compare old.csv new.csv --key id
+diffmonkey compare old.csv new.csv --key region,sku --ignore updated_at --format markdown
+diffmonkey compare old.xlsx new.xlsx --key id --format json -o diff.json
+```
+
+Exit code is `0` when the datasets are identical and `1` when they differ —
+handy in CI and scripts.
+
+## Key options
+
+| Option | Purpose |
+|---|---|
+| `key` | Identity column, or list for a composite key |
+| `columns` / `ignore` | Restrict / exclude columns from comparison |
+| `column_map={"old":"new"}` | Handle renamed columns (avoids false add+remove) |
+| `rel_tol` / `abs_tol` | Floating-point tolerance for numeric columns |
+| `locale="us"` / `"eu"` | Disambiguate slash dates and number separators |
+| `null_equivalent` | Treat all null spellings as one value (default on) |
+| `type_aware` / `date_aware` | Toggle type/date-aware comparison |
+| `include_unchanged` | Retain unchanged rows in the result |
+| `on_duplicate` / `on_missing_key` | Policies for messy keys |
+
+## Output formats
+
+- `result.to_dict()` — JSON-serialisable structure
+- `result.to_markdown()` — report for PRs, chat, email
+- `result.to_html()` — standalone HTML diff report
+- `result.to_csv()` / `result.write_csv(path)` — one row per field change
+
+## Using with AI assistants
+
+See [`SKILL.md`](./SKILL.md) for LLM-oriented usage (decision tree, worked
+examples, anti-patterns). See [`LIMITATIONS.md`](./LIMITATIONS.md) for the
+deliberate design tradeoffs (date/locale ambiguity, null vocabulary, duplicate
+handling) so behaviour that looks surprising is not mistaken for a bug.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+[`typemonkey`]: https://pypi.org/project/typemonkey/
+[`datemonkey`]: https://pypi.org/project/datemonkey/
+[`cleanmonkey`]: https://pypi.org/project/cleanmonkey/

diffmonkey-1.0.0/README.md

@@ -0,0 +1,98 @@
+# diffmonkey
+
+Type-aware, key-based structural diffing of tabular datasets — answer "what
+changed between last month's export and this month's?" in one call, with
+human- and machine-readable reports.
+
+diffmonkey matches rows by a key column (or composite key), compares the
+remaining columns *with type awareness* (numbers by value, dates by calendar
+date, booleans by truth, strings whitespace-normalised, nulls unified), and
+buckets the result into **added / removed / changed / unchanged** with summary
+statistics. It is built on the rexbytes ecosystem — [`typemonkey`] for type
+inference and number parsing, [`datemonkey`] for date parsing, [`cleanmonkey`]
+for whitespace and invisible-character normalisation — so it does not re-derive
+those wheels.
+
+In scope: structural comparison, change detection, change reporting. Out of
+scope: merge/reconciliation, text diffing, schema migration, version control.
+
+## Install
+
+```bash
+pip install diffmonkey            # CSV/TSV/pipe input built in
+pip install "diffmonkey[excel]"   # add .xlsx reading (openpyxl)
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+from diffmonkey import compare
+
+old = [{"id": "1", "name": "Widget", "price": "1,234"},
+       {"id": "2", "name": "Gadget", "price": "50"}]
+new = [{"id": "1", "name": "Widget", "price": "1234"},   # price reformatted, not changed
+       {"id": "3", "name": "Gizmo",  "price": "9"}]       # id 2 removed, id 3 added
+
+result = compare(old, new, key="id")
+
+print(result.summary.one_line())
+# 1 added, 1 removed, 0 changed (of 2 current), 0 unchanged
+
+print(result.to_markdown())   # human report
+result.to_dict()              # machine-readable
+result.write_csv("changes.csv")
+```
+
+`"1,234"` vs `"1234"` is **not** reported as a change — type-aware numeric
+comparison sees one number. The same applies to `"01/02/2025"` vs `"2025-01-02"`
+(dates, with a `locale` hint), `" foo "` vs `"foo"` (whitespace), and
+`None`/`""`/`"NA"` (nulls).
+
+## CLI
+
+```bash
+diffmonkey compare old.csv new.csv --key id
+diffmonkey compare old.csv new.csv --key region,sku --ignore updated_at --format markdown
+diffmonkey compare old.xlsx new.xlsx --key id --format json -o diff.json
+```
+
+Exit code is `0` when the datasets are identical and `1` when they differ —
+handy in CI and scripts.
+
+## Key options
+
+| Option | Purpose |
+|---|---|
+| `key` | Identity column, or list for a composite key |
+| `columns` / `ignore` | Restrict / exclude columns from comparison |
+| `column_map={"old":"new"}` | Handle renamed columns (avoids false add+remove) |
+| `rel_tol` / `abs_tol` | Floating-point tolerance for numeric columns |
+| `locale="us"` / `"eu"` | Disambiguate slash dates and number separators |
+| `null_equivalent` | Treat all null spellings as one value (default on) |
+| `type_aware` / `date_aware` | Toggle type/date-aware comparison |
+| `include_unchanged` | Retain unchanged rows in the result |
+| `on_duplicate` / `on_missing_key` | Policies for messy keys |
+
+## Output formats
+
+- `result.to_dict()` — JSON-serialisable structure
+- `result.to_markdown()` — report for PRs, chat, email
+- `result.to_html()` — standalone HTML diff report
+- `result.to_csv()` / `result.write_csv(path)` — one row per field change
+
+## Using with AI assistants
+
+See [`SKILL.md`](./SKILL.md) for LLM-oriented usage (decision tree, worked
+examples, anti-patterns). See [`LIMITATIONS.md`](./LIMITATIONS.md) for the
+deliberate design tradeoffs (date/locale ambiguity, null vocabulary, duplicate
+handling) so behaviour that looks surprising is not mistaken for a bug.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+[`typemonkey`]: https://pypi.org/project/typemonkey/
+[`datemonkey`]: https://pypi.org/project/datemonkey/
+[`cleanmonkey`]: https://pypi.org/project/cleanmonkey/

diffmonkey-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "diffmonkey"
+version = "1.0.0"
+description = "Type-aware, key-based structural diffing of tabular datasets with human- and machine-readable reports."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "RexBytes", email = "pythonic@rexbytes.com" }]
+requires-python = ">=3.11"
+keywords = ["diff", "csv", "tabular", "compare", "dataset", "changes", "reconciliation"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "cleanmonkey",
+    "typemonkey",
+    "datemonkey",
+]
+
+[project.optional-dependencies]
+excel = ["openpyxl>=3.0"]
+dsv = ["dsvmonkey"]
+dev = ["pytest>=7.0", "pytest-cov", "hypothesis>=6.0"]
+
+[project.scripts]
+diffmonkey = "diffmonkey.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/RexBytes/diffmonkey"
+Issues   = "https://github.com/RexBytes/diffmonkey/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

diffmonkey-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

diffmonkey-1.0.0/src/diffmonkey/__init__.py

@@ -0,0 +1,49 @@
+"""diffmonkey — type-aware, key-based structural diffing of tabular datasets.
+
+Public API::
+
+    from diffmonkey import compare
+    result = compare(old_rows, new_rows, key="id")
+    print(result.summary.one_line())
+    print(result.to_markdown())
+
+``compare`` matches rows by a key column (or composite key), compares the
+remaining columns with type awareness (numbers by value, dates by calendar
+date, booleans by truth, strings whitespace-normalised, nulls unified), and
+returns a :class:`DiffResult` bucketed into added / removed / changed /
+unchanged with summary statistics and multiple report formats.
+
+See ``LIMITATIONS.md`` for deliberate design tradeoffs and ``SKILL.md`` for
+LLM-oriented usage guidance.
+"""
+
+from __future__ import annotations
+
+from .compare import compare
+from .models import (
+    DiffMonkeyError,
+    DiffResult,
+    DiffSummary,
+    DuplicateKeyError,
+    FieldChange,
+    MissingKeyError,
+    RowDiff,
+)
+from .readers import read_csv, read_excel, read_table
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "compare",
+    "DiffResult",
+    "DiffSummary",
+    "RowDiff",
+    "FieldChange",
+    "DiffMonkeyError",
+    "DuplicateKeyError",
+    "MissingKeyError",
+    "read_table",
+    "read_csv",
+    "read_excel",
+    "__version__",
+]

diffmonkey-1.0.0/src/diffmonkey/cli.py

@@ -0,0 +1,168 @@
+"""Command-line interface — a thin wrapper around :func:`diffmonkey.compare`.
+
+This module exists only to parse arguments, read input files
+(:mod:`diffmonkey.readers`), call the library, render the chosen format and
+return a process exit code. It contains no comparison logic. Exit codes:
+``0`` = no differences, ``1`` = differences found, ``2`` = usage/IO error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Sequence
+
+from . import __version__
+from .compare import compare
+from .models import DiffMonkeyError
+from .readers import read_table
+
+EXIT_NO_DIFF = 0
+EXIT_DIFF = 1
+EXIT_ERROR = 2
+
+
+def _split_csv_opt(value: str | None) -> list[str] | None:
+    if value is None:
+        return None
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
+def _parse_column_map(pairs: Sequence[str] | None) -> dict[str, str] | None:
+    if not pairs:
+        return None
+    mapping: dict[str, str] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            # ValueError (not argparse.ArgumentTypeError): this runs inside
+            # main(), not as an argparse type= callable, so it must be caught
+            # by main()'s handler and turned into exit code 2.
+            raise ValueError(f"--map expects OLD=NEW, got {pair!r}")
+        old, new = pair.split("=", 1)
+        mapping[old.strip()] = new.strip()
+    return mapping
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="diffmonkey",
+        description="Type-aware, key-based structural diff of two tabular files.",
+    )
+    parser.add_argument("--version", action="version", version=f"diffmonkey {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    cmp = sub.add_parser("compare", help="Compare two files by key column(s).")
+    cmp.add_argument("old", help="Baseline file (CSV/TSV/Excel).")
+    cmp.add_argument("new", help="Current file to compare against the baseline.")
+    cmp.add_argument(
+        "-k", "--key", required=True,
+        help="Identity column, or comma-separated columns for a composite key.",
+    )
+    cmp.add_argument("--columns", help="Comma-separated columns to compare (default: all).")
+    cmp.add_argument("--ignore", help="Comma-separated columns to exclude.")
+    cmp.add_argument(
+        "--map", action="append", metavar="OLD=NEW",
+        help="Rename an old column to a new name (repeatable).",
+    )
+    cmp.add_argument(
+        "--format", choices=["summary", "markdown", "html", "csv", "json"],
+        default="summary", help="Output format (default: summary).",
+    )
+    cmp.add_argument("-o", "--output", help="Write report to this file instead of stdout.")
+    cmp.add_argument("--rel-tol", type=float, default=1e-9, help="Numeric relative tolerance.")
+    cmp.add_argument("--abs-tol", type=float, default=0.0, help="Numeric absolute tolerance.")
+    cmp.add_argument("--locale", choices=["us", "eu"], help="Number/date locale hint.")
+    cmp.add_argument(
+        "--no-type-aware", action="store_true",
+        help="Compare every column as a normalised string.",
+    )
+    cmp.add_argument(
+        "--no-null-equivalent", action="store_true",
+        help="Do not treat different null spellings as equal.",
+    )
+    cmp.add_argument(
+        "--include-unchanged", action="store_true",
+        help="Include unchanged rows in json/markdown output.",
+    )
+    cmp.add_argument(
+        "--on-duplicate", choices=["warn", "first", "last", "error"], default="warn",
+        help="Duplicate-key policy (default: warn).",
+    )
+    cmp.add_argument(
+        "--on-missing-key", choices=["warn", "skip", "error"], default="warn",
+        help="Missing-key policy (default: warn).",
+    )
+    cmp.add_argument("--delimiter", help="Force a delimiter for DSV inputs.")
+    return parser
+
+
+def _render(result, fmt: str, *, include_unchanged: bool) -> str:
+    if fmt == "summary":
+        text = result.summary.one_line()
+        if result.warnings:
+            text += "\n" + "\n".join(f"warning: {w}" for w in result.warnings)
+        return text + "\n"
+    if fmt == "markdown":
+        return result.to_markdown()
+    if fmt == "html":
+        return result.to_html()
+    if fmt == "csv":
+        return result.to_csv()
+    if fmt == "json":
+        return json.dumps(result.to_dict(), indent=2, default=str) + "\n"
+    raise ValueError(f"unknown format {fmt!r}")  # pragma: no cover
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "compare":
+        try:
+            read_kwargs = {"delimiter": args.delimiter} if args.delimiter else {}
+            old_rows = read_table(args.old, **read_kwargs)
+            new_rows = read_table(args.new, **read_kwargs)
+        except (OSError, RuntimeError, ValueError, TypeError) as exc:
+            print(f"diffmonkey: error reading input: {exc}", file=sys.stderr)
+            return EXIT_ERROR
+
+        try:
+            result = compare(
+                old_rows,
+                new_rows,
+                key=_split_csv_opt(args.key),
+                columns=_split_csv_opt(args.columns),
+                ignore=_split_csv_opt(args.ignore),
+                column_map=_parse_column_map(args.map),
+                rel_tol=args.rel_tol,
+                abs_tol=args.abs_tol,
+                locale=args.locale,
+                type_aware=not args.no_type_aware,
+                null_equivalent=not args.no_null_equivalent,
+                include_unchanged=args.include_unchanged,
+                on_duplicate=args.on_duplicate,
+                on_missing_key=args.on_missing_key,
+            )
+        except (DiffMonkeyError, ValueError, TypeError) as exc:
+            print(f"diffmonkey: {exc}", file=sys.stderr)
+            return EXIT_ERROR
+
+        text = _render(result, args.format, include_unchanged=args.include_unchanged)
+        if args.output:
+            try:
+                with open(args.output, "w", encoding="utf-8", newline="") as fh:
+                    fh.write(text)
+            except OSError as exc:
+                print(f"diffmonkey: error writing output: {exc}", file=sys.stderr)
+                return EXIT_ERROR
+        else:
+            sys.stdout.write(text)
+
+        return EXIT_DIFF if result.has_changes() else EXIT_NO_DIFF
+
+    return EXIT_ERROR  # pragma: no cover - argparse enforces a command
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())