feat: add pointblank tutorial materials (#764)

* feat: add pointblank tutorial materials

* docs: refine pointblank materials

* fix: sync pointblank materials with tutorial scripts

Align the quickstart and atom scripts and the atom YAML with the
published tutorial examples, and refresh the generated HTML report.

* Update README

---------

Co-authored-by: Bartosz Zaczyński <bartosz.zaczynski@gmail.com>

Author: HaoZeke

python-pointblank/README.md

@@ -0,0 +1,21 @@
+# Validating Data With Pointblank in Python
+
+Supporting code and sample data for the Real Python tutorial [Validating Data With Pointblank in Python](https://realpython.com/python-pointblank/).
+
+## Requirements
+
+The Python scripts use PEP 723 dependency metadata and run with [uv](https://docs.astral.sh/uv/):
+
+```console
+$ uv run pointblank_quickstart.py
+$ uv run pointblank_thresholds.py
+$ uv run pointblank_atoms.py
+```
+
+The command-line examples can run without a project environment:
+
+```console
+$ uv run --no-project --with 'pointblank[pl]' -- pb scan pointblank_atoms.csv
+$ uv run --no-project --with 'pointblank[pl]' -- pb missing pointblank_atoms.csv
+$ uvx --from 'pointblank[pl]' pb run pointblank_atoms.yaml --output-html pointblank_report.html
+```

python-pointblank/pointblank_atoms.csv

@@ -0,0 +1,14 @@
+atom_id,symbol,x,y,z,fx,fy,fz
+0,Cu,1.0,0.5,0.1,0.1,0.0,0.0
+1,Pt,2.1,1.5,0.2,-0.2,0.1,-0.1
+2,Cu,3.2,2.5,0.3,0.3,-0.1,0.1
+3,Pt,4.3,3.5,0.4,-0.1,0.0,0.0
+4,Cu,5.4,4.5,0.5,0.2,0.1,-0.1
+5,Pt,6.5,5.5,0.6,-0.3,-0.1,0.1
+6,Cu,7.6,6.5,0.7,0.1,0.0,0.0
+7,Pt,8.7,7.5,0.8,-0.2,0.1,-0.1
+8,Cu,9.8,8.5,0.9,0.3,-0.1,0.1
+9,Pt,10.9,9.5,1.0,-0.1,0.0,0.0
+10,Zz,0.5,0.5,0.1,0.0,0.0,0.0
+11,Cu,,1.5,0.2,0.0,0.0,0.0
+12,Pt,12.1,2.5,0.3,1500.0,0.0,0.0

python-pointblank/pointblank_atoms.py

@@ -0,0 +1,41 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#   "pointblank[pl]",
+# ]
+# ///
+
+import polars as pl
+import pointblank as pb
+
+VALID_ELEMENTS = ["Cu", "Pt"]
+
+
+def main() -> None:
+    atoms = pl.read_csv("pointblank_atoms.csv")
+
+    validation = (
+        pb.Validate(
+            data=atoms,
+            tbl_name="atoms",
+            label="Atom data validation",
+            thresholds=pb.Thresholds(warning=0.02, error=0.05, critical=0.07),
+        )
+        .col_vals_in_set(columns="symbol", set=VALID_ELEMENTS)
+        .col_vals_not_null(columns=["x", "y", "z"])
+        .col_vals_between(columns=["x", "y", "z"], left=0, right=20)
+        .col_vals_between(columns=["fx", "fy", "fz"], left=-1000, right=1000)
+        .interrogate()
+    )
+
+    clean = validation.get_sundered_data(type="pass")
+    dirty = validation.get_sundered_data(type="fail")
+
+    print(f"Clean rows: {len(clean)}")
+    print(clean.select(["atom_id", "symbol", "x", "fx"]))
+    print(f"\nDirty rows: {len(dirty)}")
+    print(dirty.select(["atom_id", "symbol", "x", "fx"]))
+
+
+if __name__ == "__main__":
+    main()

python-pointblank/pointblank_atoms.yaml

@@ -0,0 +1,22 @@
+tbl: pointblank_atoms.csv
+df_library: polars
+tbl_name: "atoms"
+label: "Atom data validation"
+thresholds:
+  warning: 0.02
+  error: 0.05
+  critical: 0.07
+steps:
+  - col_vals_in_set:
+      columns: symbol
+      set: [Cu, Pt]
+  - col_vals_not_null:
+      columns: [x, y, z]
+  - col_vals_between:
+      columns: [x, y, z]
+      left: 0
+      right: 20
+  - col_vals_between:
+      columns: [fx, fy, fz]
+      left: -1000
+      right: 1000

python-pointblank/pointblank_quickstart.py

@@ -0,0 +1,38 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#   "pointblank[pl]",
+# ]
+# ///
+
+import json
+
+import pointblank as pb
+
+
+def main() -> None:
+    validation = (
+        pb.Validate(
+            data=pb.load_dataset("small_table", tbl_type="polars"),
+            tbl_name="small_table",
+            label="Quickstart validation",
+        )
+        .col_vals_between(columns="d", left=0, right=5000)
+        .col_vals_in_set(columns="f", set=["low", "mid", "high"])
+        .col_vals_not_null(columns="c")
+        .interrogate()
+    )
+
+    report = json.loads(validation.get_json_report())
+
+    print("Validation summary:\n")
+    for step in report:
+        print(
+            f"{step['assertion_type']:20}"
+            f"passed={step['n_passed']:<4}"
+            f"failed={step['n_failed']}"
+        )
+
+
+if __name__ == "__main__":
+    main()

python-pointblank/pointblank_report.html

@@ -0,0 +1,24 @@
+# Starter Pointblank template for adapting to your own pipeline.
+#
+# You can run this template against a real file with:
+# uv run --no-project --with 'pointblank[pl]' pb run pointblank_starter_validation.yaml --data your_data.csv --fail-on critical
+
+tbl: small_table
+df_library: polars
+tbl_name: "Starter Validation"
+label: "Adapt this template to your data"
+thresholds:
+  warning: 0.02
+  error: 0.05
+  critical: 0.10
+steps:
+  - col_exists:
+      columns: [record_id, status, amount]
+  - col_vals_not_null:
+      columns: record_id
+  - col_vals_in_set:
+      columns: status
+      set: [pending, shipped, delivered]
+  - col_vals_gt:
+      columns: amount
+      value: 0

python-pointblank/pointblank_report.png

@@ -0,0 +1,48 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#   "pointblank[pl]",
+# ]
+# ///
+
+import pointblank as pb
+
+
+def main() -> None:
+    validation = (
+        pb.Validate(
+            data=pb.load_dataset("small_table", tbl_type="polars"),
+            tbl_name="small_table",
+            label="Threshold-driven validation",
+            thresholds=pb.Thresholds(warning=0.05, error=0.10, critical=0.15),
+            actions=pb.Actions(
+                warning=(
+                    "Warning: step {step} reached {level} severity during "
+                    "{type}."
+                ),
+                critical=(
+                    "Critical: step {step} reached {level} severity during "
+                    "{type}."
+                ),
+            ),
+        )
+        .col_vals_between(columns="d", left=0, right=5000)
+        .col_vals_not_null(columns="c")
+        .rows_distinct()
+        .interrogate()
+    )
+
+    print("All checks passed perfectly:", validation.all_passed())
+    print(
+        "Anything above the error threshold:",
+        validation.above_threshold(level="error"),
+    )
+
+    try:
+        validation.assert_below_threshold(level="critical")
+    except AssertionError as exc:
+        print("CI gate tripped:", exc)
+
+
+if __name__ == "__main__":
+    main()