tablevalidator-databricks 0.1.4__tar.gz → 0.1.5__tar.gz

{tablevalidator_databricks-0.1.4 → tablevalidator_databricks-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tablevalidator-databricks
-Version: 0.1.4
+Version: 0.1.5
 Summary: Generates a widget-driven Databricks notebook UI on top of the table-validator package - no code required to run a comparison.
 License: MIT
 Requires-Python: >=3.9
@@ -35,6 +35,14 @@ there's nothing else to install separately.
 
 ## Usage
 
+```bash
+tablevalidator-databricks info
+```
+
+Prints a full usage guide - the steps, the three modes, what each check
+group actually does, schema-wide sweeps, the cascading-dropdown caveat,
+manual overrides, and version pinning. Start here if you're new to it.
+
 ```bash
 tablevalidator-databricks init
 ```

{tablevalidator_databricks-0.1.4 → tablevalidator_databricks-0.1.5}/README.md

@@ -21,6 +21,14 @@ there's nothing else to install separately.
 
 ## Usage
 
+```bash
+tablevalidator-databricks info
+```
+
+Prints a full usage guide - the steps, the three modes, what each check
+group actually does, schema-wide sweeps, the cascading-dropdown caveat,
+manual overrides, and version pinning. Start here if you're new to it.
+
 ```bash
 tablevalidator-databricks init
 ```

tablevalidator_databricks-0.1.5/tablevalidator_databricks/cli/main.py

@@ -0,0 +1,173 @@
+"""CLI entry point: `tablevalidator-databricks` console script."""
+
+from pathlib import Path
+
+import typer
+
+from tablevalidator_databricks.generator.generator import (
+    VALID_MODES,
+    _min_core_version,
+    generate_notebook,
+)
+
+app = typer.Typer(
+    name="tablevalidator-databricks",
+    help=(
+        "Generate a widget-driven Databricks notebook UI for table-validator. "
+        "Run 'tablevalidator-databricks info' for a full usage guide."
+    ),
+    no_args_is_help=True,
+)
+
+DEFAULT_OUTPUT_PATH = Path("TableValidator.py")
+
+
+@app.command()
+def init(
+    output: Path = typer.Option(
+        DEFAULT_OUTPUT_PATH,
+        "--output",
+        help="Path to write the generated notebook to (default: ./TableValidator.py).",
+    ),
+    mode: str = typer.Option(
+        "full",
+        "--mode",
+        help=(
+            "basic: only the check-group Yes/No dropdowns and table pickers. "
+            "full (default): also shows optional filter widgets (only/ "
+            "ignore columns, row filter, primary key). "
+            "schema: same widgets as basic, but the Row checks default to No "
+            "(schema-shape-only comparison)."
+        ),
+    ),
+) -> None:
+    """Generate a Databricks notebook with dbutils widgets for source/
+    target catalog.schema.table selection and validation checks - fill in
+    the widgets and run the notebook, no code to write.
+
+    Import the generated file into a Databricks workspace via
+    Workspace -> Import, with format set to "Source" (or "File" -> upload
+    directly, depending on your workspace UI version) - Databricks
+    recognizes the "# Databricks notebook source" header and cell
+    (# COMMAND ----------) markers and opens it as a real notebook, not a
+    plain text file.
+    """
+    if mode not in VALID_MODES:
+        typer.secho(
+            f"Invalid --mode {mode!r} - must be one of {', '.join(VALID_MODES)}.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    generate_notebook(output, mode)
+
+    typer.echo(f"Generated notebook: {output.resolve()}")
+    typer.echo(
+        "Import it into Databricks (Workspace -> Import, format 'Source'), "
+        "fill in the widgets, and Run All."
+    )
+
+
+_INFO_TEXT = """
+tablevalidator-databricks - Databricks notebook UI for table-validator
+------------------------------------------------------------------------
+Generates a Databricks notebook driven entirely by dbutils widgets -
+Catalog/Schema/Table dropdowns populated live from Unity Catalog, plus
+Yes/No dropdowns for which checks to run - as a wrapper around the
+table-validator package's validate_tables() API. No Python to write, and
+no separate credentials to configure (the notebook reuses its own
+ambient Spark session, same as validate_tables() itself).
+
+This package contains NO validation logic of its own. Every generated
+notebook calls straight into table-validator's engine, so results are
+identical to calling validate_tables() yourself in a code cell.
+
+STEPS
+-----
+  1. tablevalidator-databricks init
+     Writes a ready-to-run notebook (./TableValidator.py by default).
+       --output PATH   write somewhere else
+       --mode MODE     basic | full (default) | schema
+     See 'tablevalidator-databricks init --help' for details.
+
+  2. Import it into Databricks
+     Workspace -> Import -> format "Source", pick the generated file.
+     Databricks reads the '# Databricks notebook source' header and
+     '# COMMAND ----------' markers and opens it as a real notebook.
+
+  3. Fill in the widgets, then Run All
+     Pick Source and Target Catalog / Schema / Table, choose which
+     checks to run, and run the notebook top to bottom.
+
+MODES
+-----
+  basic    Check-group Yes/No dropdowns and the table pickers only.
+  full     (default) Also shows optional filter widgets: only-columns,
+           ignore-columns, row filter, primary key.
+  schema   Same widgets as basic, but the Row checks default to "No" -
+           a lightweight schema-shape-only comparison.
+
+THE CHECK GROUPS
+----------------
+Three independent Yes/No dropdowns:
+
+  Catalog & Schema   Do the catalogs/schemas/tables exist and match by
+                     name? This produces NO per-table PASS/FAIL on its
+                     own - running it alone reports every table as
+                     SKIPPED. That is expected, not an error.
+  Column             Column names, data types, nullability, null and
+                     distinct counts, min/max. This is where schema-
+                     shape problems are actually caught.
+  Row                Row counts and row-level data comparison. The most
+                     expensive group.
+
+Turning every group off falls back to running everything, rather than
+silently validating nothing.
+
+VALIDATING A WHOLE SCHEMA
+-------------------------
+Set the Table dropdown to "(all tables in schema)" on BOTH sides to
+compare every identically-named table in that schema in one run - the
+same schema-wide sweep validate_tables() itself supports. A primary key
+can't be used in this mode (a single key can't apply to every table), so
+leave the Primary Key widget blank. Comparing every schema in a catalog
+is not supported yet - Schema must be a specific pick.
+
+CASCADING DROPDOWNS
+-------------------
+Databricks widgets have no on-change event, so choosing a new Catalog
+does NOT repopulate the Schema dropdown below it (same for Schema ->
+Table). After changing a Catalog or Schema, re-run the notebook's
+"Create / refresh widgets" cell (Shift+Enter) before continuing. This is
+a Databricks platform limitation, not a bug in the notebook - and if you
+skip it, the notebook fails with a clear error naming the cell to re-run
+rather than silently comparing the wrong table.
+
+NAME NOT IN A DROPDOWN?
+-----------------------
+Every Catalog/Schema/Table dropdown has a "(manual override)" text
+widget beside it. Type an exact name there and it is used instead of the
+dropdown - handy for a permissions lag, an odd sort order, anything the
+listing misses. It is used as-is, not checked against the live catalog.
+Leave the overrides blank to just use the dropdowns.
+
+VERSION PINNING (IMPORTANT)
+---------------------------
+The generated notebook installs the engine with a floor:
+    %pip install "table-validator>={MIN_CORE_VERSION}"
+Do NOT lower that pin, and do not confuse it with this package's own
+version number - the two packages are versioned completely
+independently. validate_tables() only exists in table-validator 0.1.9
+and later, so pinning the engine to this generator's version installs
+something far too old and fails with:
+    ImportError: cannot import name 'validate_tables'
+
+Re-run 'tablevalidator-databricks init' after upgrading this package -
+an already-generated notebook keeps whatever code it was written with.
+""".strip("\n")
+
+
+@app.command()
+def info() -> None:
+    """Show what this tool does and how to use the generated notebook."""
+    typer.echo("\n" + _INFO_TEXT.replace("{MIN_CORE_VERSION}", _min_core_version()) + "\n")

{tablevalidator_databricks-0.1.4 → tablevalidator_databricks-0.1.5}/tablevalidator_databricks.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tablevalidator-databricks
-Version: 0.1.4
+Version: 0.1.5
 Summary: Generates a widget-driven Databricks notebook UI on top of the table-validator package - no code required to run a comparison.
 License: MIT
 Requires-Python: >=3.9
@@ -35,6 +35,14 @@ there's nothing else to install separately.
 
 ## Usage
 
+```bash
+tablevalidator-databricks info
+```
+
+Prints a full usage guide - the steps, the three modes, what each check
+group actually does, schema-wide sweeps, the cascading-dropdown caveat,
+manual overrides, and version pinning. Start here if you're new to it.
+
 ```bash
 tablevalidator-databricks init
 ```

tablevalidator_databricks-0.1.5/tablevalidator_databricks.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.5",
+  "distance": 0,
+  "node": "g00d5f8a",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-10"
+}

tablevalidator_databricks-0.1.5/tests/test_cli.py

@@ -0,0 +1,90 @@
+"""Tests for the tablevalidator-databricks CLI (cli/main.py)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from tablevalidator_databricks.cli.main import app
+
+runner = CliRunner()
+
+
+def test_app_is_importable() -> None:
+    assert app is not None
+
+
+def test_help_lists_init_command() -> None:
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "init" in result.output
+
+
+def test_init_writes_notebook_to_default_path(tmp_path: Path) -> None:
+    output = tmp_path / "TableValidator.py"
+
+    result = runner.invoke(app, ["init", "--output", str(output)])
+
+    assert result.exit_code == 0
+    assert output.exists()
+    assert "Generated notebook" in result.output
+
+
+def test_init_respects_mode_flag(tmp_path: Path) -> None:
+    output = tmp_path / "basic.py"
+
+    result = runner.invoke(app, ["init", "--output", str(output), "--mode", "basic"])
+
+    assert result.exit_code == 0
+    content = output.read_text(encoding="utf-8")
+    assert 'MODE = "basic"' in content
+
+
+def test_init_rejects_invalid_mode(tmp_path: Path) -> None:
+    output = tmp_path / "x.py"
+
+    result = runner.invoke(app, ["init", "--output", str(output), "--mode", "bogus"])
+
+    assert result.exit_code == 1
+    assert not output.exists()
+
+
+def test_info_command_runs() -> None:
+    result = runner.invoke(app, ["info"])
+    assert result.exit_code == 0
+    assert "tablevalidator-databricks" in result.output
+
+
+def test_info_covers_every_documented_behaviour() -> None:
+    """`info` is the single place a user is pointed at to learn this tool,
+    so it must stay in step with what the generated notebook actually
+    does - each of these corresponds to a real behaviour (or a real
+    reported confusion) the notebook has."""
+    result = runner.invoke(app, ["info"])
+
+    for expected in (
+        "init",                          # the generate step
+        "Workspace -> Import",           # how to get it into Databricks
+        "basic",                         # the three modes
+        "full",
+        "schema",
+        "Yes/No",                        # check groups are dropdowns, not a multiselect
+        "SKIPPED",                       # why catalog+schema alone reports SKIPPED
+        "(all tables in schema)",        # schema-wide sweep
+        "Create / refresh widgets",      # the cascading-dropdown caveat
+        "(manual override)",             # typing a name the dropdown misses
+        "table-validator>=",             # the version floor
+    ):
+        assert expected in result.output, f"`info` no longer mentions {expected!r}"
+
+
+def test_info_renders_the_real_version_floor() -> None:
+    """The floor shown by `info` must be substituted from package
+    metadata, not left as a literal placeholder."""
+    from tablevalidator_databricks.generator.generator import _min_core_version
+
+    result = runner.invoke(app, ["info"])
+
+    assert "{MIN_CORE_VERSION}" not in result.output
+    assert f'table-validator>={_min_core_version()}' in result.output

tablevalidator_databricks-0.1.4/tablevalidator_databricks/cli/main.py

@@ -1,101 +0,0 @@
-"""CLI entry point: `tablevalidator-databricks` console script."""
-
-from pathlib import Path
-
-import typer
-
-from tablevalidator_databricks.generator.generator import VALID_MODES, generate_notebook
-
-app = typer.Typer(
-    name="tablevalidator-databricks",
-    help="Generate a widget-driven Databricks notebook UI for table-validator.",
-    no_args_is_help=True,
-)
-
-DEFAULT_OUTPUT_PATH = Path("TableValidator.py")
-
-
-@app.command()
-def init(
-    output: Path = typer.Option(
-        DEFAULT_OUTPUT_PATH,
-        "--output",
-        help="Path to write the generated notebook to (default: ./TableValidator.py).",
-    ),
-    mode: str = typer.Option(
-        "full",
-        "--mode",
-        help=(
-            "basic: only the check-group multiselect and table pickers. "
-            "full (default): also shows optional filter widgets (only/ "
-            "ignore columns, row filter, primary key). "
-            "schema: pre-selects only the Catalog & Schema check group."
-        ),
-    ),
-) -> None:
-    """Generate a Databricks notebook with dbutils widgets for source/
-    target catalog.schema.table selection and validation checks - fill in
-    the widgets and run the notebook, no code to write.
-
-    Import the generated file into a Databricks workspace via
-    Workspace -> Import, with format set to "Source" (or "File" -> upload
-    directly, depending on your workspace UI version) - Databricks
-    recognizes the "# Databricks notebook source" header and cell
-    (# COMMAND ----------) markers and opens it as a real notebook, not a
-    plain text file.
-    """
-    if mode not in VALID_MODES:
-        typer.secho(
-            f"Invalid --mode {mode!r} - must be one of {', '.join(VALID_MODES)}.",
-            fg=typer.colors.RED,
-        )
-        raise typer.Exit(code=1)
-
-    generate_notebook(output, mode)
-
-    typer.echo(f"Generated notebook: {output.resolve()}")
-    typer.echo(
-        "Import it into Databricks (Workspace -> Import, format 'Source'), "
-        "fill in the widgets, and Run All."
-    )
-
-
-@app.command()
-def info() -> None:
-    """Show what this tool does and how to use the generated notebook."""
-    typer.echo(
-        "\n"
-        "tablevalidator-databricks - Databricks notebook UI for table-validator\n"
-        "------------------------------------------------------------------------\n"
-        "Generates a Databricks notebook with dbutils widgets (dynamic "
-        "catalog/schema/table dropdowns sourced from Unity Catalog, plus a "
-        "validation-checks multiselect) as a wrapper around the "
-        "table-validator package's validate_tables() API - no Python code "
-        "to write, no separate credentials to configure (the notebook "
-        "reuses its own ambient Spark session, same as validate_tables() "
-        "itself).\n"
-        "\n"
-        "Workflow:\n"
-        "\n"
-        "  1. tablevalidator-databricks init\n"
-        "     Writes a ready-to-use notebook (./TableValidator.py by "
-        "default). Use --output to write elsewhere, --mode to pick basic/"
-        "full/schema (see 'tablevalidator-databricks init --help').\n"
-        "\n"
-        "  2. Import the generated file into Databricks\n"
-        "     Workspace -> Import, format 'Source'.\n"
-        "\n"
-        "  3. Fill in the widgets and Run All\n"
-        "     Pick Source/Target Catalog, Schema, Table, and which checks "
-        "to run, then run the notebook top to bottom. Re-run the "
-        "'Create / refresh widgets' cell after changing a Catalog/Schema "
-        "selection, to repopulate the dropdowns below it (a Databricks "
-        "widget limitation, not a bug). Can't find a name in a dropdown? "
-        "Each dropdown has a '(manual override)' text widget next to it - "
-        "type the exact name there instead.\n"
-        "\n"
-        "This package contains no validation logic of its own - every "
-        "generated notebook calls directly into table-validator's own "
-        "validate_tables() engine, so results are identical to calling it "
-        "yourself in a code cell.\n"
-    )

tablevalidator_databricks-0.1.4/tablevalidator_databricks.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.1.4",
-  "distance": 0,
-  "node": "g131e781",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-08"
-}

tablevalidator_databricks-0.1.4/tests/test_cli.py

@@ -1,56 +0,0 @@
-"""Tests for the tablevalidator-databricks CLI (cli/main.py)."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from typer.testing import CliRunner
-
-from tablevalidator_databricks.cli.main import app
-
-runner = CliRunner()
-
-
-def test_app_is_importable() -> None:
-    assert app is not None
-
-
-def test_help_lists_init_command() -> None:
-    result = runner.invoke(app, ["--help"])
-    assert result.exit_code == 0
-    assert "init" in result.output
-
-
-def test_init_writes_notebook_to_default_path(tmp_path: Path) -> None:
-    output = tmp_path / "TableValidator.py"
-
-    result = runner.invoke(app, ["init", "--output", str(output)])
-
-    assert result.exit_code == 0
-    assert output.exists()
-    assert "Generated notebook" in result.output
-
-
-def test_init_respects_mode_flag(tmp_path: Path) -> None:
-    output = tmp_path / "basic.py"
-
-    result = runner.invoke(app, ["init", "--output", str(output), "--mode", "basic"])
-
-    assert result.exit_code == 0
-    content = output.read_text(encoding="utf-8")
-    assert 'MODE = "basic"' in content
-
-
-def test_init_rejects_invalid_mode(tmp_path: Path) -> None:
-    output = tmp_path / "x.py"
-
-    result = runner.invoke(app, ["init", "--output", str(output), "--mode", "bogus"])
-
-    assert result.exit_code == 1
-    assert not output.exists()
-
-
-def test_info_command_runs() -> None:
-    result = runner.invoke(app, ["info"])
-    assert result.exit_code == 0
-    assert "tablevalidator-databricks" in result.output