From 17536fd4ff9c98ca422aaff8546ff277c2f87ad8 Mon Sep 17 00:00:00 2001
From: Oleksandr Pavlyk <21087696+oleksandr-pavlyk@users.noreply.github.com>
Date: Mon, 22 Jun 2026 11:58:16 -0500
Subject: [PATCH] Ensure that bulk-debug-python script is enclosed in markers

This permits extracting Python script using Unix CLI tools
when `--bulk-debug-python stdout` is used.

Added example of using this to nvbench_compare.md doc.
---
 docs/nvbench_compare.md             | 28 ++++++++++++++++++++++++++++
 python/scripts/nvbench_compare.py   |  2 ++
 python/test/test_nvbench_compare.py |  4 ++++
 3 files changed, 34 insertions(+)

diff --git a/docs/nvbench_compare.md b/docs/nvbench_compare.md
index d0c0054..477a111 100644
--- a/docs/nvbench_compare.md
+++ b/docs/nvbench_compare.md
@@ -168,6 +168,34 @@ Use `stdout` instead of a file path to print the generated Python code:
 nvbench-compare --bulk-debug-python stdout reference.json compare.json
 ```
 
+Generated bulk-debug Python is enclosed in comment markers:
+
+```python
+# NVB-BULK-BEGIN
+...
+# NVB-BULK-END
+```
+
+Because the markers are valid Python comments, the generated helpers can be
+filtered directly into the standard Python REPL:
+
+```bash
+python -i <(
+  nvbench-compare --bulk-debug-python stdout reference.json compare.json \
+    | sed -n '/^# NVB-BULK-BEGIN$/,/^# NVB-BULK-END$/p'
+)
+```
+
+IPython does not reliably accept process-substitution paths as startup files.
+For IPython, write the generated code to a temporary file directly:
+
+```bash
+tmp=$(mktemp --suffix=.py)
+nvbench-compare --bulk-debug-python "$tmp" reference.json compare.json
+ipython -i "$tmp"
+rm -f "$tmp"
+```
+
 Each `bulk_rows` entry includes:
 
 - `row_index`: zero-based index among displayed comparison rows
diff --git a/python/scripts/nvbench_compare.py b/python/scripts/nvbench_compare.py
index 28c7e6b..9b1cd77 100644
--- a/python/scripts/nvbench_compare.py
+++ b/python/scripts/nvbench_compare.py
@@ -996,6 +996,7 @@ def make_bulk_debug_row(
 
 def format_bulk_debug_python(bulk_rows: list[dict[str, Any]]) -> str:
     return (
+        "# NVB-BULK-BEGIN\n"
         "# Generated by nvbench-compare --bulk-debug-python.\n"
         "import numpy as np\n\n"
         f"bulk_rows = {pprint.pformat(bulk_rows, sort_dicts=False)}\n\n"
@@ -1028,6 +1029,7 @@ def format_bulk_debug_python(bulk_rows: list[dict[str, Any]]) -> str:
         "# row = bulk_rows[0]\n"
         "# arrays = load_bulk_data(row)\n"
         "# ambiguous = [row for row in bulk_rows if row['status'] == 'AMBG']\n"
+        "# NVB-BULK-END\n"
     )
 
 
diff --git a/python/test/test_nvbench_compare.py b/python/test/test_nvbench_compare.py
index f60461f..c6dc2a0 100644
--- a/python/test/test_nvbench_compare.py
+++ b/python/test/test_nvbench_compare.py
@@ -495,6 +495,8 @@ def test_format_bulk_debug_python_loads_arrays(tmp_path, nvbench_compare):
     )
     namespace = {}
 
+    assert script.startswith("# NVB-BULK-BEGIN\n")
+    assert script.endswith("# NVB-BULK-END\n")
     exec(script, namespace)
 
     arrays = namespace["load_bulk_data"](namespace["bulk_rows"][0])
@@ -1847,9 +1849,11 @@ def test_main_prints_bulk_debug_python_to_stdout(monkeypatch, capsys, nvbench_co
 
     assert nvbench_compare.main() == 0
     output = capsys.readouterr().out
+    assert "# NVB-BULK-BEGIN" in output
     assert "bulk_rows = [" in output
     assert "'status': 'AMBG'" in output
     assert "def load_bulk_data(row):" in output
+    assert "# NVB-BULK-END" in output
 
 
 def test_compare_benches_defaults_to_interval_display(monkeypatch, nvbench_compare):