Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/library_adder.py

@@ -0,0 +1,440 @@
+"""BARMAJA Library Adder: add any Arduino library to BARMAJA PyArduino (upload() mode).
+
+Window:   python -m Barmaja_PyArduino add-library
+Headless: python -m Barmaja_PyArduino add-library <library.zip|folder> --auto [--class X] [--name Y] [--no-compile]
+Remove:   python -m Barmaja_PyArduino remove-pack <StudentClass>
+
+What "Add" does on this PC (no internet, no admin rights needed for the BARMAJA folder):
+  * copies the Arduino library to  <BARMAJA root>/arduino-libraries/<folder>
+  * writes the device pack to      <BARMAJA root>/device-packs/<StudentClass>
+  * replaced items are moved to    <BARMAJA root>/backups/   (never deleted)
+The next program run (PyCharm, IDLE, PictoBlox) can use the new class immediately.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import textwrap
+import threading
+import time
+from pathlib import Path
+
+from . import pack_builder as pb
+
+ADDED_MARKER = ".barmaja_added_by_library_adder"
+PKG_PARENT = str(Path(__file__).resolve().parent.parent)
+
+
+# ---------------- paths / install / remove ----------------
+def runtime_paths() -> dict[str, Path]:
+    from .environment import ensure_runtime_dirs
+    root = ensure_runtime_dirs()["root"]
+    return {"root": root, "libraries": root / "arduino-libraries", "packs": root / "device-packs", "backups": root / "backups"}
+
+
+def _backup(path: Path, paths: dict[str, Path]) -> Path:
+    stamp = time.strftime('%Y%m%d-%H%M%S')
+    dest = paths["backups"] / f"{path.name}-{stamp}"
+    n = 1
+    while dest.exists():
+        n += 1
+        dest = paths["backups"] / f"{path.name}-{stamp}-{n}"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(path), str(dest))
+    return dest
+
+
+def _lib_version(folder: Path) -> str:
+    props = folder / "library.properties"
+    if props.is_file():
+        for line in props.read_text(encoding="utf-8", errors="replace").splitlines():
+            if line.startswith("version="):
+                return line.split("=", 1)[1].strip()
+    return "?"
+
+
+def installed_library_names() -> dict[str, Path]:
+    """library.properties name (lower-case) -> folder, from every BARMAJA library root."""
+    from .toolchain import pinned_library_dirs
+    found: dict[str, Path] = {}
+    for folder in pinned_library_dirs():
+        props = folder / "library.properties"
+        try:
+            for line in props.read_text(encoding="utf-8", errors="replace").splitlines():
+                if line.startswith("name="):
+                    found[line.split("=", 1)[1].strip().lower()] = folder
+        except OSError:
+            pass
+        found.setdefault(folder.name.lower(), folder)
+    return found
+
+
+def missing_dependencies(lib: pb.LibraryScan) -> list[str]:
+    have = installed_library_names()
+    return [d for d in lib.depends if d.lower() not in have and d.replace(" ", "_").lower() not in have]
+
+
+def install_library_only(lib: pb.LibraryScan, *, replace_library: bool = False) -> list[str]:
+    """Copy just the Arduino library (e.g. a dependency such as 'Adafruit BusIO')."""
+    return install(lib, None, replace_library=replace_library)
+
+
+def install(lib: pb.LibraryScan, pack_folder: Path | None, *, replace_library: bool = False) -> list[str]:
+    paths = runtime_paths()
+    out: list[str] = []
+    paths["libraries"].mkdir(parents=True, exist_ok=True)
+    paths["packs"].mkdir(parents=True, exist_ok=True)
+    target = paths["libraries"] / lib.folder_name
+    if target.exists():
+        have = _lib_version(target)
+        if have == lib.version and not replace_library:
+            out.append(f"Library {lib.folder_name} {have} is already installed - kept.")
+        elif not (target / ADDED_MARKER).exists() and not replace_library:
+            raise RuntimeError(f"A different {lib.folder_name} ({have}) is already part of BARMAJA. "
+                               "It was not replaced, to protect existing projects.")
+        else:
+            out.append(f"Old library moved to {_backup(target, paths)}")
+            target = paths["libraries"] / lib.folder_name
+    if not target.exists():
+        shutil.copytree(lib.root, target, ignore=shutil.ignore_patterns(".*", "examples", "extras", "test", "tests", "docs"))
+        (target / ADDED_MARKER).write_text(time.strftime("%Y-%m-%d %H:%M:%S"), encoding="utf-8")
+        out.append(f"Library copied to {target}")
+    if pack_folder is None:
+        out.append("DONE. Library files installed (no student class).")
+        return out
+    spec = json.loads((pack_folder / "pack.json").read_text(encoding="utf-8"))
+    dest = paths["packs"] / spec["class"]
+    if dest.exists():
+        out.append(f"Previous pack moved to {_backup(dest, paths)}")
+    shutil.copytree(pack_folder, dest)
+    out.append(f"Device pack installed: {dest}")
+    out.append(f"DONE. Use {spec['class']}(...) in your upload() programs. Restart PictoBlox/IDLE if they are open.")
+    return out
+
+
+def installed_packs() -> list[dict]:
+    paths = runtime_paths()
+    out = []
+    if paths["packs"].is_dir():
+        for f in sorted(paths["packs"].iterdir()):
+            if (f / "pack.json").is_file():
+                try:
+                    spec = json.loads((f / "pack.json").read_text(encoding="utf-8"))
+                    out.append({"class": spec.get("class", f.name), "title": spec.get("title", ""), "folder": f,
+                                "libraries": [d.get("library_folder", d.get("name")) for d in spec.get("dependencies", [])]})
+                except (OSError, ValueError):
+                    out.append({"class": f.name, "title": "(unreadable pack.json)", "folder": f, "libraries": []})
+    return out
+
+
+def remove(class_name: str, *, remove_library: bool = True) -> list[str]:
+    paths = runtime_paths()
+    packs = installed_packs()
+    me = next((p for p in packs if p["class"] == class_name), None)
+    if me is None:
+        raise RuntimeError(f"No added pack named {class_name} (built-in packs cannot be removed here).")
+    out = [f"Pack moved to {_backup(me['folder'], paths)}"]
+    if remove_library:
+        others = {lib for p in packs if p is not me for lib in p["libraries"]}
+        for lib in me["libraries"]:
+            folder = paths["libraries"] / str(lib)
+            if lib in others:
+                out.append(f"Library {lib} kept (used by another pack)."); continue
+            if folder.is_dir() and (folder / ADDED_MARKER).exists():
+                out.append(f"Library moved to {_backup(folder, paths)}")
+            elif folder.is_dir():
+                out.append(f"Library {lib} kept (it is part of the BARMAJA installation).")
+    return out
+
+
+# ---------------- checking (fresh Python, like a real program run) ----------------
+def check(pack_folder: Path, library_root: Path, *, compile: bool = True) -> tuple[bool, list[str]]:
+    spec = json.loads((pack_folder / "pack.json").read_text(encoding="utf-8"))
+    holder = Path(tempfile.mkdtemp(prefix="barmaja_check_"))
+    (holder / "packs").mkdir(); (holder / "libs").mkdir()
+    shutil.copytree(pack_folder, holder / "packs" / pack_folder.name)
+    shutil.copytree(library_root, holder / "libs" / library_root.name,
+                    ignore=shutil.ignore_patterns(".*", "examples", "extras", "test", "tests", "docs"))
+    env = {**os.environ, "BARMAJA_DEVICE_PACKS": str(holder / "packs"), "BARMAJA_DEV_LIBRARIES": str(holder / "libs"),
+           "BARMAJA_SKIP_BUILTIN_PACKS": spec["class"]}
+    code = textwrap.dedent(f'''
+        import sys; sys.path.insert(0, {PKG_PARENT!r})
+        from Barmaja_PyArduino import device_packs as dp
+        from Barmaja_PyArduino.compiler import Transpiler
+        from Barmaja_PyArduino.errors import BarmajaError, format_error
+        cls = {spec["class"]!r}
+        if cls not in dp.LOADED:
+            print("FAIL  The pack was not accepted:", "; ".join(dp.LOAD_ERRORS)); sys.exit(1)
+        print("PASS  pack.json accepted")
+        try:
+            r = Transpiler().compile_text(open({str(pack_folder / "example.py")!r}, encoding="utf-8").read())
+        except BarmajaError as e:
+            print("FAIL  Example program:", " ".join(format_error(e).split())); sys.exit(1)
+        print("PASS  Example converted to Arduino C++")
+        if {compile!r}:
+            try:
+                from Barmaja_PyArduino.toolchain import compile_sketch
+                art = compile_sketch(r.cpp)
+                print("PASS  Arduino Uno compile OK:", art.memory)
+            except Exception as e:
+                text = " ".join(str(e).split())
+                low = text.lower()
+                if "compilation environment was not found" in low or "toolchain not found" in low or ("arduino-cli" in low and "not found" in low):
+                    print("SKIP  Arduino toolchain not found on this PC - compile test skipped:", text[:300])
+                else:
+                    print("FAIL  Arduino Uno compile:", text[:900]); sys.exit(1)
+    ''')
+    try:
+        res = subprocess.run([sys.executable, "-I", "-c", code], env=env, text=True, capture_output=True, timeout=600)
+    finally:
+        shutil.rmtree(holder, ignore_errors=True)
+    lines = [l for l in (res.stdout + ("\n" + res.stderr.strip()[-1200:] if res.returncode and res.stderr.strip() else "")).splitlines() if l.strip()]
+    return res.returncode == 0, lines
+
+
+def add_library_auto(path: str, *, cls: str | None = None, student: str | None = None,
+                     compile: bool = True, do_install: bool = True, say=print) -> int:
+    root = pb.open_library(path)
+    lib = pb.scan_library(root)
+    say(f"Library: {lib.name} {lib.version}   licence: {lib.license}")
+    if lib.license_warning:
+        say("NOTE  " + lib.license_warning)
+    for p in lib.problems:
+        say("NOTE  " + p)
+    missing = missing_dependencies(lib)
+    if lib.depends:
+        say("Needs also: " + ", ".join(lib.depends) + (f"   MISSING: {', '.join(missing)} - add those libraries first" if missing else "   (all found)"))
+    cls = cls or pb.main_class(lib)
+    if not cls or cls not in lib.classes:
+        say(f"FAIL  Class not found. Classes: {', '.join(lib.classes) or 'none'}"); return 1
+    student = student or pb.default_student_name(cls)
+    spec, adapter, example = pb.build_pack(lib, cls, student, ctor_index=-1)
+    say(f"Class {cls} -> student class {student} with {len(spec['methods'])} methods")
+    if lib.classes[cls].skipped:
+        say(f"NOTE  {len(lib.classes[cls].skipped)} method(s) not converted (see notes in pack.json)")
+    work = Path(tempfile.mkdtemp(prefix="barmaja_pack_"))
+    folder = pb.write_pack(work, spec, adapter)
+    ok, lines = check(folder, root, compile=compile)
+    for line in lines:
+        say(line)
+    if not ok:
+        say(f"Pack NOT installed. Draft kept for editing: {folder}"); return 1
+    compiled = any("Arduino Uno compile OK" in l for l in lines)
+    if do_install and missing and not compiled:
+        say("NOT INSTALLED: add the missing libraries first (add-library <zip> --auto works for them too), then run again.")
+        say(f"Draft kept: {folder}"); return 1
+    if do_install:
+        for line in install(lib, folder):
+            say(line)
+    else:
+        say(f"Checked only (not installed). Pack folder: {folder}")
+    return 0
+
+
+# ---------------- window ----------------
+def run_gui(initial: str | None = None) -> int:
+    import tkinter as tk
+    from tkinter import filedialog, messagebox, ttk
+
+    root = tk.Tk()
+    root.title("BARMAJA Library Adder - add an Arduino library")
+    root.geometry("1080x740")
+    try:
+        ico = Path(__file__).resolve().parent / "BARMAJA_PyArduino.ico"
+        if ico.is_file() and os.name == "nt":
+            root.iconbitmap(str(ico))
+    except Exception:
+        pass
+    state: dict = {"lib": None, "folder": None}
+
+    top = ttk.Frame(root, padding=8); top.pack(fill="x")
+    ttk.Label(top, text="1. Arduino library:", font=("Segoe UI", 10, "bold")).pack(side="left")
+    path_var = tk.StringVar(value="Choose a library ZIP (e.g. downloaded from GitHub) or its folder")
+    ttk.Button(top, text="Choose ZIP...", command=lambda: load(filedialog.askopenfilename(filetypes=[("Arduino library ZIP", "*.zip")]))).pack(side="left", padx=4)
+    ttk.Button(top, text="Choose folder...", command=lambda: load(filedialog.askdirectory())).pack(side="left")
+    ttk.Label(top, textvariable=path_var, foreground="#555").pack(side="left", padx=8)
+
+    info_var = tk.StringVar(value="")
+    ttk.Label(root, textvariable=info_var, padding=(8, 0)).pack(fill="x")
+
+    mid = ttk.Frame(root, padding=8); mid.pack(fill="x")
+    ttk.Label(mid, text="2. Library class:").grid(row=0, column=0, sticky="w")
+    class_var = tk.StringVar(); class_box = ttk.Combobox(mid, textvariable=class_var, state="readonly", width=34)
+    class_box.grid(row=0, column=1, sticky="w", padx=4)
+    ttk.Label(mid, text="Name for students:").grid(row=0, column=2, sticky="w", padx=(16, 0))
+    student_var = tk.StringVar(); ttk.Entry(mid, textvariable=student_var, width=26).grid(row=0, column=3, sticky="w", padx=4)
+    ttk.Label(mid, text="Constructor:").grid(row=1, column=0, sticky="w", pady=4)
+    ctor_var = tk.StringVar(); ctor_box = ttk.Combobox(mid, textvariable=ctor_var, state="readonly", width=60)
+    ctor_box.grid(row=1, column=1, columnspan=3, sticky="w", padx=4)
+    print_var = tk.BooleanVar(value=False)
+    print_chk = ttk.Checkbutton(mid, text="Add print()/println() (screens, displays)", variable=print_var)
+    print_chk.grid(row=2, column=1, columnspan=3, sticky="w", padx=4)
+
+    ttk.Label(root, text="3. Methods students can use (click a row to tick/untick; double-click the name to rename):", padding=(8, 2)).pack(fill="x")
+    cols = ("use", "student", "library", "params", "returns")
+    tree = ttk.Treeview(root, columns=cols, show="headings", height=13)
+    for c, w, t in [("use", 50, "Use"), ("student", 170, "Student name"), ("library", 170, "Library method"), ("params", 420, "Parameters (* = pin)"), ("returns", 80, "Returns")]:
+        tree.heading(c, text=t); tree.column(c, width=w, anchor="w")
+    tree.pack(fill="both", expand=False, padx=8)
+
+    btns = ttk.Frame(root, padding=8); btns.pack(fill="x")
+    log = tk.Text(root, height=12, wrap="word", font=("Consolas", 9)); log.pack(fill="both", expand=True, padx=8, pady=(0, 8))
+
+    def say(text: str) -> None:
+        def put():
+            log.insert("end", text + "\n"); log.see("end")
+        root.after(0, put)
+
+    def current_scan():
+        lib = state["lib"]
+        return lib.classes.get(class_var.get()) if lib else None
+
+    def fill_methods(*_):
+        scan = current_scan()
+        tree.delete(*tree.get_children())
+        if not scan:
+            return
+        student_var.set(pb.default_student_name(scan.name))
+        ctors = [", ".join(p.name + ("*" if p.is_pin else "") + (f"={p.default}" if p.default is not None else "") for p in c) or "(no arguments)" for c in scan.constructors]
+        ctor_box["values"] = ctors
+        ctor_box.current(pb.default_constructor(scan))
+        print_var.set(scan.printable)
+        for i, m in enumerate(scan.methods):
+            ps = ", ".join(f"{p.name}{'*' if p.is_pin else ''}: {p.type}" + (f"={p.default}" if p.default is not None else "") for p in m.params)
+            tree.insert("", "end", iid=str(i), values=("[x]" if m.selected else "[ ]", m.student_name, m.cpp_name, ps, m.returns))
+        if scan.skipped:
+            say(f"{len(scan.skipped)} method(s) cannot be converted automatically (arrays, pointers, objects):")
+            for s in scan.skipped[:12]:
+                say("   - " + s)
+
+    def toggle(event):
+        row = tree.identify_row(event.y); col = tree.identify_column(event.x)
+        scan = current_scan()
+        if not row or not scan or col == "#2":
+            return
+        m = scan.methods[int(row)]; m.selected = not m.selected
+        tree.set(row, "use", "[x]" if m.selected else "[ ]")
+
+    def rename(event):
+        row = tree.identify_row(event.y); scan = current_scan()
+        if not row or not scan or tree.identify_column(event.x) != "#2":
+            return
+        x, y, w, h = tree.bbox(row, "student")
+        entry = ttk.Entry(tree); entry.place(x=x, y=y, width=w, height=h)
+        entry.insert(0, scan.methods[int(row)].student_name); entry.focus()
+        def done(_=None):
+            new = entry.get().strip()
+            if new:
+                scan.methods[int(row)].student_name = new; tree.set(row, "student", new)
+            entry.destroy()
+        entry.bind("<Return>", done); entry.bind("<FocusOut>", done)
+
+    tree.bind("<Button-1>", toggle); tree.bind("<Double-1>", rename)
+    class_box.bind("<<ComboboxSelected>>", fill_methods)
+
+    def load(path):
+        if not path:
+            return
+        try:
+            libroot = pb.open_library(path)
+            lib = pb.scan_library(libroot)
+        except Exception as exc:
+            messagebox.showerror("Library Adder", str(exc)); return
+        state["lib"] = lib; path_var.set(str(path))
+        info_var.set(f"{lib.name}   version {lib.version}   licence {lib.license}" + (f"   ⚠ {lib.license_warning}" if lib.license_warning else ""))
+        log.delete("1.0", "end")
+        if lib.depends:
+            missing = missing_dependencies(lib)
+            say("This library also needs: " + ", ".join(lib.depends))
+            say(("   MISSING on this PC: " + ", ".join(missing) + " -> open each one here and press 'Add library files only' first.")
+                if missing else "   All of them are already installed.")
+        for p in lib.problems:
+            say("PROBLEM: " + p)
+        class_box["values"] = list(lib.classes)
+        main = pb.main_class(lib)
+        if main:
+            class_var.set(main); fill_methods()
+
+    def make_pack():
+        lib, scan = state["lib"], current_scan()
+        if not lib or not scan:
+            messagebox.showinfo("Library Adder", "Choose a library first."); return None
+        spec, adapter, _ = pb.build_pack(lib, scan.name, student_var.get().strip(), ctor_box.current(), add_print=print_var.get())
+        folder = pb.write_pack(Path(tempfile.mkdtemp(prefix="barmaja_pack_")), spec, adapter)
+        state["folder"] = folder
+        return lib, folder
+
+    def busy(flag: bool):
+        for b in (check_btn, add_btn):
+            b.state(["disabled"] if flag else ["!disabled"])
+
+    def run_check(then_install: bool):
+        try:
+            made = make_pack()
+        except ValueError as exc:
+            messagebox.showerror("Library Adder", str(exc)); return
+        if not made:
+            return
+        lib, folder = made
+        say("\nChecking... (converting the example and compiling it for Arduino Uno; this can take a minute)")
+        busy(True)
+        def work():
+            ok, lines = check(folder, lib.root, compile=True)
+            for l in lines:
+                say(l)
+            missing = missing_dependencies(lib)
+            compiled = any("Arduino Uno compile OK" in l for l in lines)
+            if ok and then_install and missing and not compiled:
+                say("NOT INSTALLED: first add the missing libraries: " + ", ".join(missing))
+            elif ok and then_install:
+                try:
+                    for l in install(lib, folder):
+                        say(l)
+                    root.after(0, lambda: messagebox.showinfo("Library Adder", f"{student_var.get()} was added to BARMAJA PyArduino."))
+                except Exception as exc:
+                    say(f"NOT INSTALLED: {exc}")
+            elif not ok:
+                say("Fix: untick the method named in the error (or rename it), then press Check again.")
+            say("Example program for students:\n" + (folder / "example.py").read_text(encoding="utf-8"))
+            root.after(0, lambda: busy(False))
+        threading.Thread(target=work, daemon=True).start()
+
+    def manage():
+        win = tk.Toplevel(root); win.title("Libraries added to BARMAJA"); win.geometry("640x320")
+        lb = tk.Listbox(win); lb.pack(fill="both", expand=True, padx=8, pady=8)
+        items = installed_packs()
+        for p in items:
+            lb.insert("end", f"{p['class']}  -  {p['title']}")
+        def do_remove():
+            sel = lb.curselection()
+            if not sel:
+                return
+            name = items[sel[0]]["class"]
+            if messagebox.askyesno("Remove", f"Remove {name}? (moved to the backups folder, not deleted)"):
+                for l in remove(name):
+                    say(l)
+                win.destroy()
+        ttk.Button(win, text="Remove selected", command=do_remove).pack(pady=(0, 8))
+
+    check_btn = ttk.Button(btns, text="4. Check (convert + compile test)", command=lambda: run_check(False)); check_btn.pack(side="left")
+    add_btn = ttk.Button(btns, text="5. Add to BARMAJA", command=lambda: run_check(True)); add_btn.pack(side="left", padx=8)
+    def library_only():
+        lib = state["lib"]
+        if not lib:
+            messagebox.showinfo("Library Adder", "Choose a library first."); return
+        try:
+            for l in install_library_only(lib):
+                say(l)
+        except Exception as exc:
+            say(f"NOT INSTALLED: {exc}")
+    ttk.Button(btns, text="Add library files only", command=library_only).pack(side="left")
+    ttk.Button(btns, text="Added libraries / Remove...", command=manage).pack(side="left", padx=8)
+    ttk.Label(btns, text="upload() only • offline • old files kept in backups", foreground="#666").pack(side="right")
+    if initial:
+        root.after(100, lambda: load(initial))
+    root.mainloop()
+    return 0