Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/errors.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """Stable machine-readable diagnostic metadata for CLI/IDE integrations."""
+
+    code: str
+    message: str
+    line: int | None = None
+    column: int | None = None
+    end_line: int | None = None
+    end_column: int | None = None
+    source: str | None = None
+    details: str | None = None
+
+
+class BarmajaError(Exception):
+    """Base class for Barmaja PyArduino user-facing errors."""
+
+    code = "BJ0000"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        line: int | None = None,
+        column: int | None = None,
+        end_line: int | None = None,
+        end_column: int | None = None,
+        source: str | None = None,
+        details: str | None = None,
+    ):
+        self.message = message
+        self.line = line
+        self.column = column
+        self.end_line = end_line
+        self.end_column = end_column
+        self.source = source
+        self.details = details
+        super().__init__(self._human_message())
+
+    def _human_message(self) -> str:
+        prefix = ""
+        if self.line is not None:
+            prefix = f"Line {self.line}"
+            if self.column is not None:
+                prefix += f":{self.column}"
+            prefix += ": "
+        return prefix + self.message
+
+    @property
+    def diagnostic(self) -> Diagnostic:
+        return Diagnostic(
+            code=self.code,
+            message=self.message,
+            line=self.line,
+            column=self.column,
+            end_line=self.end_line,
+            end_column=self.end_column,
+            source=self.source,
+            details=self.details,
+        )
+
+
+class CompileError(BarmajaError):
+    code = "BJ1000"
+
+    # Preserve the 0.5 public positional constructor used throughout compiler.py.
+    def __init__(
+        self,
+        message: str,
+        line: int | None = None,
+        column: int | None = None,
+        *,
+        end_line: int | None = None,
+        end_column: int | None = None,
+        source: str | None = None,
+        details: str | None = None,
+    ):
+        super().__init__(
+            message,
+            line=line,
+            column=column,
+            end_line=end_line,
+            end_column=end_column,
+            source=source,
+            details=details,
+        )
+
+
+class SourceSyntaxError(CompileError):
+    """Invalid source syntax under the common Barmaja grammar profile."""
+
+    code = "BJ1001"
+
+
+class SourceEncodingError(CompileError):
+    """Student source could not be decoded as UTF-8/UTF-8-BOM."""
+
+    code = "BJ1002"
+
+
+class UnsupportedFeatureError(CompileError):
+    """Valid Python that is intentionally outside the Barmaja V1 subset."""
+
+    code = "BJ1100"
+
+
+class NameResolutionError(CompileError):
+    """Undefined/conflicting/protected name under Barmaja Python scope rules."""
+
+    code = "BJ1200"
+
+
+class TypeCheckError(CompileError):
+    """Static type error in the supported Barmaja Python subset."""
+
+    code = "BJ1300"
+
+
+class NumericRangeError(TypeCheckError):
+    """Numeric value/range is outside the supported target-safe domain."""
+
+    code = "BJ1310"
+
+
+class HardwareError(CompileError):
+    """Hard target/board/resource violation."""
+
+    code = "BJ3000"
+
+
+class ToolchainError(BarmajaError):
+    code = "BJ5000"
+
+
+class BoardDetectionError(BarmajaError):
+    code = "BJ5100"
+
+    def __init__(self, message: str, *, reason: str | None = None, ports=(), **kwargs):
+        self.reason = reason
+        self.ports = tuple(ports or ())
+        super().__init__(message, **kwargs)
+
+
+class InternalCompilerError(BarmajaError):
+    """Unexpected compiler defect translated to a safe, stable user error."""
+
+    code = "BJ9000"
+
+
+def format_error(error: BarmajaError, *, details: bool = False) -> str:
+    """Common CLI/UI representation; technical details are opt-in."""
+
+    text = f"Barmaja PyArduino: {error}"
+    if details:
+        meta = [f"Code: {error.code}"]
+        if error.source:
+            meta.append(f"Source: {error.source}")
+        if error.details:
+            meta.append(f"Details: {error.details}")
+        text += "\n" + "\n".join(meta)
+    return text