Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/serial_monitor.py

@@ -0,0 +1,172 @@
+"""PC-side Serial monitor for ``upload()`` sketches (BARMAJA PyArduino 1.1.0.dev8).
+
+After a successful compile AND upload the Arduino CLI has released the COM port.
+Only then does this module open the SAME port with pyserial and copy everything
+the Uno prints into the host's normal Python console (PyCharm Run, IDLE,
+terminal ...). The sketch itself is a normal standalone Arduino program: it
+keeps running when the monitor is closed or the USB cable is removed.
+
+NEVER use this module while LiveRun/Telemetrix owns the port.  LiveRun has its
+own stdout compatibility layer (see ``Serial`` in ``__init__``).
+
+Environment variables (all optional, for advanced users / teachers):
+    BARMAJA_SERIAL_MONITOR   auto (default) | off     - never changes student code
+    BARMAJA_SERIAL_WAIT      seconds to wait for the Uno bootloader after the
+                             port is opened (default 0.0; bytes are buffered by
+                             the OS so startup output is not lost)
+    BARMAJA_SERIAL_OPEN_TRIES  attempts to open the freshly released port (default 8)
+"""
+from __future__ import annotations
+
+import codecs
+import os
+import sys
+import time
+from typing import Callable
+
+__all__ = ["monitor_baud", "monitor_enabled", "stream_serial_output"]
+
+_OFF = {"0", "off", "false", "no", "none", "disabled"}
+DEFAULT_BAUD = 9600
+
+
+def monitor_baud(result) -> int | None:
+    """Return the baud for a compiled sketch that writes to Serial, else None.
+
+    Uses compiler metadata (TargetPlan), not text search of the generated C++:
+    * ``print()``, ``Serial.print()``, ``Serial.println()`` and ``Serial.write()``
+      set ``serial_output``;
+    * ``resolved_serial_baud`` is the single compile-time baud that the compiler
+      itself emitted (automatic 9600 for ``print()``, or the explicit value).
+    A sketch with only ``Serial.begin()`` / ``Serial.read()`` has no output, so an
+    LED-only or input-only program exits normally instead of blocking forever.
+    """
+    plan = getattr(result, "target_plan", None)
+    if plan is None or not getattr(plan, "serial_output", False):
+        return None
+    baud = getattr(plan, "resolved_serial_baud", None)
+    return int(baud) if baud else DEFAULT_BAUD
+
+
+def monitor_enabled(requested: bool | None = None) -> bool:
+    """``upload(monitor=False)`` wins, then ``BARMAJA_SERIAL_MONITOR``."""
+    if requested is not None:
+        return bool(requested)
+    return os.environ.get("BARMAJA_SERIAL_MONITOR", "auto").strip().lower() not in _OFF
+
+
+def _float_env(name: str, default: float) -> float:
+    try:
+        return max(0.0, float(os.environ.get(name, default)))
+    except ValueError:
+        return default
+
+
+def _int_env(name: str, default: int) -> int:
+    try:
+        return max(1, int(os.environ.get(name, default)))
+    except ValueError:
+        return default
+
+
+def _write_console(text: str) -> None:
+    """Write to stdout without ever raising on odd characters (cp1252 consoles)."""
+    try:
+        sys.stdout.write(text)
+    except UnicodeEncodeError:
+        enc = getattr(sys.stdout, "encoding", None) or "ascii"
+        sys.stdout.write(text.encode(enc, errors="replace").decode(enc, errors="replace"))
+    try:
+        sys.stdout.flush()
+    except Exception:
+        pass
+
+
+def _open_with_retry(serial_module, port: str, baud: int, tries: int):
+    """Open the COM port. Windows may need a moment after avrdude releases it."""
+    last: BaseException | None = None
+    for attempt in range(tries):
+        try:
+            return serial_module.Serial(port=port, baudrate=baud, timeout=0.2)
+        except Exception as exc:  # SerialException / PermissionError / OSError
+            last = exc
+            text = str(exc).lower()
+            busy = any(w in text for w in ("access is denied", "permissionerror", "busy", "denied"))
+            gone = any(w in text for w in ("could not open", "file not found", "cannot find"))
+            if attempt + 1 < tries and (busy or gone):
+                time.sleep(0.4)
+                continue
+            break
+    assert last is not None
+    raise last
+
+
+def stream_serial_output(
+    port: str,
+    baud: int,
+    *,
+    announce: Callable[..., None] = print,
+) -> int:
+    """Show the Uno's Serial output until Ctrl+C / IDE Stop / USB removal.
+
+    Returns 0 after a normal stop, 1 if the monitor could not run.  The upload has
+    already succeeded in both cases; the monitor never changes what the Arduino
+    does.  The port is always closed in ``finally``.
+    """
+    try:
+        import serial  # pyserial 3.5 (pinned, bundled with the offline package)
+    except ImportError:
+        announce("Serial viewer unavailable: pyserial is not installed. "
+                 "Open the Arduino IDE Serial Monitor instead.")
+        return 1
+
+    announce(f"Serial output from {port} at {baud} baud. Press Ctrl+C (or Stop) to stop viewing.")
+    announce("(The Arduino keeps running its program after the viewer stops.)")
+    announce("")
+    decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+    connection = None
+    try:
+        connection = _open_with_retry(serial, port, baud, _int_env("BARMAJA_SERIAL_OPEN_TRIES", 8))
+        wait = _float_env("BARMAJA_SERIAL_WAIT", 0.0)
+        if wait:
+            time.sleep(wait)
+        while True:
+            # read(1) blocks at most `timeout`; then drain whatever else is waiting.
+            chunk = connection.read(1)
+            if chunk:
+                try:
+                    waiting = connection.in_waiting
+                except Exception:
+                    waiting = 0
+                if waiting:
+                    chunk += connection.read(min(waiting, 4096))
+                text = decoder.decode(chunk)
+                if text:
+                    _write_console(text)
+        # unreachable
+    except KeyboardInterrupt:
+        announce("")
+        announce("Serial viewer stopped. The Arduino continues running its program.")
+        return 0
+    except Exception as exc:
+        tail = decoder.decode(b"", final=True)
+        if tail:
+            _write_console(tail)
+        text = str(exc).lower()
+        announce("")
+        if any(w in text for w in ("access is denied", "permissionerror", "busy", "denied")):
+            announce(f"Serial viewer could not open {port}: the port is in use.")
+            announce("Close the Arduino IDE / PictoBlox Serial Monitor (only one program can use the port), then run again.")
+        elif connection is not None:
+            announce(f"Serial viewer stopped: the connection to {port} was lost (USB unplugged?).")
+            announce("The Arduino keeps running if it has power. Reconnect USB and run the program again to view it.")
+        else:
+            announce(f"Serial viewer could not open {port}: {exc}")
+            announce("The upload succeeded and the Arduino is running. Check the USB cable and COM port.")
+        return 1
+    finally:
+        if connection is not None:
+            try:
+                connection.close()
+            except Exception:
+                pass

Barmaja_PyArduino/source.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import ast
+import io
+import tokenize
+import warnings
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import SourceEncodingError, SourceSyntaxError
+
+# Barmaja 0.6.0 deliberately accepts one common Python grammar across every
+# supported host interpreter (3.10 and every newer version).  Newer host-only syntax must
+# not silently become valid just because a teacher upgraded Python.
+COMMON_PYTHON_FEATURE_VERSION = 10
+
+def _parser_feature_version(version_info=None):
+    """Return the grammar minor version usable by this host.
+
+    Normal Barmaja hosts are Python 3.10 or newer and therefore always parse the
+    common Python-3.10 grammar. PictoBlox V1 currently embeds CPython 3.8.10;
+    that host cannot request a future grammar from ast.parse(), so use its own
+    3.8 grammar. The supported Barmaja student subset does not depend on
+    Python-3.9/3.10-only syntax, so this does not change supported-language
+    semantics; it only lets the same compiler run inside the mandatory
+    PictoBlox host.
+    """
+    vi = version_info or sys.version_info
+    major = int(vi[0])
+    minor = int(vi[1])
+    if major != 3:
+        return COMMON_PYTHON_FEATURE_VERSION
+    return min(COMMON_PYTHON_FEATURE_VERSION, minor)
+
+
+@dataclass(frozen=True)
+class SourceSpan:
+    """A source location using Python's 1-based lines / 0-based columns."""
+
+    line: int
+    column: int
+    end_line: int
+    end_column: int
+
+
+@dataclass(frozen=True)
+class ParsedSource:
+    """Phase-A output: decoded source, parsed AST, tokens, and source identity."""
+
+    filename: str
+    text: str
+    tree: ast.Module
+    tokens: tuple[tokenize.TokenInfo, ...]
+
+    def span_for(self, node: ast.AST) -> SourceSpan | None:
+        line = getattr(node, "lineno", None)
+        column = getattr(node, "col_offset", None)
+        if line is None or column is None:
+            return None
+        end_line = getattr(node, "end_lineno", None) or line
+        end_column = getattr(node, "end_col_offset", None)
+        if end_column is None:
+            end_column = column
+        return SourceSpan(line, column, end_line, end_column)
+
+
+def _syntax_error_from(exc: SyntaxError, filename: str) -> SourceSyntaxError:
+    # SyntaxError.offset is 1-based while ast node col_offset is 0-based.  The
+    # existing student-facing CompileError contract also uses the syntax-style
+    # 1-based column, so preserve that here.
+    return SourceSyntaxError(
+        exc.msg or "Invalid Python syntax.",
+        line=exc.lineno,
+        column=exc.offset,
+        end_line=getattr(exc, "end_lineno", None),
+        end_column=getattr(exc, "end_offset", None),
+        source=filename,
+    )
+
+
+
+class _Py38SubscriptNormalizer(ast.NodeTransformer):
+    """Rewrite Python 3.8 ast.Index/ast.ExtSlice to the Python 3.9+ shape."""
+
+    def visit_Index(self, node):  # Python 3.8 only
+        return self.visit(node.value)
+
+    def visit_ExtSlice(self, node):  # Python 3.8 only
+        dims = [self.visit(d) for d in node.dims]
+        return ast.Tuple(elts=dims, ctx=ast.Load())
+
+
+def _normalize_py38_subscripts(tree: ast.Module) -> ast.Module:
+    tree = _Py38SubscriptNormalizer().visit(tree)
+    return ast.fix_missing_locations(tree)
+
+
+def parse_source_text(source: str, source_path: str | Path | None = None) -> ParsedSource:
+    """Parse text using the common Barmaja Python-3.10 grammar profile."""
+
+    filename = str(source_path or "<student.py>")
+
+    # compile_text() may receive text copied from a UTF-8-with-BOM file.  The
+    # file loader already strips it through utf-8-sig, but accepting it here
+    # keeps the public text API deterministic too.
+    if source.startswith("\ufeff"):
+        source = source[1:]
+
+    try:
+        # Python-level SyntaxWarning/DeprecationWarning text (for example an
+        # invalid escape such as "C:\path") must not leak to the student's
+        # console as a raw interpreter message during compilation.
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            tree = ast.parse(
+                source,
+                filename=filename,
+                mode="exec",
+                feature_version=_parser_feature_version(),
+            )
+    except SyntaxError as exc:
+        raise _syntax_error_from(exc, filename) from None
+    except UnicodeEncodeError:  # (a ValueError subclass; must precede it)
+        # Only reachable through the text API: a lone surrogate cannot come from a UTF-8 file.
+        raise SourceEncodingError(
+            "Source text contains characters that cannot be saved as UTF-8. Save the Python file as UTF-8 and try again.",
+            source=filename,
+        ) from None
+    except ValueError as exc:
+        # Python 3.10/3.11 report NUL bytes as ValueError instead of SyntaxError.
+        raise SourceSyntaxError(
+            str(exc) or "Invalid Python source.",
+            source=filename,
+        ) from None
+    except (RecursionError, MemoryError):
+        # CPython 3.11-3.13 raise RecursionError while building very deep ASTs
+        # (for example thousands of chained '+' terms) instead of SyntaxError.
+        raise SourceSyntaxError(
+            "This expression or statement is nested too deeply for Barmaja PyArduino. Split it into smaller steps.",
+            source=filename,
+        ) from None
+
+    if sys.version_info < (3, 9):
+        # PictoBlox embeds CPython 3.8, whose AST wraps subscripts in
+        # ast.Index / ast.ExtSlice. Normalize to the 3.9+ shape so every later
+        # phase sees one AST on every supported host.
+        tree = _normalize_py38_subscripts(tree)
+
+    # Token data is part of the Phase-A contract and is intentionally captured
+    # now so later diagnostics do not need to re-tokenize a possibly transformed
+    # representation of the source.
+    try:
+        tokens = tuple(tokenize.generate_tokens(io.StringIO(source).readline))
+    except (RecursionError, MemoryError):
+        raise SourceSyntaxError(
+            "This expression or statement is nested too deeply for Barmaja PyArduino. Split it into smaller steps.",
+            source=filename,
+        ) from None
+    except (tokenize.TokenError, IndentationError) as exc:
+        # ast.parse normally catches these first, but keep the source boundary
+        # closed and student-facing if tokenization ever disagrees.
+        message = exc.args[0] if exc.args else "Invalid Python source."
+        location = exc.args[1] if len(exc.args) > 1 and isinstance(exc.args[1], tuple) else None
+        line = location[0] if location else None
+        column = (location[1] + 1) if location else None
+        raise SourceSyntaxError(str(message), line=line, column=column, source=filename) from None
+
+    return ParsedSource(filename=filename, text=source, tree=tree, tokens=tokens)
+
+
+def load_source_file(path: str | Path) -> ParsedSource:
+    """Read a student source file as UTF-8/UTF-8-BOM and parse it."""
+
+    p = Path(path)
+    raw = p.read_bytes()
+    try:
+        text = raw.decode("utf-8-sig")
+    except UnicodeDecodeError as exc:
+        raise SourceEncodingError(
+            "Source file is not valid UTF-8. Save the Python file as UTF-8 and try again.",
+            source=str(p),
+        ) from None
+    return parse_source_text(text, p)

Barmaja_PyArduino/stubgen.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+"""Generate the public typing stub directly from the formal API registry.
+
+The generated stub is editor-neutral. Any Python IDE/type checker that understands
+PEP 484/561 can use it. PictoBlox remains a mandatory supported host, but the
+stub itself contains no IDE-specific integration.
+"""
+
+from pathlib import Path
+
+from .api_registry import CONSTANT_VALUES, CORE_FUNCTIONS, HARDWARE_CLASSES, SINGLETONS, SignatureSpec
+
+
+_ARG_NAMES = {
+    "pinMode": ("pin", "mode"),
+    "digitalWrite": ("pin", "value"),
+    "digitalRead": ("pin",),
+    "analogRead": ("pin",),
+    "analogWrite": ("pin", "value"),
+    "delay": ("milliseconds",),
+    "tone": ("pin", "frequency", "duration"),
+    "noTone": ("pin",),
+    "delayMicroseconds": ("microseconds",),
+    "map": ("value", "in_min", "in_max", "out_min", "out_max"),
+    "constrain": ("value", "lower", "upper"),
+    "Servo.__init__": (),
+    "Servo.attach": ("pin", "min_us", "max_us"),
+    "Servo.write": ("angle",),
+    "Servo.writeMicroseconds": ("microseconds",),
+    "Ultrasonic.__init__": ("trigger_pin", "echo_pin"),
+    "Ultrasonic.read": ("unit",),
+    "Ultrasonic.setTimeout": ("timeout",),
+    "DHT.__init__": ("pin", "sensor_type"),
+    "LiquidCrystal_I2C.__init__": ("address", "columns", "rows"),
+    "LiquidCrystal_I2C.begin": ("columns", "rows", "charsize"),
+    "LiquidCrystal_I2C.setCursor": ("column", "row"),
+    "LiquidCrystal_I2C.print": ("value",),
+    "Serial.begin": ("baud",),
+    "Serial.print": ("value", "format"),
+    "Serial.println": ("value", "format"),
+    "Wire.beginTransmission": ("address",),
+    "Wire.write": ("value",),
+    "Wire.requestFrom": ("address", "count"),
+}
+
+_TYPE_MAP = {
+    "Void": "None",
+    "Bool": "bool",
+    "Int": "int",
+    "Float": "float",
+    "String": "str",
+    "TimeU32": "TimeU32",
+    "IntOrBool": "IntOrBool",
+    "NumericOrBool": "NumericOrBool",
+    "Scalar": "Scalar",
+    "UltrasonicUnit": "UltrasonicUnit",
+    "DHTType": "DHTType",
+}
+
+
+def _py_type(token: str) -> str:
+    if token.startswith("Hardware["):
+        return token[len("Hardware["):-1]
+    return _TYPE_MAP.get(token, "int")
+
+
+def _params(sig: SignatureSpec, *, method: bool = False, key: str = "") -> str:
+    parts = ["self"] if method else []
+    names = _ARG_NAMES.get(key, ())
+    for i, token in enumerate(sig.args):
+        name = names[i] if i < len(names) else f"arg{i}"
+        parts.append(f"{name}: {_py_type(token)}")
+    if not sig.args and method:
+        return "self"
+    return ", ".join(parts)
+
+
+def _emit_callable(name: str, signatures: tuple[SignatureSpec, ...], *, indent: str = "", method: bool = False, key: str = "") -> list[str]:
+    lines: list[str] = []
+    if len(signatures) > 1:
+        for sig in signatures:
+            lines.append(f"{indent}@overload")
+            lines.append(f"{indent}def {name}({_params(sig, method=method, key=key)}) -> {_py_type(sig.returns)}: ...")
+    else:
+        sig = signatures[0]
+        lines.append(f"{indent}def {name}({_params(sig, method=method, key=key)}) -> {_py_type(sig.returns)}: ...")
+    return lines
+
+
+def render_stub() -> str:
+    lines = [
+        "# AUTO-GENERATED by Barmaja_PyArduino.stubgen from api_registry.py.",
+        "# Do not edit manually; change the registry and regenerate.",
+        "from typing import Final, TypeAlias, overload",
+        "",
+        "TimeU32: TypeAlias = int",
+        "IntOrBool: TypeAlias = int | bool",
+        "NumericOrBool: TypeAlias = int | float | bool",
+        "Scalar: TypeAlias = int | float | bool | str",
+        "UltrasonicUnit: TypeAlias = int",
+        "DHTType: TypeAlias = int",
+        "",
+    ]
+
+    for name in CONSTANT_VALUES:
+        lines.append(f"{name}: Final[int]")
+    lines.append("")
+
+    for name, spec in CORE_FUNCTIONS.items():
+        lines.extend(_emit_callable(name, spec.signatures, key=name))
+    lines.append("")
+
+    for class_name, spec in HARDWARE_CLASSES.items():
+        lines.append(f"class {class_name}:")
+        ctor_sigs = tuple(SignatureSpec(s.args, "Void", s.constraints) for s in spec.constructors)
+        lines.extend(_emit_callable("__init__", ctor_sigs, indent="    ", method=True, key=f"{class_name}.__init__"))
+        for method_name, method_spec in spec.methods.items():
+            lines.extend(_emit_callable(method_name, method_spec.signatures, indent="    ", method=True, key=f"{class_name}.{method_name}"))
+        lines.append("")
+
+    for singleton_name, spec in SINGLETONS.items():
+        cls = f"_{singleton_name}API"
+        lines.append(f"class {cls}:")
+        for method_name, method_spec in spec.methods.items():
+            lines.extend(_emit_callable(method_name, method_spec.signatures, indent="    ", method=True, key=f"{singleton_name}.{method_name}"))
+        lines.append(f"{singleton_name}: Final[{cls}]")
+        lines.append("")
+
+    lines.append("def upload(path: str | None = None, *, port: str | None = None, monitor: bool | None = None) -> None: ...")
+    lines.append("def verify(path: str | None = None) -> None: ...")
+    lines.append("def show_code(path: str | None = None) -> None: ...")
+    lines.append("def LiveRun(port: str | None = None, *, auto_firmware: bool = True, debug: bool = False): ...")
+    lines.append("def LiveStop() -> None: ...")
+    lines.append("")
+    lines.append("def doctor_pictoblox(*, details: bool = False) -> str: ...")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def write_stub(path: str | Path | None = None) -> Path:
+    target = Path(path) if path is not None else Path(__file__).with_name("__init__.pyi")
+    target.write_text(render_stub(), encoding="utf-8", newline="\n")
+    return target
+
+
+if __name__ == "__main__":
+    print(write_stub())