dstrack 0.1.0__tar.gz → 0.2.0__tar.gz

{dstrack-0.1.0 → dstrack-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dstrack
-Version: 0.1.0
+Version: 0.2.0
 Summary: A Python package for versioning and monitoring dataset changes throughout the machine learning lifecycle.
 Keywords: dataset,versioning,monitoring,machine learning,mlops,data science
 Author: Leonardo Ayala
@@ -19,8 +19,10 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: rich>=15.0.0
 Requires-Dist: typer>=0.26.8
+Requires-Dist: reportlab>=4.2 ; extra == 'report'
 Requires-Python: >=3.11
 Project-URL: GitHub, https://github.com/leoyala/dstrack
+Provides-Extra: report
 Description-Content-Type: text/markdown
 
 # dstrack
@@ -29,7 +31,7 @@ Description-Content-Type: text/markdown
 [![codecov](https://codecov.io/github/leoyala/dstrack/graph/badge.svg?token=DEKCE4LR88)](https://codecov.io/github/leoyala/dstrack)
 
 <p align="center">
-  <img src="docs/assets/dstrack-logo.png" width="200" alt="dstrack logo">
+  <img src="src/dstrack/assets/dstrack-logo.png" width="200" alt="dstrack logo">
 </p>
 
 
@@ -39,6 +41,12 @@ A Python package for versioning and monitoring dataset changes throughout the ma
   <img src="docs/assets/cli.gif" alt="CLI example">
 </p>
 
+
+<figure markdown="span">
+<img src="src/dstrack/assets/diff-report.png" alt="PDF Diff report">
+<figcaption>Exemplary PDF report (1st page only)</figcaption>
+</figure>
+
 ## Overview
 
 `dstrack` helps data scientists and ML engineers track how datasets evolve over time, catching schema drift, distribution shifts, and unexpected mutations before they silently break pipelines or degrade model performance.
@@ -109,15 +117,37 @@ Each snapshot captures the file's schema, a content fingerprint, and per-column
 statistics. See the [Getting Started guide](https://leoyala.github.io/dstrack/getting_started/)
 for options such as `--name`, `--reader`, and `--dataset-id`.
 
+**4. See what changed** - `dstrack log` shows *that* a dataset changed;
+`dstrack diff` shows *what* changed:
+
+```bash
+dstrack diff data.csv
+```
+
+The two snapshots are shown side by side, with the schema changes, the dataset's own
+numbers, and every column whose statistics moved, each colored by how much it should
+worry you. Add `--json` for a pipeline to read, or `--pdf report.pdf` for a formatted
+report to share (needs the `report` extra).
+
+It is a library too, so a comparison can be done entirely from Python:
+
+```python
+from dstrack.diff import diff_snapshots
+
+result = diff_snapshots(old_payload, new_payload)
+print(result.severity, result.summary)
+```
+
 ## Features
 
 - **Dataset versioning** - snapshot a dataset and track its lineage across pipeline stages
 - **Rich snapshots** - schema hash, content fingerprint, and per-column statistics (ranges, null rates, and more)
+- **Snapshot comparison** - schema, statistics and distribution-shift diffs, in the terminal, as JSON, or as a PDF report
 - **CSV out of the box** - pure standard-library reader, no heavy dependencies
 - **Lightweight CLI** - a small, git-like local store you can commit alongside your code
 
 ## Roadmap
 
-Change detection and drift monitoring are on the way - comparing snapshots, surfacing
-schema and distribution shifts, and failing CI on drift. See the
-[roadmap](docs/roadmap.md) for what's planned.
+Drift monitoring in CI is next - comparing a working file against its latest snapshot
+and failing the build when data drifts. See the [roadmap](docs/roadmap.md) for what's
+planned.

{dstrack-0.1.0 → dstrack-0.2.0}/README.md

@@ -4,7 +4,7 @@
 [![codecov](https://codecov.io/github/leoyala/dstrack/graph/badge.svg?token=DEKCE4LR88)](https://codecov.io/github/leoyala/dstrack)
 
 <p align="center">
-  <img src="docs/assets/dstrack-logo.png" width="200" alt="dstrack logo">
+  <img src="src/dstrack/assets/dstrack-logo.png" width="200" alt="dstrack logo">
 </p>
 
 
@@ -14,6 +14,12 @@ A Python package for versioning and monitoring dataset changes throughout the ma
   <img src="docs/assets/cli.gif" alt="CLI example">
 </p>
 
+
+<figure markdown="span">
+<img src="src/dstrack/assets/diff-report.png" alt="PDF Diff report">
+<figcaption>Exemplary PDF report (1st page only)</figcaption>
+</figure>
+
 ## Overview
 
 `dstrack` helps data scientists and ML engineers track how datasets evolve over time, catching schema drift, distribution shifts, and unexpected mutations before they silently break pipelines or degrade model performance.
@@ -84,15 +90,37 @@ Each snapshot captures the file's schema, a content fingerprint, and per-column
 statistics. See the [Getting Started guide](https://leoyala.github.io/dstrack/getting_started/)
 for options such as `--name`, `--reader`, and `--dataset-id`.
 
+**4. See what changed** - `dstrack log` shows *that* a dataset changed;
+`dstrack diff` shows *what* changed:
+
+```bash
+dstrack diff data.csv
+```
+
+The two snapshots are shown side by side, with the schema changes, the dataset's own
+numbers, and every column whose statistics moved, each colored by how much it should
+worry you. Add `--json` for a pipeline to read, or `--pdf report.pdf` for a formatted
+report to share (needs the `report` extra).
+
+It is a library too, so a comparison can be done entirely from Python:
+
+```python
+from dstrack.diff import diff_snapshots
+
+result = diff_snapshots(old_payload, new_payload)
+print(result.severity, result.summary)
+```
+
 ## Features
 
 - **Dataset versioning** - snapshot a dataset and track its lineage across pipeline stages
 - **Rich snapshots** - schema hash, content fingerprint, and per-column statistics (ranges, null rates, and more)
+- **Snapshot comparison** - schema, statistics and distribution-shift diffs, in the terminal, as JSON, or as a PDF report
 - **CSV out of the box** - pure standard-library reader, no heavy dependencies
 - **Lightweight CLI** - a small, git-like local store you can commit alongside your code
 
 ## Roadmap
 
-Change detection and drift monitoring are on the way - comparing snapshots, surfacing
-schema and distribution shifts, and failing CI on drift. See the
-[roadmap](docs/roadmap.md) for what's planned.
+Drift monitoring in CI is next - comparing a working file against its latest snapshot
+and failing the build when data drifts. See the [roadmap](docs/roadmap.md) for what's
+planned.

dstrack-0.2.0/pyproject.toml

@@ -0,0 +1,124 @@
+[project]
+name = "dstrack"
+version = "0.2.0"
+description = "A Python package for versioning and monitoring dataset changes throughout the machine learning lifecycle."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "dataset",
+    "versioning",
+    "monitoring",
+    "machine learning",
+    "mlops",
+    "data science",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "rich>=15.0.0",
+    "typer>=0.26.8",
+]
+
+[[project.authors]]
+name = "Leonardo Ayala"
+
+[project.optional-dependencies]
+report = ["reportlab>=4.2"]
+
+[project.urls]
+GitHub = "https://github.com/leoyala/dstrack"
+
+[project.scripts]
+dstrack = "dstrack._cli:app"
+dstrack-benchmark = "dstrack._benchmark:app"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "C4",
+    "PERF",
+    "RUF",
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "B",
+    "S101",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+docstring-code-format = true
+quote-style = "double"
+
+[tool.mypy]
+files = ["src"]
+python_version = "3.11"
+strict = true
+show_error_codes = true
+warn_unreachable = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+enable_error_code = [
+    "ignore-without-code",
+    "redundant-expr",
+    "truthy-bool",
+]
+
+[[tool.mypy.overrides]]
+module = [
+    "numpy.*",
+    "pandas.*",
+    "reportlab.*",
+    "sklearn.*",
+]
+ignore_missing_imports = true
+
+[tool.coverage.run]
+omit = ["sample_data.py"]
+
+[tool.codespell]
+ignore-words-list = "nd,hist,ans"
+skip = "*.lock,*.csv,*.parquet,./data,./datasets"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "mkdocstrings-python>=2.0.5",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "zensical>=0.0.50",
+]

dstrack-0.1.0/pyproject.toml → dstrack-0.2.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dstrack"
-version = "0.1.0"
+version = "0.2.0"
 description = "A Python package for versioning and monitoring dataset changes throughout the machine learning lifecycle."
 readme = "README.md"
 license = "MIT"
@@ -28,6 +28,11 @@ dependencies = [
     "typer>=0.26.8",
 ]
 
+[project.optional-dependencies]
+# PDF reporting only. Kept out of the base install so the core stays as
+# dependency-light as it is: most runs never write a report.
+report = ["reportlab>=4.2"]
+
 [project.urls]
 GitHub = "https://github.com/leoyala/dstrack"
 
@@ -36,7 +41,7 @@ dstrack = "dstrack._cli:app"
 dstrack-benchmark = "dstrack._benchmark:app"
 
 [build-system]
-requires = ["uv_build>=0.11.28,<0.12.0"]
+requires = ["uv_build>=0.11.28,<0.13.0"]
 build-backend = "uv_build"
 
 # -----------------------------------------------------------------------------
@@ -93,10 +98,18 @@ enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
 module = [
     "numpy.*",
     "pandas.*",
+    "reportlab.*",
     "sklearn.*",
 ]
 ignore_missing_imports = true
 
+# -----------------------------------------------------------------------------
+# coverage
+# -----------------------------------------------------------------------------
+[tool.coverage.run]
+# Manual helper for trying out `dstrack diff`; deliberately untested.
+omit = ["sample_data.py"]
+
 # -----------------------------------------------------------------------------
 # codespell: spell-checking for code, docstrings, and docs
 # -----------------------------------------------------------------------------

{dstrack-0.1.0 → dstrack-0.2.0}/src/dstrack/_cli.py

@@ -6,6 +6,7 @@ from typing import Annotated
 import typer
 
 from dstrack import __version__, console
+from dstrack._diff import diff
 from dstrack._log import log
 from dstrack._store_template import STORE_TEMPLATE, materialize
 from dstrack._track import track
@@ -95,6 +96,13 @@ app.command(
     "or its path."
 )(log)
 
+app.command(
+    help="Compare two snapshots and show what changed between them, side by "
+    "side. Each argument may be a snapshot id, a dataset id, or the path to a "
+    "tracked dataset; given one, it is compared against the snapshot it "
+    "succeeded."
+)(diff)
+
 
 @app.command(help="Print package version.")
 def version() -> None:

dstrack-0.2.0/src/dstrack/_diff.py

@@ -0,0 +1,235 @@
+"""The ``dstrack diff`` command: compare two snapshots of a dataset."""
+
+import json
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dstrack import cache, console
+from dstrack._diff_render import render_diff
+from dstrack._resolve import ensure_index, resolve_pair
+from dstrack.diff import PRESETS, DiffOptions, SnapshotDiff, diff_snapshots, preset
+from dstrack.errors import (
+    AmbiguousSnapshotError,
+    DatasetNotFoundError,
+    IncompatibleSnapshotError,
+    MissingDependencyError,
+    SnapshotNotFoundError,
+    StoreCorruptionError,
+    StoreNotFoundError,
+)
+from dstrack.paths import resolve_store_root
+
+# Failures that mean "what you asked for is not in the store, or is not
+# readable", all of which are reported the same way: a message, and exit 1.
+_USER_ERRORS = (
+    AmbiguousSnapshotError,
+    DatasetNotFoundError,
+    IncompatibleSnapshotError,
+    SnapshotNotFoundError,
+    StoreCorruptionError,
+    ValueError,
+    OSError,
+    sqlite3.DatabaseError,
+)
+
+
+def diff(
+    refs: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="Snapshots to compare: a snapshot id (in full or by its "
+            "leading characters), a dataset id, or the path to a tracked "
+            "dataset file. Given one, it is compared against the snapshot it "
+            "succeeded; given two, the first is the baseline.",
+        ),
+    ] = None,
+    from_ref: Annotated[
+        str | None,
+        typer.Option(
+            "--from",
+            help="Baseline to compare against. Alone, the dataset's latest "
+            "snapshot is compared to it.",
+        ),
+    ] = None,
+    to_ref: Annotated[
+        str | None,
+        typer.Option(
+            "--to",
+            help="Snapshot to compare. Alone, it is compared against the one "
+            "it succeeded.",
+        ),
+    ] = None,
+    sensitivity: Annotated[
+        str,
+        typer.Option(
+            "--sensitivity",
+            help="How much movement counts as significant: low, normal, or high.",
+        ),
+    ] = "normal",
+    show_all: Annotated[
+        bool,
+        typer.Option("--all", help="Include columns and metrics that did not change."),
+    ] = False,
+    oneline: Annotated[
+        bool,
+        typer.Option("--oneline", help="Condense the comparison to a single line."),
+    ] = False,
+    as_json: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Print the comparison as JSON instead of a table. Implies a "
+            "non-interactive run, so pass `--yes` in scripts.",
+        ),
+    ] = False,
+    pdf: Annotated[
+        Path | None,
+        typer.Option(
+            "--pdf",
+            dir_okay=False,
+            writable=True,
+            help="Also write a PDF report of the comparison to this path. "
+            "Needs the `report` extra: pip install 'dstrack[report]'.",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Build the snapshot index without asking, if it does not exist yet.",
+        ),
+    ] = False,
+    rebuild: Annotated[
+        bool,
+        typer.Option(
+            "--rebuild",
+            help="Discard the snapshot index and rebuild it from the dataset logs.",
+        ),
+    ] = False,
+    root: Annotated[
+        Path | None,
+        typer.Option(
+            "--root",
+            help="Path root a REF path is made relative to, matching the one "
+            "`dstrack track` recorded it with. Defaults to the store root (the "
+            "directory containing .dstrack/). Ignored for a REF that is an id.",
+        ),
+    ] = None,
+) -> None:
+    """Compare two snapshots and report what changed between them."""
+    options = _options(sensitivity)
+
+    # Locate the .dstrack/ store; without one there is nothing to compare.
+    try:
+        store_root = resolve_store_root()
+    except StoreNotFoundError as e:
+        console.error(str(e))
+        raise typer.Exit(code=1) from e
+
+    # Under --json the only thing on stdout may be the document itself, so the
+    # index cannot be offered interactively: without one, --yes or --rebuild
+    # must be given, or the request is rejected.
+    ensure_index(store_root, yes=yes, rebuild=rebuild, quiet=as_json)
+
+    try:
+        # Sync before resolving: the index does not travel with the repository,
+        # so a snapshot taken elsewhere is only visible once its log is read.
+        reason = cache.sync(store_root)
+        if reason is not None and not as_json:
+            console.warning(f"Rebuilt the snapshot index: {reason}.")
+
+        old, new = resolve_pair(
+            refs or [],
+            from_ref=from_ref,
+            to_ref=to_ref,
+            store_root=store_root,
+            root=root,
+        )
+        result = diff_snapshots(
+            old.payload,
+            new.payload,
+            options=options,
+            old_dataset_id=old.dataset_id,
+            new_dataset_id=new.dataset_id,
+        )
+    except _USER_ERRORS as e:
+        console.error(str(e))
+        raise typer.Exit(code=1) from e
+
+    if pdf is not None and not _write_pdf(result, pdf, quiet=as_json):
+        raise typer.Exit(code=1)
+
+    if as_json:
+        # Deliberately not `console.display`: the document is data, and rich
+        # would wrap and highlight it into something no parser accepts.
+        print(json.dumps(result.to_dict(), indent=2))
+        return
+
+    if not result.same_dataset:
+        console.warning("Comparing snapshots from two different datasets.")
+
+    console.display(
+        render_diff(
+            result,
+            width=console.width(),
+            now=datetime.now(UTC),
+            oneline=oneline,
+            show_unchanged=show_all,
+        )
+    )
+
+
+def _options(sensitivity: str) -> DiffOptions:
+    """Return the thresholds a named sensitivity stands for.
+
+    Args:
+        sensitivity: The preset name, as the user gave it.
+
+    Returns:
+        Its thresholds.
+
+    Raises:
+        typer.BadParameter: If no preset goes by that name. Raised rather than
+            reported, so the failure reads like any other bad option.
+    """
+    try:
+        return preset(sensitivity)
+    except KeyError as e:
+        known = ", ".join(sorted(PRESETS))
+        raise typer.BadParameter(
+            f"Unknown sensitivity {sensitivity!r}. Choose one of: {known}."
+        ) from e
+
+
+def _write_pdf(result: SnapshotDiff, path: Path, *, quiet: bool) -> bool:
+    """Write the PDF report, reporting a failure rather than raising it.
+
+    The reporting module is imported here rather than at the top of the file
+    because it needs an optional dependency: importing it eagerly would make
+    every `dstrack diff` pay for a feature most runs do not use, and would turn
+    a missing extra into an import error on an unrelated command.
+
+    Args:
+        result: The comparison to report.
+        path: Where to write the PDF.
+        quiet: Suppress the success message, for a run whose stdout is data.
+
+    Returns:
+        Whether the report was written.
+    """
+    from dstrack._diff_report import write_pdf_report
+
+    try:
+        write_pdf_report(result, path, now=datetime.now(UTC))
+    except (MissingDependencyError, OSError) as e:
+        console.error(str(e))
+        return False
+
+    if not quiet:
+        console.success(f"Wrote the comparison report to {path}")
+    return True