bdalabb 0.1.0__py3-none-any.whl

bdalabb-0.1.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: bdalabb
+Version: 0.1.0
+Summary: QuickPad-style hotkey overlay for Hadoop lab programs
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# BDA Lab
+
+A Windows desktop overlay for keeping Hadoop lab programs together. Hold the
+dedicated Numpad Minus key to show the window until you release it. A quick
+second press also shows it only while that second press is held. Tap the key
+three times quickly to pin or unpin the window. The top-row hyphen key is not
+used. Press **Ctrl+Shift+Q** to exit the background app.
+
+Each browser-style program tab contains inner tabs for its source code,
+execution commands, and input files. You can preview files, download the
+selected file, or download the complete program as a ZIP.
+
+## Install and run
+
+Use Windows with Python 3.10 or newer and **Tcl/Tk** included:
+
+```
+pip install bdalabb
+bdalabb
+```
+
+The app starts in the background and waits for the Numpad Minus key.
+
+## Program 1
+
+The package includes **Implementing Matrix Multiplication Using One MapReduce
+Step** with `MatrixMulti.java`, `RUN_COMMANDS.txt`, `input1.txt`, and
+`input2.txt`.
+
+## Add more programs
+
+Pin the window with three quick taps, then choose **Add program folder** to keep
+a complete lab program together. It is copied into the app's per-user data
+folder. The app picks a `.java` file as the main preview when available. You can
+also add individual files; each becomes its own program tab.
+
+To ship fixed files inside a later package build, add a folder under
+`src/labprograms/programs/` with a `program.json` file containing `title` and
+`primary_file` fields. No cloud account or network connection is required.

bdalabb-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+labprograms/__init__.py,sha256=9dKswjjlp1qEYEEGVwBkTAOjaX3dSD_HVCvntmfw9eg,66
+labprograms/__main__.py,sha256=gSsgGE9s4B5-SzM92_WkltpSoCCaJSE8nERjbUdGY8I,80
+labprograms/app.py,sha256=s-u3RZ4y80Nyxae2s1vV9fMOUmNiErgWAQEiV1ga_rA,18791
+labprograms/catalog.py,sha256=V01wWWIp7ffZLxlPGxHekpKCppR9gYFFRqMruY-1ZSM,11161
+labprograms/hotkeys.py,sha256=rmuNYYEI1TDlRZ-rgXniMUSvUa8o5AP_DgCJyAbpyG4,4092
+labprograms/preview.py,sha256=nnQQMPtsdXrBaMYyWgma0m8G3M8Y7kjbQw6rhcRw1qY,1092
+labprograms/programs/program1-matrix-multiplication/MatrixMulti.java,sha256=Mu4YZv67Li79twatvXZug_YVONi89yCy8QQtP4eEvnM,3179
+labprograms/programs/program1-matrix-multiplication/RUN_COMMANDS.txt,sha256=7M3zS2I2FXyXvJZeh5WTVoewFKUw0zcHZmqrK0i8mF0,367
+labprograms/programs/program1-matrix-multiplication/input1.txt,sha256=QgBfa-McHw442ExLHXh6_8nLJ2MvzhaY3V20tEWCKAQ,40
+labprograms/programs/program1-matrix-multiplication/input2.txt,sha256=CvrnFWrSRhL3l0AvsYOsbd5dv5Y44Zrv2-2qZyXf_WA,40
+labprograms/programs/program1-matrix-multiplication/program.json,sha256=rNHttTT2-5X03L54OPZZBFV92zZcT5P1re0nsF5jzBs,115
+bdalabb-0.1.0.dist-info/METADATA,sha256=ByVsYBxx5M-KM8bxYtcGFYJIGhxG-Ng3eDHHGPyxDFs,1671
+bdalabb-0.1.0.dist-info/WHEEL,sha256=PovZm1ExVWmrRefZoXCfejlbKLnQI5SVIf1SWRV4QQI,97
+bdalabb-0.1.0.dist-info/entry_points.txt,sha256=9Y7tcGHb_OrvS0FXXYnP7DHa66NnJBLGRLaiP5OnERw,45
+bdalabb-0.1.0.dist-info/top_level.txt,sha256=Jj_ZtEv3BN_J23iaP3Se6v7Iewy0yW4PuPJbIg5NaYw,12
+bdalabb-0.1.0.dist-info/RECORD,,

bdalabb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0.post0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bdalabb-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[gui_scripts]
+bdalabb = labprograms.app:main

bdalabb-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+labprograms

labprograms/__init__.py

@@ -0,0 +1,3 @@
+"""Lab Program Library desktop package."""
+
+__version__ = "0.1.0"

labprograms/__main__.py

@@ -0,0 +1,5 @@
+from .app import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

labprograms/app.py

@@ -0,0 +1,517 @@
+"""Tk desktop interface for the Lab Program Library."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import tkinter as tk
+import time
+from pathlib import Path
+from tkinter import filedialog, messagebox, ttk
+
+from .catalog import ProgramFile, ProgramLibrary, create_program_archive
+from .hotkeys import ActivationStateMachine, WindowsKeyPoller
+from .preview import read_preview
+
+
+INK = "#17263d"
+MUTED = "#607086"
+ACCENT = "#167c72"
+PANEL = "#f4f7fa"
+PREVIEW_BG = "#101d2d"
+PREVIEW_FG = "#d7e4ee"
+
+
+def _format_size(size: int) -> str:
+    if size < 1024:
+        return f"{size} B"
+    if size < 1024 * 1024:
+        return f"{size / 1024:.1f} KB"
+    return f"{size / (1024 * 1024):.1f} MB"
+
+
+class LabProgramApp:
+    def __init__(self, library: ProgramLibrary | None = None) -> None:
+        self.library = library or ProgramLibrary()
+        self.programs: list[ProgramFile] = []
+        self.file_notebooks: list[ttk.Notebook] = []
+        self.activation = ActivationStateMachine()
+        self.root = tk.Tk()
+        self.root.title("BDA Lab — Hadoop Program Library")
+        self.root.geometry("1100x740")
+        self.root.minsize(780, 520)
+        self.root.configure(bg=PANEL)
+        self._configure_styles()
+        self._build_ui()
+        self.key_poller = WindowsKeyPoller(
+            on_minus_down=lambda: self._dispatch_hotkey(self._handle_minus_down),
+            on_minus_up=lambda: self._dispatch_hotkey(self._handle_minus_up),
+            on_quit=lambda: self._dispatch_hotkey(self._quit),
+            on_error=lambda error: self._dispatch_hotkey(
+                lambda: self._handle_hotkey_error(error)
+            ),
+        )
+        self.refresh()
+
+    def _configure_styles(self) -> None:
+        style = ttk.Style(self.root)
+        preferred_theme = "vista" if sys.platform == "win32" else "clam"
+        if preferred_theme in style.theme_names():
+            style.theme_use(preferred_theme)
+        style.configure("TFrame", background=PANEL)
+        style.configure("TLabel", background=PANEL, foreground=INK)
+        style.configure("Muted.TLabel", foreground=MUTED)
+        style.configure("TNotebook", background=PANEL, borderwidth=0)
+        style.configure(
+            "TNotebook.Tab",
+            padding=(18, 10),
+            background="#e6edf2",
+            foreground=INK,
+        )
+        style.map(
+            "TNotebook.Tab",
+            background=[("selected", "#ffffff")],
+            foreground=[("selected", ACCENT)],
+        )
+        style.configure("Accent.TButton", padding=(14, 9))
+        style.map(
+            "Accent.TButton",
+            foreground=[("!disabled", "#ffffff")],
+            background=[("!disabled", ACCENT), ("active", "#0f635b")],
+        )
+
+    def _build_ui(self) -> None:
+        shell = ttk.Frame(self.root, padding=(26, 22))
+        shell.pack(fill="both", expand=True)
+        shell.columnconfigure(0, weight=1)
+        shell.rowconfigure(2, weight=1)
+
+        header = tk.Frame(shell, bg=INK, padx=22, pady=18)
+        header.grid(row=0, column=0, sticky="ew")
+        header.columnconfigure(0, weight=1)
+        tk.Label(
+            header,
+            text="BDA LAB",
+            bg=INK,
+            fg="#ffffff",
+            font=("Segoe UI", 16, "bold"),
+        ).grid(row=0, column=0, sticky="w")
+        tk.Label(
+            header,
+            text="Keep each lab program and its related files together.",
+            bg=INK,
+            fg="#c8d5e2",
+            font=("Segoe UI", 10),
+        ).grid(row=1, column=0, sticky="w", pady=(5, 0))
+
+        toolbar = ttk.Frame(shell, padding=(0, 16, 0, 12))
+        toolbar.grid(row=1, column=0, sticky="ew")
+        toolbar.columnconfigure(4, weight=1)
+        ttk.Button(
+            toolbar,
+            text="Add program files",
+            style="Accent.TButton",
+            command=self.add_programs,
+        ).grid(row=0, column=0, sticky="w")
+        ttk.Button(
+            toolbar,
+            text="Add program folder",
+            command=self.add_program_folder,
+        ).grid(row=0, column=1, padx=(9, 0), sticky="w")
+        self.download_button = ttk.Button(
+            toolbar,
+            text="Download selected file",
+            command=self.download_active,
+            state="disabled",
+        )
+        self.download_button.grid(row=0, column=2, padx=(9, 0), sticky="w")
+        ttk.Button(
+            toolbar,
+            text="Download program bundle (.zip)",
+            command=self.download_program_bundle,
+        ).grid(row=0, column=3, padx=(9, 0), sticky="w")
+        self.count_label = ttk.Label(toolbar, text="0 programs", style="Muted.TLabel")
+        self.count_label.grid(row=0, column=5, sticky="e")
+
+        body = ttk.Frame(shell)
+        body.grid(row=2, column=0, sticky="nsew")
+        body.columnconfigure(0, weight=1)
+        body.rowconfigure(0, weight=1)
+
+        self.notebook = ttk.Notebook(body)
+        self.empty_state = ttk.Frame(body, padding=34)
+        self._build_empty_state()
+
+        footer = ttk.Frame(shell, padding=(0, 12, 0, 0))
+        footer.grid(row=3, column=0, sticky="ew")
+        footer.columnconfigure(0, weight=1)
+        self.status_label = ttk.Label(
+            footer,
+            text=(
+                "Hold Numpad Minus to peek · tap it 3 times to pin · "
+                "Ctrl+Shift+Q to exit"
+            ),
+            style="Muted.TLabel",
+        )
+        self.status_label.grid(row=0, column=0, sticky="w")
+
+        self.root.bind("<Control-o>", lambda _event: self.add_programs())
+        self.root.bind("<Control-Tab>", self._next_tab)
+        self.root.bind("<Control-Shift-Tab>", self._previous_tab)
+        self.notebook.bind("<<NotebookTabChanged>>", self._update_download_button)
+        self.root.protocol(
+            "WM_DELETE_WINDOW",
+            self._dismiss_overlay if sys.platform == "win32" else self._quit,
+        )
+
+    def _build_empty_state(self) -> None:
+        self.empty_state.columnconfigure(0, weight=1)
+        tk.Label(
+            self.empty_state,
+            text="Your lab programs will appear here",
+            bg=PANEL,
+            fg=INK,
+            font=("Segoe UI", 19, "bold"),
+        ).grid(row=0, column=0, pady=(70, 8))
+        tk.Label(
+            self.empty_state,
+            text="Each program tab can contain its source, commands, and input files.",
+            bg=PANEL,
+            fg=MUTED,
+            font=("Segoe UI", 11),
+        ).grid(row=1, column=0, pady=(0, 20))
+        ttk.Button(
+            self.empty_state,
+            text="Choose lab files",
+            style="Accent.TButton",
+            command=self.add_programs,
+        ).grid(row=2, column=0)
+
+    def refresh(self, select_paths: set[Path] | None = None) -> None:
+        self.programs = self.library.list_programs()
+        self.file_notebooks = []
+        for tab_id in self.notebook.tabs():
+            self.notebook.forget(tab_id)
+
+        if self.programs:
+            if self.empty_state.winfo_manager() == "grid":
+                self.empty_state.grid_remove()
+            self.notebook.grid(row=0, column=0, sticky="nsew")
+            for index, program in enumerate(self.programs, start=1):
+                page, file_notebook = self._create_program_page(index, program)
+                self.notebook.add(page, text=f"Program {index}")
+                self.file_notebooks.append(file_notebook)
+            self.count_label.configure(
+                text=f"{len(self.programs)} program"
+                f"{'' if len(self.programs) == 1 else 's'}"
+            )
+            if select_paths:
+                for index, program in enumerate(self.programs):
+                    if program.path.resolve() in select_paths:
+                        self.notebook.select(index)
+                        break
+        else:
+            if self.notebook.winfo_manager() == "grid":
+                self.notebook.grid_remove()
+            self.empty_state.grid(row=0, column=0, sticky="nsew")
+            self.count_label.configure(text="0 programs")
+            self.status_label.configure(
+                text="Add a program folder or choose individual program files."
+            )
+
+        self._update_download_button()
+
+    def _create_program_page(
+        self, index: int, program: ProgramFile
+    ) -> tuple[ttk.Frame, ttk.Notebook]:
+        page = ttk.Frame(self.notebook, padding=(22, 18))
+        page.columnconfigure(0, weight=1)
+        page.rowconfigure(2, weight=1)
+
+        ttk.Label(
+            page,
+            text=f"Program {index}",
+            font=("Segoe UI", 17, "bold"),
+        ).grid(row=0, column=0, sticky="w")
+        ttk.Label(
+            page,
+            text=(
+                f"{program.display_name}  ·  {len(program.files)} files  ·  "
+                f"{_format_size(program.size)}  ·  {program.source}"
+            ),
+            style="Muted.TLabel",
+        ).grid(row=1, column=0, sticky="w", pady=(5, 14))
+
+        file_notebook = ttk.Notebook(page)
+        file_notebook.grid(row=2, column=0, sticky="nsew")
+        root = program.folder or program.path.parent
+        for file_path in program.files:
+            try:
+                tab_label = file_path.relative_to(root).as_posix()
+            except ValueError:
+                tab_label = file_path.name
+            file_notebook.add(
+                self._create_file_page(file_notebook, file_path),
+                text=tab_label,
+            )
+        file_notebook.bind(
+            "<<NotebookTabChanged>>", self._update_download_button
+        )
+        return page, file_notebook
+
+    def _create_file_page(
+        self, parent: ttk.Notebook, file_path: Path
+    ) -> ttk.Frame:
+        page = ttk.Frame(parent, padding=(8, 8))
+        page.columnconfigure(0, weight=1)
+        page.rowconfigure(0, weight=1)
+        try:
+            preview = read_preview(file_path)
+        except OSError as exc:
+            ttk.Label(
+                page,
+                text=f"This file could not be opened for preview: {exc}",
+                wraplength=700,
+            ).grid(row=0, column=0, sticky="nw", padx=16, pady=16)
+            return page
+
+        if not preview.is_text:
+            ttk.Label(
+                page,
+                text="Preview isn’t available for this file type.\n"
+                "Use the download button to save the original file.",
+                justify="center",
+                style="Muted.TLabel",
+            ).grid(row=0, column=0, sticky="nsew", padx=24, pady=24)
+            return page
+
+        text_frame = tk.Frame(page, bg=PREVIEW_BG)
+        text_frame.grid(row=0, column=0, sticky="nsew")
+        text_frame.rowconfigure(0, weight=1)
+        text_frame.columnconfigure(0, weight=1)
+        code = tk.Text(
+            text_frame,
+            wrap="none",
+            padx=18,
+            pady=16,
+            bg=PREVIEW_BG,
+            fg=PREVIEW_FG,
+            insertbackground="#ffffff",
+            selectbackground="#2b5367",
+            font=("Consolas", 10),
+            relief="flat",
+            borderwidth=0,
+            state="normal",
+        )
+        code.grid(row=0, column=0, sticky="nsew")
+        y_scroll = ttk.Scrollbar(text_frame, orient="vertical", command=code.yview)
+        y_scroll.grid(row=0, column=1, sticky="ns")
+        x_scroll = ttk.Scrollbar(text_frame, orient="horizontal", command=code.xview)
+        x_scroll.grid(row=1, column=0, sticky="ew")
+        code.configure(yscrollcommand=y_scroll.set, xscrollcommand=x_scroll.set)
+        code.insert("1.0", preview.text)
+        if preview.truncated:
+            code.insert(
+                "end",
+                "\n\n[Preview shortened. Download the file to see the full contents.]",
+            )
+        code.configure(state="disabled")
+        return page
+
+    def add_programs(self) -> None:
+        selected = filedialog.askopenfilenames(
+            parent=self.root,
+            title="Choose lab program files",
+            filetypes=[("All files", "*.*")],
+        )
+        if not selected:
+            return
+        try:
+            imported = self.library.import_files(selected)
+        except (OSError, ValueError) as exc:
+            messagebox.showerror("Could not add files", str(exc), parent=self.root)
+            return
+        self.refresh(select_paths={program.path.resolve() for program in imported})
+        self.status_label.configure(
+            text=f"Added {len(imported)} file"
+            f"{'' if len(imported) == 1 else 's'}. Originals were not changed."
+        )
+
+    def add_program_folder(self) -> None:
+        selected = filedialog.askdirectory(
+            parent=self.root,
+            title="Choose a folder containing one complete lab program",
+            mustexist=True,
+        )
+        if not selected:
+            return
+        try:
+            program = self.library.import_directory(selected)
+        except (OSError, ValueError) as exc:
+            messagebox.showerror("Could not add program folder", str(exc), parent=self.root)
+            return
+        self.refresh(select_paths={program.path.resolve()})
+        self.status_label.configure(
+            text=(
+                f"Added {program.display_name} with {len(program.files)} files. "
+                "Original files were not changed."
+            )
+        )
+
+    def _selected_file(self) -> Path | None:
+        if not self.programs or not self.notebook.tabs():
+            return None
+        program_index = self.notebook.index(self.notebook.select())
+        if program_index >= len(self.programs):
+            return None
+        file_notebook = self.file_notebooks[program_index]
+        if not file_notebook.tabs():
+            return None
+        file_index = file_notebook.index(file_notebook.select())
+        program = self.programs[program_index]
+        return program.files[file_index] if file_index < len(program.files) else None
+
+    def download_active(self) -> None:
+        selected_file = self._selected_file()
+        if selected_file is None:
+            return
+        downloads = Path.home() / "Downloads"
+        initial_dir = downloads if downloads.is_dir() else Path.home()
+        destination = filedialog.asksaveasfilename(
+            parent=self.root,
+            title="Download program file",
+            initialdir=initial_dir,
+            initialfile=selected_file.name,
+            filetypes=[("All files", "*.*")],
+        )
+        if not destination:
+            return
+        try:
+            shutil.copy2(selected_file, destination)
+        except (OSError, shutil.SameFileError) as exc:
+            messagebox.showerror("Download failed", str(exc), parent=self.root)
+            return
+        self.status_label.configure(
+            text=f"Saved a copy of {selected_file.name} to {destination}"
+        )
+
+    def download_program_bundle(self) -> None:
+        if not self.programs or not self.notebook.tabs():
+            return
+        program_index = self.notebook.index(self.notebook.select())
+        if program_index >= len(self.programs):
+            return
+        program = self.programs[program_index]
+        initial_name = (
+            f"{program.folder.name}.zip"
+            if program.folder
+            else f"{program.display_name}.zip"
+        )
+        downloads = Path.home() / "Downloads"
+        initial_dir = downloads if downloads.is_dir() else Path.home()
+        destination = filedialog.asksaveasfilename(
+            parent=self.root,
+            title="Download complete program",
+            initialdir=initial_dir,
+            initialfile=initial_name,
+            defaultextension=".zip",
+            filetypes=[("ZIP archive", "*.zip")],
+        )
+        if not destination:
+            return
+        try:
+            archive_path = create_program_archive(program, destination)
+        except (OSError, ValueError) as exc:
+            messagebox.showerror("Download failed", str(exc), parent=self.root)
+            return
+        self.status_label.configure(
+            text=f"Saved all {len(program.files)} files for {program.display_name} "
+            f"to {archive_path}"
+        )
+
+    def _update_download_button(self, _event: tk.Event | None = None) -> None:
+        selected_file = self._selected_file()
+        if selected_file is None:
+            self.download_button.configure(
+                text="Download selected file",
+                state="disabled",
+            )
+        else:
+            self.download_button.configure(
+                text=f"Download {selected_file.name}",
+                state="normal",
+            )
+
+    def _dispatch_hotkey(self, callback) -> None:
+        try:
+            self.root.after(0, callback)
+        except tk.TclError:
+            pass
+
+    def _handle_minus_down(self) -> None:
+        action = self.activation.press(time.monotonic())
+        if action == "show":
+            self._show_overlay()
+
+    def _handle_minus_up(self) -> None:
+        action = self.activation.release(time.monotonic())
+        if action == "hide":
+            self.root.withdraw()
+
+    def _show_overlay(self) -> None:
+        self.root.deiconify()
+        self.root.lift()
+        self.root.attributes("-topmost", True)
+        self.root.focus_force()
+
+    def _dismiss_overlay(self) -> None:
+        self.activation.dismiss()
+        self.root.withdraw()
+
+    def _handle_hotkey_error(self, error: Exception) -> None:
+        self.root.deiconify()
+        self.status_label.configure(
+            text=f"Numpad Minus activation could not start: {error}"
+        )
+        messagebox.showerror(
+            "Hotkey unavailable",
+            f"Could not start the Numpad Minus listener:\n{error}",
+            parent=self.root,
+        )
+
+    def _quit(self) -> None:
+        self.key_poller.stop()
+        self.root.destroy()
+
+    def _next_tab(self, _event: tk.Event) -> str:
+        tabs = self.notebook.tabs()
+        if tabs:
+            current = self.notebook.index(self.notebook.select())
+            self.notebook.select((current + 1) % len(tabs))
+        return "break"
+
+    def _previous_tab(self, _event: tk.Event) -> str:
+        tabs = self.notebook.tabs()
+        if tabs:
+            current = self.notebook.index(self.notebook.select())
+            self.notebook.select((current - 1) % len(tabs))
+        return "break"
+
+    def run(self) -> None:
+        if sys.platform == "win32":
+            self.root.withdraw()
+            self.root.after(0, self.key_poller.start)
+        else:
+            self.root.deiconify()
+            self.status_label.configure(
+                text="Global Numpad Minus activation is available on Windows."
+            )
+        try:
+            self.root.mainloop()
+        finally:
+            self.key_poller.stop()
+
+
+def main() -> int:
+    LabProgramApp().run()
+    return 0

labprograms/catalog.py

@@ -0,0 +1,295 @@
+"""Find, import, and safely store lab program files and file bundles."""
+
+from __future__ import annotations
+
+import filecmp
+import json
+import os
+import re
+import shutil
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Iterable
+
+
+MANIFEST_NAME = "program.json"
+IGNORED_DIRECTORY_NAMES = {".git", ".venv", "__pycache__"}
+
+
+@dataclass(frozen=True)
+class ProgramFile:
+    """One program, represented by a primary file and its associated assets."""
+
+    path: Path
+    source: str
+    title: str | None = None
+    associated_files: tuple[Path, ...] = ()
+    folder: Path | None = None
+
+    @property
+    def name(self) -> str:
+        return self.path.name
+
+    @property
+    def display_name(self) -> str:
+        return self.title or self.path.stem
+
+    @property
+    def files(self) -> tuple[Path, ...]:
+        return (self.path, *self.associated_files)
+
+    @property
+    def size(self) -> int:
+        try:
+            return sum(path.stat().st_size for path in self.files)
+        except OSError:
+            return 0
+
+
+def default_data_dir() -> Path:
+    """Return a per-user data directory without touching the package install."""
+    if os.name == "nt":
+        base = Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming")
+    else:
+        base = Path(
+            os.environ.get("XDG_DATA_HOME")
+            or Path.home() / ".local" / "share"
+        )
+    return base / "LabProgramLibrary"
+
+
+def _natural_key(value: str) -> tuple[tuple[int, int | str], ...]:
+    parts = re.split(r"(\d+)", value.casefold())
+    return tuple((0, int(part)) if part.isdigit() else (1, part) for part in parts)
+
+
+def create_program_archive(program: ProgramFile, destination: str | Path) -> Path:
+    """Write all files in a program to a ZIP with a single top-level folder."""
+    target = Path(destination)
+    resolved_target = target.resolve()
+    program_paths = {path.resolve() for path in program.files}
+    if resolved_target in program_paths or (
+        program.folder
+        and resolved_target.is_relative_to(program.folder.resolve())
+    ):
+        raise ValueError("Save the ZIP outside the program's source folder.")
+    root_name = program.folder.name if program.folder else "Program"
+    root_name = root_name.replace("/", "_").replace("\\", "_").strip()
+    if root_name in {"", ".", ".."}:
+        root_name = "Program"
+
+    with zipfile.ZipFile(target, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for file_path in program.files:
+            relative = (
+                file_path.relative_to(program.folder)
+                if program.folder
+                else Path(file_path.name)
+            )
+            if relative.is_absolute() or ".." in relative.parts:
+                raise ValueError(f"Unsafe path in program bundle: {relative}")
+            archive_path = PurePosixPath(root_name, *relative.parts).as_posix()
+            archive.write(file_path, archive_path)
+    return target
+
+
+def _read_program_directory(directory: Path, source: str) -> ProgramFile | None:
+    """Read a bundle folder, using its manifest when one is present."""
+    manifest_path = directory / MANIFEST_NAME
+    manifest: dict[str, object] = {}
+    if manifest_path.is_file():
+        try:
+            content = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ValueError(f"Could not read {manifest_path}: {exc}") from exc
+        if not isinstance(content, dict):
+            raise ValueError(f"{manifest_path} must contain a JSON object.")
+        manifest = content
+
+    files = sorted(
+        (
+            path
+            for path in directory.rglob("*")
+            if path.is_file()
+            and not path.is_symlink()
+            and not any(part.startswith(".") for part in path.relative_to(directory).parts)
+            and path.name != MANIFEST_NAME
+        ),
+        key=lambda path: _natural_key(path.relative_to(directory).as_posix()),
+    )
+    if not files:
+        return None
+
+    requested_primary = manifest.get("primary_file")
+    if requested_primary is not None:
+        if not isinstance(requested_primary, str):
+            raise ValueError(f"{manifest_path} has an invalid primary_file value.")
+        primary = (directory / requested_primary).resolve()
+        if (
+            not primary.is_relative_to(directory.resolve())
+            or not primary.is_file()
+            or primary not in [path.resolve() for path in files]
+        ):
+            raise ValueError(
+                f"{manifest_path} points to a missing or unsafe primary file."
+            )
+        primary = next(path for path in files if path.resolve() == primary)
+    else:
+        primary = next(
+            (path for path in files if path.suffix.casefold() == ".java"),
+            files[0],
+        )
+
+    title = manifest.get("title", directory.name)
+    if not isinstance(title, str) or not title.strip():
+        raise ValueError(f"{manifest_path} must have a non-empty title.")
+    associated = tuple(path for path in files if path != primary)
+    return ProgramFile(
+        path=primary,
+        source=source,
+        title=title.strip(),
+        associated_files=associated,
+        folder=directory,
+    )
+
+
+class ProgramLibrary:
+    """Combines bundled programs with files and folders imported by the user."""
+
+    def __init__(
+        self,
+        data_dir: Path | None = None,
+        bundled_dir: Path | None = None,
+    ) -> None:
+        package_dir = Path(__file__).resolve().parent
+        self.data_dir = Path(data_dir) if data_dir else default_data_dir()
+        self.user_program_dir = self.data_dir / "programs"
+        self.bundled_dir = (
+            Path(bundled_dir) if bundled_dir else package_dir / "programs"
+        )
+
+    def list_programs(self) -> list[ProgramFile]:
+        programs: list[ProgramFile] = []
+        for directory, source in (
+            (self.bundled_dir, "Included"),
+            (self.user_program_dir, "Added"),
+        ):
+            if not directory.is_dir():
+                continue
+            for path in directory.iterdir():
+                if path.is_dir() and not path.name.startswith("."):
+                    program = _read_program_directory(path, source)
+                    if program:
+                        programs.append(program)
+                elif path.is_file() and not path.name.startswith("."):
+                    programs.append(ProgramFile(path=path, source=source))
+        return sorted(
+            programs,
+            key=lambda item: (
+                _natural_key(item.folder.name if item.folder else item.name),
+                item.source,
+            ),
+        )
+
+    def import_files(self, paths: Iterable[str | Path]) -> list[ProgramFile]:
+        """Copy selected files into app storage; never overwrite an existing file."""
+        self.user_program_dir.mkdir(parents=True, exist_ok=True)
+        imported: list[ProgramFile] = []
+
+        for selected in paths:
+            source_path = Path(selected).expanduser()
+            if not source_path.is_file():
+                raise FileNotFoundError(f"Program file not found: {source_path}")
+
+            destination = self._destination_for(source_path)
+            if source_path.resolve() != destination.resolve():
+                if not destination.exists():
+                    shutil.copy2(source_path, destination)
+            imported.append(ProgramFile(path=destination, source="Added"))
+
+        return imported
+
+    def import_directory(self, selected: str | Path) -> ProgramFile:
+        """Import a directory as one program bundle, preserving its relative paths."""
+        source = Path(selected).expanduser().resolve()
+        if not source.is_dir():
+            raise NotADirectoryError(f"Program folder not found: {source}")
+        library_dir = self.user_program_dir.resolve()
+        if source.is_relative_to(library_dir) or library_dir.is_relative_to(source):
+            raise ValueError(
+                "Choose a program folder outside the app's own library folder."
+            )
+
+        self.user_program_dir.mkdir(parents=True, exist_ok=True)
+        destination = self._directory_destination(source.name)
+        destination.mkdir(parents=True)
+
+        try:
+            self._copy_program_tree(source, destination)
+            program = _read_program_directory(destination, "Added")
+            if program is None:
+                raise ValueError("The selected folder does not contain any files.")
+            manifest_path = destination / MANIFEST_NAME
+            if not manifest_path.exists():
+                manifest_path.write_text(
+                    json.dumps(
+                        {
+                            "title": source.name,
+                            "primary_file": program.path.relative_to(destination).as_posix(),
+                        },
+                        indent=2,
+                    )
+                    + "\n",
+                    encoding="utf-8",
+                )
+                program = _read_program_directory(destination, "Added")
+                assert program is not None
+            return program
+        except Exception:
+            shutil.rmtree(destination, ignore_errors=True)
+            raise
+
+    def _copy_program_tree(self, source: Path, destination: Path) -> None:
+        for current, directories, filenames in os.walk(source, followlinks=False):
+            current_path = Path(current)
+            directories[:] = [
+                name
+                for name in directories
+                if name not in IGNORED_DIRECTORY_NAMES
+                and not (current_path / name).is_symlink()
+            ]
+            relative = current_path.relative_to(source)
+            target_dir = destination / relative
+            target_dir.mkdir(parents=True, exist_ok=True)
+            for filename in filenames:
+                source_file = current_path / filename
+                if source_file.is_symlink() or not source_file.is_file():
+                    continue
+                shutil.copy2(source_file, target_dir / filename)
+
+    def _directory_destination(self, name: str) -> Path:
+        candidate = self.user_program_dir / name
+        number = 2
+        while candidate.exists():
+            candidate = self.user_program_dir / f"{name} ({number})"
+            number += 1
+        return candidate
+
+    def _destination_for(self, source_path: Path) -> Path:
+        candidate = self.user_program_dir / source_path.name
+        if not candidate.exists():
+            return candidate
+        if source_path.resolve() == candidate.resolve():
+            return candidate
+        if filecmp.cmp(source_path, candidate, shallow=False):
+            return candidate
+
+        stem, suffix = source_path.stem, source_path.suffix
+        number = 2
+        while True:
+            candidate = self.user_program_dir / f"{stem} ({number}){suffix}"
+            if not candidate.exists():
+                return candidate
+            if filecmp.cmp(source_path, candidate, shallow=False):
+                return candidate
+            number += 1

labprograms/hotkeys.py

@@ -0,0 +1,126 @@
+"""Windows Numpad Minus activation logic for the desktop overlay."""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+import threading
+import time
+from collections.abc import Callable
+
+
+VK_SUBTRACT = 0x6D
+VK_CONTROL = 0x11
+VK_SHIFT = 0x10
+VK_Q = 0x51
+DEFAULT_TAP_WINDOW = 0.45
+POLL_INTERVAL = 0.01
+
+
+class ActivationStateMachine:
+    """Single hold peeks, while a triple tap toggles the pinned state."""
+
+    def __init__(self, tap_window: float = DEFAULT_TAP_WINDOW) -> None:
+        self.tap_window = tap_window
+        self.key_is_down = False
+        self.last_release_time: float | None = None
+        self.press_count = 0
+        self.pinned = False
+
+    def press(self, now: float) -> str | None:
+        """Handle a fresh key-down edge and return the requested window action."""
+        if self.key_is_down:
+            return None
+        self.key_is_down = True
+
+        if (
+            self.last_release_time is not None
+            and 0 <= now - self.last_release_time <= self.tap_window
+        ):
+            self.press_count += 1
+        else:
+            self.press_count = 1
+
+        if self.press_count >= 3:
+            self.pinned = not self.pinned
+            self.press_count = 0
+        return "show"
+
+    def release(self, now: float) -> str | None:
+        """Hide after a peek release, but leave a pinned window visible."""
+        if not self.key_is_down:
+            return None
+        self.key_is_down = False
+        self.last_release_time = now
+        return "show" if self.pinned else "hide"
+
+    def dismiss(self) -> None:
+        """Clear the pinned state when the window is explicitly dismissed."""
+        self.pinned = False
+        self.press_count = 0
+        self.last_release_time = None
+
+
+class WindowsKeyPoller:
+    """Poll the dedicated Windows Numpad Minus key without extra dependencies."""
+
+    def __init__(
+        self,
+        on_minus_down: Callable[[], None],
+        on_minus_up: Callable[[], None],
+        on_quit: Callable[[], None],
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> None:
+        self.on_minus_down = on_minus_down
+        self.on_minus_up = on_minus_up
+        self.on_quit = on_quit
+        self.on_error = on_error or (lambda _error: None)
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        if sys.platform != "win32":
+            raise OSError("Global Numpad Minus activation is available on Windows.")
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._poll,
+            name="bdalabb-numpad-minus",
+            daemon=True,
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=1)
+        self._thread = None
+
+    def _poll(self) -> None:
+        try:
+            user32 = ctypes.WinDLL("user32", use_last_error=True)
+            get_async_key_state = user32.GetAsyncKeyState
+            get_async_key_state.argtypes = (ctypes.c_int,)
+            get_async_key_state.restype = ctypes.c_short
+
+            minus_down = False
+            quit_chord_down = False
+            while not self._stop.is_set():
+                current_minus = bool(get_async_key_state(VK_SUBTRACT) & 0x8000)
+                if current_minus and not minus_down:
+                    self.on_minus_down()
+                elif minus_down and not current_minus:
+                    self.on_minus_up()
+                minus_down = current_minus
+
+                current_quit_chord = all(
+                    get_async_key_state(key) & 0x8000
+                    for key in (VK_CONTROL, VK_SHIFT, VK_Q)
+                )
+                if current_quit_chord and not quit_chord_down:
+                    self.on_quit()
+                quit_chord_down = current_quit_chord
+                self._stop.wait(POLL_INTERVAL)
+        except Exception as exc:
+            self.on_error(exc)

labprograms/preview.py

@@ -0,0 +1,40 @@
+"""Bounded, read-only previews for common text-based program files."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+MAX_PREVIEW_BYTES = 512 * 1024
+
+
+@dataclass(frozen=True)
+class FilePreview:
+    text: str
+    is_text: bool
+    truncated: bool = False
+
+
+def read_preview(path: Path, max_bytes: int = MAX_PREVIEW_BYTES) -> FilePreview:
+    with Path(path).open("rb") as file:
+        data = file.read(max_bytes + 1)
+
+    truncated = len(data) > max_bytes
+    data = data[:max_bytes]
+    if b"\x00" in data[:4096]:
+        return FilePreview("", is_text=False, truncated=truncated)
+
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        return FilePreview("", is_text=False, truncated=truncated)
+
+    if text:
+        printable = sum(
+            character.isprintable() or character in "\t\r\n\f" for character in text
+        )
+        if printable / len(text) < 0.88:
+            return FilePreview("", is_text=False, truncated=truncated)
+
+    return FilePreview(text, is_text=True, truncated=truncated)

labprograms/programs/program1-matrix-multiplication/MatrixMulti.java

@@ -0,0 +1,113 @@
+import java.io.IOException;
+import java.util.*;
+
+import org.apache.hadoop.fs.Path;
+import org.apache.hadoop.conf.*;
+import org.apache.hadoop.io.*;
+import org.apache.hadoop.mapreduce.*;
+import org.apache.hadoop.mapreduce.lib.input.FileInputFormat;
+import org.apache.hadoop.mapreduce.lib.input.TextInputFormat;
+import org.apache.hadoop.mapreduce.lib.output.FileOutputFormat;
+import org.apache.hadoop.mapreduce.lib.output.TextOutputFormat;
+
+public class MatrixMulti {
+
+public static class Map extends Mapper<LongWritable, Text, Text, Text> {
+public void map(LongWritable key, Text value, Context context)
+throws IOException, InterruptedException {
+Configuration conf = context.getConfiguration();
+int m = Integer.parseInt(conf.get("m"));
+int p = Integer.parseInt(conf.get("p"));
+String line = value.toString();
+String[] indicesAndValue = line.split(",");
+Text outputKey = new Text();
+Text outputValue = new Text();
+
+// implementation
+
+if (indicesAndValue[0].equals("A")) {
+for (int k = 0; k < p; k++) {
+outputKey.set(indicesAndValue[1] + "," + k);
+outputValue.set("A," + indicesAndValue[2] + ","
++ indicesAndValue[3]);
+context.write(outputKey, outputValue);
+}
+} else {
+for (int i = 0; i < m; i++) {
+outputKey.set(i + "," + indicesAndValue[2]);
+outputValue.set("B," + indicesAndValue[1] + ","
++ indicesAndValue[3]);
+context.write(outputKey, outputValue);
+}
+}
+}
+}
+
+public static class Reduce extends Reducer<Text, Text, Text, Text> {
+public void reduce(Text key, Iterable<Text> values, Context context)
+throws IOException, InterruptedException {
+String[] value;
+HashMap<Integer, Float> hashA = new HashMap<Integer, Float>();
+HashMap<Integer, Float> hashB = new HashMap<Integer, Float>();
+int n = Integer.parseInt(context.getConfiguration().get("n"));
+float result = 0.0f;
+float a_ij;
+float b_jk;
+
+//implementation
+
+for (Text val : values) {
+value = val.toString().split(",");
+if (value[0].equals("A")) {
+hashA.put(Integer.parseInt(value[1]),
+Float.parseFloat(value[2]));
+} else {
+hashB.put(Integer.parseInt(value[1]),
+Float.parseFloat(value[2]));
+}
+}
+for (int j = 0; j < n; j++) {
+a_ij = hashA.containsKey(j) ? hashA.get(j) : 0.0f;
+b_jk = hashB.containsKey(j) ? hashB.get(j) : 0.0f;
+result += a_ij * b_jk;
+}
+
+if (result != 0.0f) {
+context.write(null,
+new Text(key.toString() + "," + Float.toString(result)));
+}
+}
+}
+
+public static void main(String[] args) throws Exception {
+if (args.length != 5) {
+System.err.println("Use: MatrixMulti <input> <output> <m> <n> <p>");
+System.exit(1);
+}
+Configuration conf = new Configuration();
+
+// A is an m-by-n matrix; B is an n-by-p matrix.
+conf.set("m", args[2]);
+conf.set("n", args[3]);
+conf.set("p", args[4]);
+
+Job job = Job.getInstance(conf);
+job.setJobName("MatrixMatrixMultiplicationOneStep");
+job.setJarByClass(MatrixMulti.class);
+job.setOutputKeyClass(Text.class);
+job.setOutputValueClass(Text.class);
+
+job.setMapperClass(Map.class);
+job.setReducerClass(Reduce.class);
+
+job.setInputFormatClass(TextInputFormat.class);
+job.setOutputFormatClass(TextOutputFormat.class);
+
+job.setNumReduceTasks(1);
+
+FileInputFormat.addInputPath(job, new Path(args[0]));
+FileOutputFormat.setOutputPath(job, new Path(args[1]));
+
+job.waitForCompletion(true);
+}
+}

labprograms/programs/program1-matrix-multiplication/RUN_COMMANDS.txt

@@ -0,0 +1,12 @@
+Run these commands from the folder containing this program's downloaded files:
+
+hadoop fs -mkdir /matrix
+hadoop fs -put input1.txt /matrix
+hadoop fs -put input2.txt /matrix
+
+hadoop com.sun.tools.javac.Main MatrixMulti.java
+jar -cf mm.jar MatrixMulti*.class
+hadoop jar mm.jar MatrixMulti /matrix /mmoutput 2 2 2
+
+hadoop fs -ls /mmoutput
+hadoop fs -cat /mmoutput/part*

labprograms/programs/program1-matrix-multiplication/input1.txt

@@ -0,0 +1,4 @@
+A,0,0,1.0
+A,0,1,2.0
+A,1,0,3.0
+A,1,1,4.0

labprograms/programs/program1-matrix-multiplication/input2.txt

@@ -0,0 +1,4 @@
+B,0,0,5.0
+B,0,1,6.0
+B,1,0,7.0
+B,1,1,8.0

labprograms/programs/program1-matrix-multiplication/program.json

@@ -0,0 +1,4 @@
+{
+  "title": "Implementing Matrix Multiplication Using One MapReduce Step",
+  "primary_file": "MatrixMulti.java"
+}