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

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

@@ -4,6 +4,26 @@ 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.3] - 2026-07-07
+
+### Added
+
+- `NcError.kind`: a stable, machine-readable string discriminating the error
+  class (e.g. `"unexpected_axis"`, `"undefined_variable"`, `"unknown_g_command"`,
+  `"parse_context"`), so a consumer can branch on the kind of error without
+  string-matching the formatted message. Present on every `NcError` alongside
+  the existing `line` / `column` / `context` / `line_text` location attributes
+  (#56).
+
+### Fixed
+
+- Validation/semantic errors now carry their source location. `Unexpected axis`,
+  and the "axis/reserved name used as a variable" definition errors, previously
+  raised an `NcError` with `line` / `column` / `context` / `line_text` all
+  `None`; they now anchor to the offending line (and expose its text), so an
+  editor can mark the exact spot - matching what syntactic parse errors already
+  did (#56).
+
 ## [v0.2.2] - 2026-07-07
 
 ### Added

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

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

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

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

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

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

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

@@ -9,6 +9,10 @@ class NcError(ValueError):
     """NC parse/interpret error carrying structured location data. Subclasses
     ValueError so `except ValueError` keeps working."""
 
+    #: Stable, machine-readable discriminator for the error class (e.g.
+    #: ``"unexpected_axis"``, ``"undefined_variable"``), for branching without
+    #: matching the formatted message.
+    kind: str
     line: Optional[int]
     column: Optional[int]
     context: Optional[str]

{nc_gcode_interpreter-0.2.2 → nc_gcode_interpreter-0.2.3}/python/tests/test_structured_errors.py

@@ -48,3 +48,44 @@ def test_str_is_still_the_full_message():
     with pytest.raises(NcError) as exc:
         nc_to_dataframe("X=R99\n")
     assert "Undefined variable" in str(exc.value)
+
+
+def test_kind_is_a_stable_machine_readable_discriminator():
+    # #56: consumers branch on `kind` instead of string-matching the message.
+    with pytest.raises(NcError) as exc:
+        nc_to_dataframe("X=R99\n")
+    assert exc.value.kind == "undefined_variable"
+
+    with pytest.raises(NcError) as exc:
+        nc_to_dataframe("G999 X1\n")
+    assert exc.value.kind == "unknown_g_command"
+
+    # Present (and stable) on every NcError, alongside the location attrs.
+    with pytest.raises(NcError) as exc:
+        nc_to_dataframe("G1 X10\nX20 Y((\n")
+    assert exc.value.kind == "parse_context"
+
+
+def test_validation_error_carries_kind_and_location():
+    # #56: an undeclared axis is a validation error; it now reports both a
+    # stable kind AND the source location (previously all-None).
+    with pytest.raises(NcError) as exc:
+        # Q is not a declared axis; the frame instruction is on line 2.
+        nc_to_dataframe("G1 X0 Y0 F100\nTRANS Q=10\n")
+    e = exc.value
+    assert e.kind == "unexpected_axis"
+    assert e.line == 2
+    assert e.column is None
+    assert e.line_text is not None and "Q=10" in e.line_text
+    assert "Unexpected axis" in str(e)
+
+
+def test_axis_used_as_variable_carries_location():
+    # Declaring a variable with an axis name is a validation error that now
+    # anchors to the offending DEF line.
+    with pytest.raises(NcError) as exc:
+        nc_to_dataframe("DEF REAL X\n")
+    e = exc.value
+    assert e.kind == "axis_used_as_variable"
+    assert e.line == 1
+    assert e.line_text is not None and "X" in e.line_text

{nc_gcode_interpreter-0.2.2 → nc_gcode_interpreter-0.2.3}/src/errors.rs

@@ -99,11 +99,26 @@ To fix this, ensure that each block contains at most one M command.
         message: String,
     },
     #[error("Unexpected axis '{axis}'. Valid axes are: {axes}")]
-    UnexpectedAxis { axis: String, axes: String },
+    UnexpectedAxis {
+        axis: String,
+        axes: String,
+        /// Source location of the offending axis word. Not shown in the
+        /// formatted message, only exposed as data (see [`ParsingError::location`]).
+        line_no: usize,
+        preview: String,
+    },
     #[error("Cannot define a variable named '{name}', as it conflicts with an axis name")]
-    AxisUsedAsVariable { name: String },
+    AxisUsedAsVariable {
+        name: String,
+        line_no: usize,
+        preview: String,
+    },
     #[error("Cannot define a variable named '{name}', as it is a reserved block address (spline PW/SD/PL)")]
-    ReservedNameUsedAsVariable { name: String },
+    ReservedNameUsedAsVariable {
+        name: String,
+        line_no: usize,
+        preview: String,
+    },
     #[error(
         r#"
 Missing axis mapping on line {line_no}
@@ -280,16 +295,48 @@ impl ParsingError {
             | Self::JumpTargetNotFound { line_no, preview, .. }
             | Self::UnmatchedStructure { line_no, preview, .. }
             | Self::UnknownGCommand { line_no, preview, .. }
-            | Self::InvalidFunctionArity { line_no, preview, .. } => some(*line_no, None, None, Some(preview)),
+            | Self::InvalidFunctionArity { line_no, preview, .. }
+            // Semantic/validation errors: the offending block is known at raise
+            // time, so they anchor to a line (no column) like the others above.
+            | Self::UnexpectedAxis { line_no, preview, .. }
+            | Self::AxisUsedAsVariable { line_no, preview, .. }
+            | Self::ReservedNameUsedAsVariable { line_no, preview, .. } => some(*line_no, None, None, Some(preview)),
             Self::ParseError { .. }
             | Self::InvalidElementCount { .. }
             | Self::InvalidCondition
             | Self::UnexpectedOperator { .. }
             | Self::LoopLimit { .. }
-            | Self::StreamClosed
-            | Self::UnexpectedAxis { .. }
-            | Self::AxisUsedAsVariable { .. }
-            | Self::ReservedNameUsedAsVariable { .. } => None,
+            | Self::StreamClosed => None,
+        }
+    }
+
+    /// A stable, machine-readable discriminator for the error class, so a
+    /// consumer can branch on the kind of error without string-matching the
+    /// formatted message. Exposed to Python as the `NcError.kind` attribute.
+    /// These strings are part of the public API: keep them stable.
+    pub fn kind(&self) -> &'static str {
+        match self {
+            Self::ParsingContext { .. } => "parse_context",
+            Self::UnknownVariable { .. } => "unknown_variable",
+            Self::UndefinedVariable { .. } => "undefined_variable",
+            Self::UnexpectedRule { .. } => "unexpected_rule",
+            Self::ParseError { .. } => "parse_error",
+            Self::InvalidElementCount { .. } => "invalid_element_count",
+            Self::InvalidCondition => "invalid_condition",
+            Self::UnexpectedOperator { .. } => "unexpected_operator",
+            Self::LoopLimit { .. } => "loop_limit",
+            Self::StreamClosed => "stream_closed",
+            Self::TooManyMCommands { .. } => "too_many_m_commands",
+            Self::UnexpectedAxis { .. } => "unexpected_axis",
+            Self::AxisUsedAsVariable { .. } => "axis_used_as_variable",
+            Self::ReservedNameUsedAsVariable { .. } => "reserved_name_used_as_variable",
+            Self::MissingAxisMapping { .. } => "missing_axis_mapping",
+            Self::InvalidAxisIndex { .. } => "invalid_axis_index",
+            Self::UnsupportedStatement { .. } => "unsupported_statement",
+            Self::JumpTargetNotFound { .. } => "jump_target_not_found",
+            Self::UnmatchedStructure { .. } => "unmatched_structure",
+            Self::UnknownGCommand { .. } => "unknown_g_command",
+            Self::InvalidFunctionArity { .. } => "invalid_function_arity",
         }
     }
 }
@@ -333,4 +380,189 @@ mod tests {
         assert!(ParsingError::StreamClosed.location().is_none());
         assert!(ParsingError::InvalidCondition.location().is_none());
     }
+
+    #[test]
+    fn validation_errors_now_carry_a_location() {
+        // #56: semantic/validation errors (previously location-less) anchor to
+        // the offending line so an editor can mark the spot.
+        let axis = ParsingError::UnexpectedAxis {
+            axis: "QQ".to_string(),
+            axes: "X, Y, Z".to_string(),
+            line_no: 4,
+            preview: "TRANS QQ10".to_string(),
+        };
+        let loc = axis.location().expect("UnexpectedAxis now has a location");
+        assert_eq!((loc.line, loc.column), (4, None));
+        assert_eq!(loc.line_text.as_deref(), Some("TRANS QQ10"));
+
+        let dup = ParsingError::AxisUsedAsVariable {
+            name: "X".to_string(),
+            line_no: 2,
+            preview: "DEF REAL X".to_string(),
+        };
+        assert_eq!(dup.location().expect("has location").line, 2);
+    }
+
+    #[test]
+    fn kind_is_a_stable_per_variant_discriminator() {
+        // Exhaustive: `kind()` strings are public API, so pin every variant's
+        // value. The wildcard-free match in `kind()` forces a new variant to be
+        // handled there; this list forces its string to be chosen deliberately.
+        use crate::types::Rule;
+        let s = String::new;
+        let cases: Vec<(ParsingError, &str)> = vec![
+            (
+                ParsingError::ParsingContext {
+                    line_no: 1,
+                    column: None,
+                    preview: s(),
+                    context: s(),
+                    message: s(),
+                },
+                "parse_context",
+            ),
+            (
+                ParsingError::UnknownVariable {
+                    line_no: 1,
+                    preview: s(),
+                    variable: s(),
+                },
+                "unknown_variable",
+            ),
+            (
+                ParsingError::UndefinedVariable {
+                    line_no: 1,
+                    preview: s(),
+                    name: s(),
+                },
+                "undefined_variable",
+            ),
+            (
+                ParsingError::UnexpectedRule {
+                    rule: Rule::EOI,
+                    context: s(),
+                    line_no: 1,
+                    preview: s(),
+                    message: s(),
+                },
+                "unexpected_rule",
+            ),
+            (ParsingError::ParseError { message: s() }, "parse_error"),
+            (
+                ParsingError::InvalidElementCount { expected: 1, actual: 2 },
+                "invalid_element_count",
+            ),
+            (ParsingError::InvalidCondition, "invalid_condition"),
+            (
+                ParsingError::UnexpectedOperator { operator: s() },
+                "unexpected_operator",
+            ),
+            (ParsingError::LoopLimit { limit: s() }, "loop_limit"),
+            (ParsingError::StreamClosed, "stream_closed"),
+            (
+                ParsingError::TooManyMCommands {
+                    line_no: 1,
+                    preview: s(),
+                    message: s(),
+                },
+                "too_many_m_commands",
+            ),
+            (
+                ParsingError::UnexpectedAxis {
+                    axis: s(),
+                    axes: s(),
+                    line_no: 1,
+                    preview: s(),
+                },
+                "unexpected_axis",
+            ),
+            (
+                ParsingError::AxisUsedAsVariable {
+                    name: s(),
+                    line_no: 1,
+                    preview: s(),
+                },
+                "axis_used_as_variable",
+            ),
+            (
+                ParsingError::ReservedNameUsedAsVariable {
+                    name: s(),
+                    line_no: 1,
+                    preview: s(),
+                },
+                "reserved_name_used_as_variable",
+            ),
+            (
+                ParsingError::MissingAxisMapping {
+                    line_no: 1,
+                    preview: s(),
+                    axis: s(),
+                },
+                "missing_axis_mapping",
+            ),
+            (
+                ParsingError::InvalidAxisIndex {
+                    line_no: 1,
+                    preview: s(),
+                    axis: s(),
+                    index: 0,
+                },
+                "invalid_axis_index",
+            ),
+            (
+                ParsingError::UnsupportedStatement {
+                    line_no: 1,
+                    preview: s(),
+                    statement: s(),
+                    hint: s(),
+                },
+                "unsupported_statement",
+            ),
+            (
+                ParsingError::JumpTargetNotFound {
+                    line_no: 1,
+                    preview: s(),
+                    target: s(),
+                    search_direction: s(),
+                    hint: s(),
+                },
+                "jump_target_not_found",
+            ),
+            (
+                ParsingError::UnmatchedStructure {
+                    line_no: 1,
+                    preview: s(),
+                    message: s(),
+                },
+                "unmatched_structure",
+            ),
+            (
+                ParsingError::UnknownGCommand {
+                    line_no: 1,
+                    preview: s(),
+                    code: s(),
+                },
+                "unknown_g_command",
+            ),
+            (
+                ParsingError::InvalidFunctionArity {
+                    line_no: 1,
+                    preview: s(),
+                    name: s(),
+                    expected: 1,
+                    actual: 2,
+                },
+                "invalid_function_arity",
+            ),
+        ];
+        for (err, expected) in &cases {
+            assert_eq!(err.kind(), *expected, "kind mismatch for {err:?}");
+        }
+        // Every kind string is distinct (no two variants share a discriminator).
+        let mut kinds: Vec<&str> = cases.iter().map(|(_, k)| *k).collect();
+        kinds.sort_unstable();
+        let unique = kinds.len();
+        kinds.dedup();
+        assert_eq!(kinds.len(), unique, "duplicate kind discriminator");
+    }
 }

{nc_gcode_interpreter-0.2.2 → nc_gcode_interpreter-0.2.3}/src/interpret_rules.rs

@@ -1168,9 +1168,17 @@ fn interpret_definition(element: Pair<Rule>, output: &mut Output, state: &mut St
                 let (line_no, preview) = get_error_context(&pair, state);
                 let res = interpret_assignment(pair, state)?;
                 if state.is_axis(res.0.as_str()) {
-                    return Err(ParsingError::AxisUsedAsVariable { name: res.0 });
+                    return Err(ParsingError::AxisUsedAsVariable {
+                        name: res.0,
+                        line_no,
+                        preview,
+                    });
                 } else if state.is_block_address(res.0.as_str()) {
-                    return Err(ParsingError::ReservedNameUsedAsVariable { name: res.0 });
+                    return Err(ParsingError::ReservedNameUsedAsVariable {
+                        name: res.0,
+                        line_no,
+                        preview,
+                    });
                 }
                 match res.1 {
                     Some(value) => {
@@ -1207,11 +1215,20 @@ fn interpret_definition(element: Pair<Rule>, output: &mut Output, state: &mut St
                 }
             }
             Rule::variable => {
+                let (line_no, preview) = get_error_context(&pair, state);
                 let key = interpret_variable(pair, state)?;
                 if state.is_axis(&key) {
-                    return Err(ParsingError::AxisUsedAsVariable { name: key });
+                    return Err(ParsingError::AxisUsedAsVariable {
+                        name: key,
+                        line_no,
+                        preview,
+                    });
                 } else if state.is_block_address(&key) {
-                    return Err(ParsingError::ReservedNameUsedAsVariable { name: key });
+                    return Err(ParsingError::ReservedNameUsedAsVariable {
+                        name: key,
+                        line_no,
+                        preview,
+                    });
                 }
                 if is_string {
                     state.string_table.insert(key.clone(), String::new());
@@ -1883,6 +1900,8 @@ fn frame_assignments(pairs: Vec<Pair<Rule>>, state: &mut State) -> Result<Vec<(S
             return Err(ParsingError::UnexpectedAxis {
                 axis: key,
                 axes: state.axis_identifiers.join(", "),
+                line_no: pair_line_no,
+                preview: pair_preview,
             });
         }
         result.push((key, value));
@@ -1908,14 +1927,14 @@ fn interpret_frame_op(element: Pair<Rule>, state: &mut State) -> Result<(), Pars
             // frames"). Bare TRANS is therefore just the reset.
             state.reset_translations();
             for (key, value) in frame_assignments(assignments, state)? {
-                state.update_translation(&key, value)?;
+                state.update_translation(&key, value, line_no, &preview)?;
             }
             Ok(())
         }
         "ATRANS" => {
             for (key, value) in frame_assignments(assignments, state)? {
                 let current_translation = state.get_translation(&key);
-                state.update_translation(&key, current_translation + value)?;
+                state.update_translation(&key, current_translation + value, line_no, &preview)?;
             }
             Ok(())
         }

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

@@ -71,15 +71,18 @@ mod python_bindings {
         "NC parse/interpret error. Subclasses ValueError (so `except ValueError` \
          still catches it) and carries the error's source location as data: the \
          `line`, `column`, `context`, and `line_text` attributes (each an int / \
-         str, or None when not applicable). `str(err)` is the full formatted \
-         message as before."
+         str, or None when not applicable), plus a stable `kind` string \
+         discriminating the error class (e.g. 'unexpected_axis', \
+         'undefined_variable') for branching without matching the message. \
+         `str(err)` is the full formatted message as before."
     );
 
-    /// An error crossing the worker channel: the formatted message plus the
-    /// structured location, so the consuming thread can raise an `NcError`
-    /// carrying both.
+    /// An error crossing the worker channel: the formatted message, the stable
+    /// error-kind discriminator, and the structured location, so the consuming
+    /// thread can raise an `NcError` carrying all three.
     struct ErrInfo {
         message: String,
+        kind: &'static str,
         location: Option<ErrorLocation>,
     }
 
@@ -87,13 +90,14 @@ mod python_bindings {
         fn from_error(error: &crate::errors::ParsingError) -> Self {
             ErrInfo {
                 message: error.to_string(),
+                kind: error.kind(),
                 location: error.location(),
             }
         }
 
-        /// Build the Python `NcError`, always setting the four location
-        /// attributes (None when absent) so callers can read them
-        /// unconditionally.
+        /// Build the Python `NcError`, always setting the `kind` discriminator
+        /// and the four location attributes (None when absent) so callers can
+        /// read them unconditionally.
         fn into_pyerr(self, py: Python<'_>) -> PyErr {
             let err = NcError::new_err(self.message);
             let value = err.value(py);
@@ -101,6 +105,7 @@ mod python_bindings {
                 Some(l) => (Some(l.line), l.column, l.context, l.line_text),
                 None => (None, None, None, None),
             };
+            let _ = value.setattr("kind", self.kind);
             let _ = value.setattr("line", line);
             let _ = value.setattr("column", column);
             let _ = value.setattr("context", context);

{nc_gcode_interpreter-0.2.2 → nc_gcode_interpreter-0.2.3}/src/state.rs

@@ -226,7 +226,13 @@ impl State {
     }
 
     /// Updates the translation value for an axis
-    pub fn update_translation(&mut self, axis: &str, value: f64) -> Result<(), ParsingError> {
+    pub fn update_translation(
+        &mut self,
+        axis: &str,
+        value: f64,
+        line_no: usize,
+        preview: &str,
+    ) -> Result<(), ParsingError> {
         if self.is_axis(axis) {
             self.translation.insert(axis.to_string(), value);
             Ok(())
@@ -234,6 +240,8 @@ impl State {
             Err(ParsingError::UnexpectedAxis {
                 axis: axis.to_string(),
                 axes: self.axis_identifiers.join(", "),
+                line_no,
+                preview: preview.to_string(),
             })
         }
     }