feat: add is_pure flag to debug (default False)

`debug` is side-effecting -- it logs (or prints) on every execution -- so
registering it as `is_pure=True` (the previous default) let Polars
deduplicate repeated uses and drop log output the caller asked for. Add
`is_pure` (keyword-only, default `False`), mirroring `probe`, so repeated
uses are not collapsed by default; a caller with a known-pure input can opt
into dedup. Adds a test that the log-side-effect runs per occurrence.

Signed-off-by: Pascal Tomecek <40371786+ptomecek@users.noreply.github.com>

Author: ptomecek

polars_io_tools/io_sources/lazy_debug.py

@@ -15,6 +15,8 @@ def debug(
     self: pl.LazyFrame,
     log_level: int | None = None,
     description: str | None = None,
+    *,
+    is_pure: bool = False,
 ) -> pl.LazyFrame:
     """
     A very simple pass-through lazy frame source to help with debugging experimentation of polars io sources and lazy frame behavior.
@@ -23,6 +25,7 @@ def debug(
         self: The input data frame to cache columns of.
         log_level: If provided, will log at the given level. If None, will print. Defaults to None.
         description: Optional free-form description of this source instance, attached to its OpenTelemetry span (``explain_detail``).
+        is_pure: Whether the wrapped input is pure (deterministic and side-effect-free). Defaults to ``False`` so repeated uses are not deduplicated -- ``debug`` logs on every execution, so collapsing executions would drop output you asked for. Set ``True`` only for a known-pure input where deduplication is wanted.
     """
     schema = self.collect_schema()
 
@@ -55,4 +58,4 @@ def source_generator(
             raise RuntimeError(err_msg) from e
 
     # TODO: Turn on validate_schema when this is solved: https://github.com/pola-rs/polars/issues/22110
-    return register_io_source_with_is_pure(source_generator, schema=schema, validate_schema=False, explain_detail=description)
+    return register_io_source_with_is_pure(source_generator, schema=schema, is_pure=is_pure, validate_schema=False, explain_detail=description)

polars_io_tools/tests/io_sources/test_lazy_debug.py

@@ -43,3 +43,12 @@ def test_debug_filter(caplog):
     assert "debug called with" in caplog.text
     assert "`with_columns=None`" in caplog.text
     assert '`predicate=[(col("a")) > (1)]`' in caplog.text
+
+
+def test_debug_logs_per_use_by_default(caplog):
+    # is_pure defaults to False, so reusing the same debug is not deduplicated: its log-side-effect runs per occurrence.
+    df = pl.DataFrame({"a": [1]}).lazy()
+    debug = df.piot.debug(log_level=logging.INFO)
+    caplog.set_level(logging.INFO)
+    pl.concat([debug, debug]).collect(engine="streaming")
+    assert caplog.text.count("debug called with") == 2