feat: composable steps

great-docs.yml

@@ -173,14 +173,17 @@ reference:
     - title: Contracts and Pipelines
       desc: >
         Use `Contract` and `Step` to define declarative data quality contracts that specify what
-        valid data looks like. Use `Pipeline` to enforce contracts at both boundaries of a data
-        transformation (source and target), producing a `PipelineResult` with full introspection
-        into what passed and what failed.
+        valid data looks like. Use `Steps` to build reusable step libraries with a fluent API and
+        compose them into `Validate` plans via `add_steps()`. Use `Pipeline` to enforce contracts
+        at both boundaries of a data transformation (source and target), producing a
+        `PipelineResult` with full introspection into what passed and what failed.
       contents:
         - name: Contract
           members: true
         - name: Step
           members: true
+        - name: Steps
+          members: true
         - name: Pipeline
           members: true
         - name: PipelineResult

pointblank/__init__.py

@@ -33,6 +33,7 @@
 )
 from pointblank.contract import Contract, Step
 from pointblank.datascan import DataScan, DataScanDiff, col_summary_tbl
+from pointblank.steps import Steps
 from pointblank.draft import DraftValidation
 from pointblank.edit import EditValidation
 from pointblank.field import (
@@ -123,6 +124,7 @@
     "Schema",
     "Contract",
     "Step",
+    "Steps",
     "Pipeline",
     "PipelineResult",
     "DataScan",

pointblank/_utils_html.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from great_tables import html
 
 from pointblank._constants import TABLE_TYPE_STYLES
 from pointblank._utils import _format_to_integer_value
 
+if TYPE_CHECKING:
+    from pointblank.steps import Steps
+
 
 def _fmt_frac(vec) -> list[str | None]:
     res: list[str | None] = []
@@ -94,3 +97,52 @@ def _create_table_dims_html(columns: int, rows: int, font_size: str = "10px") ->
         f"border: solid 1px #BDE7B4; padding: 2px 15px 2px 15px; font-size: {font_size};'>"
         f"{columns_fmt}</span>"
     )
+
+
+def _create_steps_html(steps_obj: Steps) -> str:
+    import html as html_module
+
+    n = len(steps_obj)
+    header = (
+        f"<div style='font-family: system-ui, -apple-system, sans-serif; max-width: 600px;'>"
+        f"<div style='padding: 8px 12px; background-color: #f8f8f8; border: 1px solid #e0e0e0; "
+        f"border-radius: 4px 4px 0 0; font-weight: 600; font-size: 13px; color: #333;'>"
+        f"Steps &mdash; {n} step{'s' if n != 1 else ''}"
+        f"</div>"
+    )
+
+    if n == 0:
+        body = (
+            "<div style='padding: 16px 12px; border: 1px solid #e0e0e0; border-top: none; "
+            "border-radius: 0 0 4px 4px; color: #888; font-size: 12px; font-style: italic;'>"
+            "No steps defined."
+            "</div>"
+        )
+        return header + body + "</div>"
+
+    rows = []
+    for i, step in enumerate(steps_obj._steps, start=1):
+        kwargs_parts = []
+        for k, v in step.kwargs.items():
+            if steps_obj._is_default(k, v):
+                continue
+            v_repr = html_module.escape(repr(v))
+            kwargs_parts.append(
+                f"<span style='color: #666;'>{html_module.escape(k)}</span>="
+                f"<span style='color: #0550ae;'>{v_repr}</span>"
+            )
+        kwargs_str = ", ".join(kwargs_parts)
+
+        bg = "#ffffff" if i % 2 == 1 else "#fafafa"
+        radius = "0 0 4px 4px" if i == n else "0"
+        rows.append(
+            f"<div style='padding: 6px 12px; border: 1px solid #e0e0e0; border-top: none; "
+            f"background-color: {bg}; font-size: 12px; border-radius: {radius};'>"
+            f"<span style='color: #888; margin-right: 8px;'>{i}.</span>"
+            f"<span style='font-weight: 600; color: #1a7f37;'>"
+            f"{html_module.escape(step.method)}</span>"
+            f"(<span style='font-size: 11px;'>{kwargs_str}</span>)"
+            f"</div>"
+        )
+
+    return header + "".join(rows) + "</div>"