nc-gcode-interpreter 0.2.1__tar.gz → 0.2.2__tar.gz

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.2}/CHANGELOG.md

@@ -4,6 +4,22 @@ Notable changes to **nc-gcode-interpreter**. The format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); versions are git tags,
 released to PyPI.
 
+## [v0.2.2] - 2026-07-07
+
+### Added
+
+- Variable-change events on the batch path: `nc_to_batches(...,
+  include_variables=True)` exposes, once exhausted, a sparse `variable_events`
+  DataFrame (`row_idx` / `name_id` / `value`) plus a `variable_names` list -
+  the batch-path twin of the per-row `variables` dict `nc_to_rows` already
+  yields. `row_idx` is the output-row index a change is seen at (a change on a
+  variable-only block is attributed to the next output row), so replaying the
+  events reconstructs the symbol table at any row. Off by default (no cost).
+- `string_table` in the interpreter state dict: `DEF STRING` variables now
+  round-trip into `.state` / the `nc_to_dataframe` state tuple as
+  `state["string_table"]` (`dict[str, str]`), alongside the existing `axes` /
+  `symbol_table` / `translation` numeric tables (previously omitted).
+
 ## [v0.2.1] - 2026-07-07
 
 ### Added

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.2}/Cargo.lock

@@ -506,7 +506,7 @@ checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
 
 [[package]]
 name = "nc-gcode-interpreter"
-version = "0.2.1"
+version = "0.2.2"
 dependencies = [
  "arrow-array",
  "arrow-data",

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nc-gcode-interpreter"
-version = "0.2.1"
+version = "0.2.2"
 edition = "2021"
 readme = "README.md"
 

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nc-gcode-interpreter
-Version: 0.2.1
+Version: 0.2.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: 3.12

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.2}/python/nc_gcode_interpreter/__init__.py

@@ -498,6 +498,29 @@ class _BatchIterator:
     def state(self) -> dict | None:
         return self._inner.state
 
+    @property
+    def variable_events(self) -> "pl.DataFrame | None":
+        """Sparse variable-change events (``include_variables=True``).
+
+        A :class:`polars.DataFrame` with columns ``row_idx`` (the output-row
+        index the change is seen at), ``name_id`` (index into
+        :attr:`variable_names`) and ``value``. ``None`` unless the iterator was
+        created with ``include_variables=True``. Available once exhausted.
+        Replaying the events in order (decoding ``name_id`` via
+        :attr:`variable_names`) reconstructs the symbol table at any row, the
+        batch-path twin of the per-row ``variables`` dict ``nc_to_rows`` yields.
+        """
+        batch = self._inner.variable_events
+        return None if batch is None else pl.DataFrame(batch)
+
+    @property
+    def variable_names(self) -> list[str] | None:
+        """Variable names ``variable_events.name_id`` indexes into.
+
+        ``None`` unless ``include_variables=True``; available once exhausted.
+        """
+        return self._inner.variable_names
+
 
 def nc_to_batches(
     input: "TextFileLike | str | os.PathLike",
@@ -511,6 +534,7 @@ def nc_to_batches(
     allow_undefined_variables: bool = False,
     flatten_tolerance: float | None = None,
     include_line_numbers: bool = False,
+    include_variables: bool = False,
 ) -> _BatchIterator:
     """Interpret an NC program into a stream of columnar polars DataFrames.
 
@@ -541,6 +565,12 @@ def nc_to_batches(
     a loop, non-monotonic across a jump), never forward-filled. Default False
     leaves the schema unchanged.
 
+    With ``include_variables=True`` the iterator additionally exposes
+    ``variable_events`` (a sparse :class:`polars.DataFrame` of ``row_idx`` /
+    ``name_id`` / ``value``) and ``variable_names`` once exhausted — the
+    batch-path equivalent of the per-row ``variables`` dict :func:`nc_to_rows`
+    yields; replaying the events reconstructs the symbol table at any row.
+
     Example:
     --------
     >>> batches = nc_to_batches("G1 X10\\nX20 Y5", batch_size=1)
@@ -564,5 +594,6 @@ def nc_to_batches(
         input_is_path,
         flatten_tolerance,
         include_line_numbers,
+        include_variables,
     )
     return _BatchIterator(inner)

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.2}/python/nc_gcode_interpreter/_internal.pyi

@@ -43,8 +43,15 @@ def nc_to_batches(
     input_is_path: bool = False,
     flatten_tolerance: Optional[float] = None,
     include_line_numbers: bool = False,
+    include_variables: bool = False,
 ) -> Any:
-    """Interpret an NC program into an iterator of columnar polars DataFrames."""
+    """Interpret an NC program into an iterator of columnar polars DataFrames.
+
+    The returned iterator exposes ``state`` (dict with ``axes``,
+    ``symbol_table``, ``translation`` and ``string_table``) once exhausted, and
+    - when ``include_variables`` is set - ``variable_events`` (an Arrow batch of
+    ``row_idx`` / ``name_id`` / ``value``) and ``variable_names`` (list[str]).
+    """
     ...
 
 __all__ = ["nc_to_rows", "nc_to_batches"]

nc_gcode_interpreter-0.2.2/python/tests/test_batch_variables.py

@@ -0,0 +1,205 @@
+"""Batch-path variable-change events (#46) + `string_table` in the state dict.
+
+The streaming `nc_to_rows(include_variables=True)` path yields a per-row
+`variables` dict; the batch path (`nc_to_batches` / `nc_to_dataframe`) now
+surfaces the same information as a sparse side-table (`row_idx`, `name_id`,
+`value`) plus a `variable_names` list. These tests pin (a) parity of the
+ordered assignment sequence between the two paths and (b) that `DEF STRING`
+variables round-trip into the returned state dict.
+"""
+
+import polars as pl
+
+from nc_gcode_interpreter import nc_to_batches, nc_to_dataframe, nc_to_rows
+
+
+def _stream_sequence(program: str) -> list[tuple[str, float]]:
+    """Flat, ordered `(name, value)` assignment sequence from the stream."""
+    return [
+        (name, value)
+        for _line, _row, variables in nc_to_rows(program, include_variables=True)
+        for name, value in variables.items()
+    ]
+
+
+def _batch_sequence(it) -> list[tuple[str, float]]:
+    """Flat, ordered `(name, value)` sequence decoded from the batch events."""
+    events = it.variable_events
+    names = it.variable_names
+    return [
+        (names[name_id], value)
+        for name_id, value in zip(events["name_id"], events["value"])
+    ]
+
+
+def test_batch_variable_events_match_stream_simple():
+    program = "\n".join(
+        [
+            "DEF REAL Q=2.5",  # variable-only
+            "R1=0",            # variable-only
+            "X=R1",            # output row, no change
+            "X=Q",             # output row, no change
+        ]
+    )
+    it = nc_to_batches(program, include_variables=True)
+    list(it)  # exhaust to populate variable_events / state
+    assert _batch_sequence(it) == _stream_sequence(program)
+
+
+def test_batch_variable_events_match_stream_while_loop():
+    # A WHILE loop where R1 changes once per iteration: the per-iteration
+    # counter events must appear on the batch path exactly as they do on the
+    # stream, in the same order.
+    program = "\n".join(
+        [
+            "DEF REAL Q=2.5",
+            "R1=0",
+            "WHILE R1<3",
+            "X=R1 Q=Q*2",  # output row that ALSO assigns a variable
+            "R1=R1+1",     # variable-only, per iteration
+            "ENDWHILE",
+            "X=Q",
+        ]
+    )
+    it = nc_to_batches(program, include_variables=True)
+    list(it)
+    assert _batch_sequence(it) == _stream_sequence(program)
+
+
+def test_batch_variable_events_row_idx_reconstructs_symbol_table():
+    # Replaying every event reconstructs the final symbol table (minus the
+    # built-in TRUE/FALSE), mirroring the streaming accumulation invariant.
+    program = "\n".join(
+        [
+            "DEF REAL Q=1",
+            "R1=0",
+            "WHILE R1<3",
+            "X=R1 Q=Q*2",
+            "R1=R1+1",
+            "ENDWHILE",
+        ]
+    )
+    it = nc_to_batches(program, include_variables=True)
+    list(it)
+    accumulated: dict[str, float] = {}
+    for name, value in _batch_sequence(it):
+        accumulated[name] = value
+    symbol_table = dict(it.state["symbol_table"])
+    for builtin in ("TRUE", "FALSE"):
+        symbol_table.pop(builtin)
+    assert accumulated == symbol_table
+
+    # row_idx is monotonic non-decreasing (events arrive in program order) and
+    # bounded by the number of output rows.
+    events = it.variable_events
+    row_idx = events["row_idx"].to_list()
+    assert row_idx == sorted(row_idx)
+
+
+def test_batch_variable_events_row_idx_aligns_with_output_rows():
+    # A change on a variable-only block is attributed to the NEXT output row;
+    # a change on an output row gets that row's own index.
+    program = "\n".join(
+        [
+            "R1=0",   # variable-only, before output row 0
+            "X=R1",   # output row 0
+            "R1=1",   # variable-only, before output row 1
+            "X=R1",   # output row 1
+        ]
+    )
+    it = nc_to_batches(program, include_variables=True)
+    list(it)
+    events = it.variable_events
+    names = it.variable_names
+    decoded = [
+        (row_idx, names[name_id], value)
+        for row_idx, name_id, value in zip(
+            events["row_idx"], events["name_id"], events["value"]
+        )
+    ]
+    assert decoded == [(0, "R1", 0.0), (1, "R1", 1.0)]
+
+
+def test_batch_variable_events_absent_without_flag():
+    it = nc_to_batches("R1=5\nX=R1")
+    list(it)
+    assert it.variable_events is None
+    assert it.variable_names is None
+
+
+def test_batch_variable_events_empty_when_no_assignments():
+    it = nc_to_batches("G1 X10\nX20 Y5", include_variables=True)
+    list(it)
+    assert isinstance(it.variable_events, pl.DataFrame)
+    assert it.variable_events.height == 0
+    assert it.variable_names == []
+
+
+def test_string_table_round_trips_through_state_dict():
+    program = "\n".join(
+        [
+            "DEF STRING[16] MSG",
+            'MSG="HELLO WORLD"',
+            "DEF STRING[8] TAG",
+            'TAG="ABC"',
+            "G1 X1",
+        ]
+    )
+    _df, state = nc_to_dataframe(program)
+    assert state["string_table"] == {"MSG": "HELLO WORLD", "TAG": "ABC"}
+    # The existing numeric sub-tables are untouched by the new key.
+    assert set(state) == {"axes", "symbol_table", "translation", "string_table"}
+    # The string variable never leaks into the numeric symbol table.
+    assert "MSG" not in state["symbol_table"]
+
+
+def test_string_table_on_streaming_and_batch_iterators():
+    program = 'DEF STRING[8] MSG\nMSG="HI"\nG1 X1'
+    rows = nc_to_rows(program)
+    list(rows)
+    assert rows.state["string_table"] == {"MSG": "HI"}
+
+    it = nc_to_batches(program)
+    list(it)
+    assert it.state["string_table"] == {"MSG": "HI"}
+
+
+def test_line_numbers_and_variables_compose_on_the_batch_path():
+    # include_line_numbers (#45) and include_variables (#46) share the batch
+    # path and were merged independently; requesting both at once must give the
+    # leading `line_no` column AND the sparse variable-event side-table, with
+    # `row_idx` still aligned to the emitted (line_no-carrying) output rows.
+    program = "\n".join(
+        [
+            "R1=0",          # variable-only, before output row 0
+            "WHILE R1<3",
+            "X=R1",          # output row (loop body, source line 3)
+            "R1=R1+1",       # variable-only
+            "ENDWHILE",
+            "X9",            # output row, source line 6
+        ]
+    )
+    it = nc_to_batches(
+        program,
+        batch_size=1_000_000,
+        include_line_numbers=True,
+        include_variables=True,
+    )
+    df = pl.concat(list(it), how="diagonal")
+
+    # line_no leads and tracks source lines (loop body repeats line 3).
+    assert df.columns[0] == "line_no"
+    assert df["line_no"].to_list() == [3, 3, 3, 6]
+    assert df["X"].to_list() == [0.0, 1.0, 2.0, 9.0]
+
+    # Variable events still decode independently of the line_no column.
+    names = it.variable_names
+    decoded = [
+        (row_idx, names[name_id], value)
+        for row_idx, name_id, value in zip(
+            it.variable_events["row_idx"],
+            it.variable_events["name_id"],
+            it.variable_events["value"],
+        )
+    ]
+    assert decoded == [(0, "R1", 0.0), (1, "R1", 1.0), (2, "R1", 2.0), (3, "R1", 3.0)]

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.2}/src/interpreter.rs

@@ -156,6 +156,8 @@ pub fn nc_to_batch_stream(
     flatten_tolerance: Option<f64>,
     batch_size: usize,
     sender: std::sync::mpsc::SyncSender<Table>,
+    include_variables: bool,
+    events_sender: std::sync::mpsc::Sender<crate::output::VariableEvents>,
 ) -> Result<state::State, ParsingError> {
     // Back-compatible entry point: never emits the opt-in line_no column.
     nc_to_batch_stream_with_line_numbers(
@@ -171,6 +173,8 @@ pub fn nc_to_batch_stream(
         batch_size,
         false,
         sender,
+        include_variables,
+        events_sender,
     )
 }
 
@@ -191,6 +195,8 @@ pub fn nc_to_batch_stream_with_line_numbers(
     batch_size: usize,
     emit_line_no: bool,
     sender: std::sync::mpsc::SyncSender<Table>,
+    include_variables: bool,
+    events_sender: std::sync::mpsc::Sender<crate::output::VariableEvents>,
 ) -> Result<state::State, ParsingError> {
     let mut state = build_state(
         axis_identifiers,
@@ -203,7 +209,14 @@ pub fn nc_to_batch_stream_with_line_numbers(
         let mut discard = OutputRows::collect();
         interpret_file(initial_state, &mut state, &mut discard)?;
     }
-    let mut output = OutputRows::batch_stream_with_line_numbers(sender, batch_size, disable_forward_fill, emit_line_no);
+    let mut output = OutputRows::batch_stream_with_line_numbers(
+        sender,
+        batch_size,
+        disable_forward_fill,
+        include_variables,
+        events_sender,
+        emit_line_no,
+    );
     install_flattener(&mut output, &state, flatten_tolerance)?;
     interpret_file(input, &mut state, &mut output)?;
     output.finish()?;
@@ -584,8 +597,9 @@ mod tests {
     /// emitted [`Table`] carries the whole program's `line_no` column.
     fn interpret_with_line_numbers(input: &str) -> Table {
         let (tx, rx) = std::sync::mpsc::sync_channel(64);
+        let (events_tx, _events_rx) = std::sync::mpsc::channel();
         nc_to_batch_stream_with_line_numbers(
-            input, None, None, None, 10000, false, None, false, None, 1_000_000, true, tx,
+            input, None, None, None, 10000, false, None, false, None, 1_000_000, true, tx, false, events_tx,
         )
         .expect("program should interpret");
         rx.into_iter().next().expect("one batch for a small program")

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.2}/src/lib.rs

@@ -60,7 +60,8 @@ mod python_bindings {
 
     use crate::errors::ErrorLocation;
     use crate::interpreter::{nc_to_batch_stream_with_line_numbers, nc_to_row_stream};
-    use crate::output::{is_forward_filled_column, is_string_column, Column, Row, Table};
+    use crate::output::{is_forward_filled_column, is_string_column, Column, Row, Table, VariableEvents};
+    use crate::state::FinalState;
     use crate::types::Value;
 
     pyo3::create_exception!(
@@ -108,6 +109,19 @@ mod python_bindings {
         }
     }
 
+    /// Render a [`FinalState`] as the Python `.state` dict:
+    /// `{axes, symbol_table, translation, string_table}`. The three numeric
+    /// sub-tables become `dict[str, float]`; `string_table` (DEF STRING
+    /// variables) becomes `dict[str, str]`. Shared by both iterators.
+    fn final_state_to_py<'py>(py: Python<'py>, state: &FinalState) -> PyResult<Bound<'py, PyDict>> {
+        let dict = PyDict::new(py);
+        dict.set_item("axes", state.axes.clone())?;
+        dict.set_item("symbol_table", state.symbol_table.clone())?;
+        dict.set_item("translation", state.translation.clone())?;
+        dict.set_item("string_table", state.string_table.clone())?;
+        Ok(dict)
+    }
+
     /// Build one Arrow [`RecordBatch`](arrow::record_batch::RecordBatch) directly
     /// from an output [`Table`], in column order. Each [`Column`] becomes an Arrow
     /// array straight from its `Vec` (a `Vec<Option<f64>>` -> Float64,
@@ -214,7 +228,7 @@ mod python_bindings {
                     row_sender,
                 );
                 let message = match outcome {
-                    Ok(state) => Ok(state.to_python_dict()),
+                    Ok(state) => Ok(state.final_state()),
                     // The consumer hung up: nothing to report to nobody.
                     Err(crate::errors::ParsingError::StreamClosed) => return,
                     Err(error) => Err(ErrInfo::from_error(&error)),
@@ -242,9 +256,11 @@ mod python_bindings {
         allow_undefined_variables: bool,
         flatten_tolerance: Option<f64>,
         emit_line_no: bool,
+        include_variables: bool,
     ) -> PyResult<(
         mpsc::Receiver<Table>,
         mpsc::Receiver<Result<FinalState, ErrInfo>>,
+        mpsc::Receiver<VariableEvents>,
         std::thread::JoinHandle<()>,
     )> {
         // A cap of 3 lets the worker build one batch ahead while the consumer
@@ -252,6 +268,10 @@ mod python_bindings {
         // buffering.
         let (batch_sender, batch_receiver) = mpsc::sync_channel::<Table>(3);
         let (result_sender, result_receiver) = mpsc::sync_channel::<Result<FinalState, ErrInfo>>(1);
+        // Variable-change events are a small sparse side-table sent once at the
+        // end; an unbounded channel so the worker never blocks emitting them
+        // (they are only read after the batch stream is drained).
+        let (events_sender, events_receiver) = mpsc::channel::<VariableEvents>();
 
         let handle = std::thread::Builder::new()
             .name("nc-interpreter".to_string())
@@ -269,9 +289,11 @@ mod python_bindings {
                     batch_size,
                     emit_line_no,
                     batch_sender,
+                    include_variables,
+                    events_sender,
                 );
                 let message = match outcome {
-                    Ok(state) => Ok(state.to_python_dict()),
+                    Ok(state) => Ok(state.final_state()),
                     // The consumer hung up: nothing to report to nobody.
                     Err(crate::errors::ParsingError::StreamClosed) => return,
                     Err(error) => Err(ErrInfo::from_error(&error)),
@@ -279,11 +301,9 @@ mod python_bindings {
                 let _ = result_sender.send(message);
             })
             .map_err(|e| PyErr::new::<PyValueError, _>(format!("failed to spawn interpreter thread: {}", e)))?;
-        Ok((batch_receiver, result_receiver, handle))
+        Ok((batch_receiver, result_receiver, events_receiver, handle))
     }
 
-    type FinalState = HashMap<String, HashMap<String, f64>>;
-
     /// Iterator over interpreted rows: `next()` yields
     /// `(line_no, {column: value})` while the interpreter runs on a worker
     /// thread behind a bounded channel. Dropping the iterator hangs up the
@@ -440,11 +460,12 @@ mod python_bindings {
             }
         }
 
-        /// The final interpreter state (axes, symbol_table, translation),
-        /// available once the iterator is exhausted.
+        /// The final interpreter state
+        /// (`{axes, symbol_table, translation, string_table}`), available once
+        /// the iterator is exhausted.
         #[getter]
-        fn state(&self) -> Option<FinalState> {
-            self.state.clone()
+        fn state<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyDict>>> {
+            self.state.as_ref().map(|s| final_state_to_py(py, s)).transpose()
         }
     }
 
@@ -512,8 +533,14 @@ mod python_bindings {
     struct NcBatchIterator {
         batches: Option<Mutex<mpsc::Receiver<Table>>>,
         result: Option<Mutex<mpsc::Receiver<Result<FinalState, ErrInfo>>>>,
+        /// Set at construction only when `include_variables`; drained at finish
+        /// into `variable_events`.
+        events: Option<Mutex<mpsc::Receiver<VariableEvents>>>,
         handle: Option<std::thread::JoinHandle<()>>,
         state: Option<FinalState>,
+        /// The sparse variable-change side-table, available once exhausted.
+        /// `None` unless `include_variables` was set.
+        variable_events: Option<VariableEvents>,
     }
 
     impl NcBatchIterator {
@@ -529,6 +556,16 @@ mod python_bindings {
                     Err(_) => {}
                 }
             }
+            // The worker sends the events (once) before dropping the batch
+            // sender, so by the time the batch stream has closed they are
+            // already queued on the unbounded channel; a hung-up / disabled run
+            // yields `Err` and leaves `variable_events` as `None`.
+            if let Some(events) = self.events.take() {
+                let receiver = events.into_inner().expect("events receiver mutex poisoned");
+                if let Ok(ev) = py.detach(move || receiver.recv()) {
+                    self.variable_events = Some(ev);
+                }
+            }
             self.join();
             Ok(())
         }
@@ -579,11 +616,33 @@ mod python_bindings {
             }
         }
 
-        /// The final interpreter state (axes, symbol_table, translation),
-        /// available once the iterator is exhausted.
+        /// The final interpreter state
+        /// (`{axes, symbol_table, translation, string_table}`), available once
+        /// the iterator is exhausted.
         #[getter]
-        fn state(&self) -> Option<FinalState> {
-            self.state.clone()
+        fn state<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyDict>>> {
+            self.state.as_ref().map(|s| final_state_to_py(py, s)).transpose()
+        }
+
+        /// The sparse variable-change events (`include_variables=True`) as an
+        /// Arrow record batch with columns `row_idx` (Int64, the output-row
+        /// index the change is seen at), `name_id` (Int64, index into
+        /// `variable_names`) and `value` (Float64). `None` when the iterator was
+        /// created without `include_variables`. Available once exhausted.
+        /// `pl.DataFrame(it.variable_events)` wraps it zero-copy.
+        #[getter]
+        fn variable_events(&self) -> PyResult<Option<ArrowBatch>> {
+            self.variable_events
+                .as_ref()
+                .map(|ev| table_to_arrow_batch(ev.to_table()))
+                .transpose()
+        }
+
+        /// The variable names `name_id` indexes into (in first-seen order).
+        /// `None` unless `include_variables` was set; available once exhausted.
+        #[getter]
+        fn variable_names(&self) -> Option<Vec<String>> {
+            self.variable_events.as_ref().map(|ev| ev.names.clone())
         }
     }
 
@@ -593,7 +652,7 @@ mod python_bindings {
     /// thread. Wrapping each with `pl.DataFrame` and concatenating reconstructs
     /// `nc_to_dataframe`.
     #[pyfunction]
-    #[pyo3(signature = (input, batch_size = 500_000, initial_state = None, axis_identifiers = None, extra_axes = None, iteration_limit = 10000, disable_forward_fill = false, axis_index_map = None, allow_undefined_variables = false, input_is_path = false, flatten_tolerance = None, include_line_numbers = false))]
+    #[pyo3(signature = (input, batch_size = 500_000, initial_state = None, axis_identifiers = None, extra_axes = None, iteration_limit = 10000, disable_forward_fill = false, axis_index_map = None, allow_undefined_variables = false, input_is_path = false, flatten_tolerance = None, include_line_numbers = false, include_variables = false))]
     #[allow(clippy::too_many_arguments)]
     fn nc_to_batches(
         input: String,
@@ -608,6 +667,7 @@ mod python_bindings {
         input_is_path: bool,
         flatten_tolerance: Option<f64>,
         include_line_numbers: bool,
+        include_variables: bool,
     ) -> PyResult<NcBatchIterator> {
         if batch_size == 0 {
             return Err(PyErr::new::<PyValueError, _>("batch_size must be greater than 0"));
@@ -619,7 +679,7 @@ mod python_bindings {
         } else {
             input
         };
-        let (batch_receiver, result_receiver, handle) = spawn_batch_stream(
+        let (batch_receiver, result_receiver, events_receiver, handle) = spawn_batch_stream(
             input,
             batch_size,
             initial_state,
@@ -631,13 +691,22 @@ mod python_bindings {
             allow_undefined_variables,
             flatten_tolerance,
             include_line_numbers,
+            include_variables,
         )?;
 
         Ok(NcBatchIterator {
             batches: Some(Mutex::new(batch_receiver)),
             result: Some(Mutex::new(result_receiver)),
+            // Only hold the events receiver when recording; otherwise leave it
+            // `None` so `.variable_events` stays `None`.
+            events: if include_variables {
+                Some(Mutex::new(events_receiver))
+            } else {
+                None
+            },
             handle: Some(handle),
             state: None,
+            variable_events: None,
         })
     }