pyflashgui 0.1.0__py3-none-any.whl

pyflashgui/core/shortcut.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""A Start menu or applications menu entry for a source folder.
+
+The installer makes its own. A clone has only the launcher, and the entry made
+here points at that rather than at the Python in ``.venv``: the launcher is
+what notices a dependency added since the last pull, so starting from the menu
+picks up an update exactly as double-clicking the launcher does.
+
+Offered by the launcher at the end of its first-run setup, which runs
+``python -m pyflashgui.core.shortcut``, and at any time from Tools > Settings.
+Standard library only, since the launcher calls it before anything else of
+pyflashgui's has been started.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+#: Plain, since it starts whatever was last pulled. The installer's entries
+#: carry the version they install, which is how the two are told apart.
+NAME = "pyflashgui"
+#: What each system calls the menu, for the Tools entry and the messages.
+MENU = {"win32": "Start menu", "linux": "applications menu"}
+
+
+def root() -> Path:
+    """The folder the pyflashgui package sits in: the clone, for a source folder."""
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def launcher(platform: str | None = None) -> Path | None:
+    """The launcher to point the entry at, or None where there is no entry to make.
+
+    None for a frozen build, which the installer looks after, for a pip
+    installation, which has no launcher beside it, and on macOS, whose menu
+    is not made of files like these.
+    """
+    platform = sys.platform if platform is None else platform
+    if getattr(sys, "frozen", False) or platform not in MENU:
+        return None
+    script = root() / ("pyflashgui.cmd" if platform == "win32" else "pyflashgui.sh")
+    return script if script.is_file() else None
+
+
+def menu_name(platform: str | None = None) -> str:
+    return MENU.get(sys.platform if platform is None else platform, "menu")
+
+
+def entry_path(platform: str | None = None, environ=None) -> Path:
+    """Where the entry goes: the user's own menu, so no administrator is asked."""
+    platform = sys.platform if platform is None else platform
+    environ = os.environ if environ is None else environ
+    if platform == "win32":
+        programs = Path(environ["APPDATA"]) / "Microsoft" / "Windows" / "Start Menu" / "Programs"
+        return programs / f"{NAME}.lnk"
+    data = environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return Path(data) / "applications" / f"{NAME}.desktop"
+
+
+def _desktop_quoted(path: Path) -> str:
+    """A path as an Exec argument: quoted, with the characters the spec reserves escaped."""
+    text = str(path)
+    for reserved in ("\\", '"', "`", "$"):
+        text = text.replace(reserved, "\\" + reserved)
+    return f'"{text}"'
+
+
+def desktop_entry(script: Path) -> str:
+    """The .desktop file for a launcher.
+
+    Run in a terminal: the first start after a pull may install libraries, and
+    anything that goes wrong is said there, as it is when started by hand.
+    """
+    folder = script.parent
+    return (
+        "[Desktop Entry]\n"
+        "Type=Application\n"
+        f"Name={NAME}\n"
+        "Comment=Flash programming tool\n"
+        f"Exec={_desktop_quoted(script)}\n"
+        f"Path={folder}\n"
+        f"Icon={folder / 'pyflashgui' / 'resources' / 'pyflashgui.png'}\n"
+        "Terminal=true\n"
+        "Categories=Development;Electronics;\n"
+    )
+
+
+def _windows_link(link: Path, script: Path) -> None:
+    """Make the .lnk through the shell's own COM object, by way of PowerShell.
+
+    The paths go in the environment rather than the command line, so no
+    folder name can be mistaken for PowerShell syntax.
+    """
+    folder = script.parent
+    command = (
+        "$s = (New-Object -ComObject WScript.Shell).CreateShortcut($env:PYFLASHGUI_LINK);"
+        "$s.TargetPath = $env:PYFLASHGUI_TARGET;"
+        "$s.WorkingDirectory = $env:PYFLASHGUI_FOLDER;"
+        "$s.IconLocation = $env:PYFLASHGUI_ICON;"
+        "$s.Description = 'Flash programming tool, started from ' + $env:PYFLASHGUI_FOLDER;"
+        "$s.Save()"
+    )
+    environ = dict(
+        os.environ,
+        PYFLASHGUI_LINK=str(link),
+        PYFLASHGUI_TARGET=str(script),
+        PYFLASHGUI_FOLDER=str(folder),
+        PYFLASHGUI_ICON=str(folder / "pyflashgui" / "resources" / "pyflashgui.ico"),
+    )
+    done = subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", command],
+        env=environ,
+        capture_output=True,
+        text=True,
+        # pyflashgui runs under pythonw, and a console would flash up otherwise.
+        creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+    )
+    if done.returncode != 0 or not link.is_file():
+        raise OSError(done.stderr.strip() or "PowerShell could not make the shortcut.")
+
+
+def create(platform: str | None = None, environ=None) -> Path:
+    """Make or replace the entry, and say where it is. OSError if it cannot be."""
+    platform = sys.platform if platform is None else platform
+    script = launcher(platform)
+    if script is None:
+        raise OSError("Only a source folder with its launcher needs a menu entry made.")
+    path = entry_path(platform, environ)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if platform == "win32":
+        _windows_link(path, script)
+    else:
+        path.write_text(desktop_entry(script), encoding="utf-8")
+        # Some desktops start only an entry that is marked executable.
+        path.chmod(0o755)
+    return path
+
+
+def main() -> int:
+    try:
+        path = create()
+    except OSError as exc:
+        print(f" Could not add pyflashgui to the {menu_name()}: {exc}")
+        return 1
+    print(f" Added pyflashgui to the {menu_name()}: {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyflashgui/core/slow_start.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Two lines after starting, when there is something to say: what Python had to
+compile, and what made a slow start slow.
+
+**Compiling.** The first start after an update is much slower than the rest:
+every changed file is compiled to bytecode again. Thirteen seconds where two is
+normal, once, and then it cures itself -- but somebody watching a blank screen
+has no way of knowing that, and "it has got slow" is what sticks. This is not a
+guess about the clock: Python records where each module's compiled copy lives,
+so counting the ones written during this start says exactly what happened. It
+is said whenever any file was compiled, fast start or slow, as information.
+
+**Slow.** A start can be slow with nothing compiled, too -- the first after the
+computer started, with nothing in the disk cache, or with an antivirus checking
+every file. So past ``SLOW_S`` the clock is enough on its own: the start says
+how long it took and what took over a second -- the steps, and inside the one
+the libraries load in, the packages -- and points to *Help > Diagnostics* for
+the rest, rather than putting the whole report in the Event Log.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+#: A step or a package at least this long is named in the slow-start line.
+OVER_S = 1.0
+#: Seconds of work, the notice not counted, past which a start is worth
+#: explaining whatever the cause. A normal start is two or three.
+SLOW_S = 10.0
+
+
+def is_slow(took: float) -> bool:
+    return took >= SLOW_S
+
+
+def compiled_this_start(since: float, modules=None) -> int:
+    """How many imported modules were compiled during this start.
+
+    ``since`` is the wall clock as the process began. A ``.pyc`` written
+    after that is one this start had to make, whether because the source
+    changed, the file was new, or the cache had been cleared.
+    """
+    written = 0
+    for module in list((sys.modules if modules is None else modules).values()):
+        cached = getattr(module, "__cached__", None)
+        if not cached:
+            continue
+        try:
+            if Path(cached).stat().st_mtime >= since:
+                written += 1
+        except OSError:  # deleted since, or on a read-only installation
+            pass
+    return written
+
+
+def compiled_note(since: float, modules=None) -> str | None:
+    """The compiling line, or None when nothing was compiled."""
+    written = compiled_this_start(since, modules)
+    if not written:
+        return None
+    files = "file" if written == 1 else "files"
+    return f"Python compiled {written} changed {files}, which it only does after files change."
+
+
+def message(
+    took: float,
+    steps: list[tuple[str, float]] | None = None,
+    packages: dict[str, float] | None = None,
+) -> str | None:
+    """The slow-start line, or None when the start was not slow."""
+    if not is_slow(took):
+        return None
+    said = f"Starting took {took:.1f} s."
+    if slow := culprits(steps or [], packages or {}):
+        said += f" Over a second: {slow}."
+    return said + " Help > Diagnostics has the full breakdown."
+
+
+def culprits(steps: list[tuple[str, float]], packages: dict[str, float]) -> str:
+    """The steps over ``OVER_S``, longest first, with the slow packages beside
+    the libraries step -- "the libraries" on its own says nothing about which
+    one. Empty when no step was."""
+    from pyflashgui.core.timing import LIBRARIES_STEP
+
+    named = []
+    for label, seconds in sorted(steps, key=lambda step: step[1], reverse=True):
+        if seconds < OVER_S:
+            break
+        part = f"{label} {seconds:.1f} s"
+        if label == LIBRARIES_STEP:
+            slow = sorted(
+                ((name, s) for name, s in packages.items() if s >= OVER_S),
+                key=lambda package: package[1],
+                reverse=True,
+            )
+            if slow:
+                part += " (" + ", ".join(f"{name} {s:.1f} s" for name, s in slow) + ")"
+        named.append(part)
+    return ", ".join(named)

pyflashgui/core/timing.py

@@ -0,0 +1,312 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Where the seconds go while pyflashgui starts.
+
+Starting up is a chain of things that each look cheap: Qt, a workspace's
+settings, the flashing libraries, asking every probe driver what is plugged
+in. When it adds up to ten seconds, guessing which one is at fault costs more
+than measuring it, and the answer is different on every machine --
+a slow file system here, a driver that takes its time enumerating probes
+somewhere else.
+
+So everything is always measured: the marks between steps, and how long
+each package took to import. Neither costs anything that can be measured,
+and a start that turns out to have been slow cannot be measured after the
+fact. The report is always in *Help > About*'s diagnostics, and goes to the
+Event Log after a slow start; ``pyflashgui --timing``, which the launchers
+pass through, or ``PYFLASHGUI_TIMING=1`` shows it after every start.
+
+The report goes to the Event Log and to ``startup-timing.txt`` in pyflashgui's
+own folder, because the launcher starts pythonw and there is no console to
+print it to.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+
+FLAG = "--timing"
+ENV = "PYFLASHGUI_TIMING"
+#: Stamped by the launchers before they do anything, so the report can say
+#: what happened before Python: the dependency check, and the interpreter
+#: starting. A shell writes epoch seconds; cmd writes %TIME%, which is
+#: HH:MM:SS.ss in whatever the machine's separators are.
+LAUNCH_ENV = "PYFLASHGUI_LAUNCH_AT"
+#: Stamped again by the launchers immediately before they start Python, so
+#: that the script's own work and the interpreter starting are separate
+#: numbers: one is fixed by doing less in the script, the other is not.
+PYTHON_ENV = "PYFLASHGUI_PYTHON_AT"
+#: Longer than this and the stamp is from an earlier run left in the
+#: environment, not from the launch that is starting now.
+SANE_LAUNCH_S = 600.0
+REPORT_NAME = "startup-timing.txt"
+#: The one step that is not work: the libraries load behind the start-up
+#: notice and the window is built after it, so a person reading the notice
+#: sits between two marks. It is shown, because it is part of the wait, and
+#: left out of the total, because it is not something to make faster.
+NOTICE_STEP = "waiting for the notice to be answered"
+#: The step the libraries load in, which the package times break down.
+LIBRARIES_STEP = "libraries imported"
+
+#: The clock starts when this module is imported, which ``__main__`` does
+#: before anything heavy. Whatever ran before that -- the interpreter itself,
+#: and the launcher's dependency check -- is outside anything Python here can
+#: see, so the report says so rather than pretending to a total.
+_STARTED = time.perf_counter()
+#: The wall clock at the same moment, for comparing against the launchers'
+#: stamps. Taken here rather than when the report is written: the report
+#: comes seconds later, and measuring against it charged the launcher with
+#: everything that happened after it -- Qt, the libraries, the window, and
+#: however long somebody took to read the notice.
+_STARTED_WALL = time.time()
+
+_marks: list[tuple[str, float]] = []
+_on = FLAG in sys.argv or os.environ.get(ENV, "") not in ("", "0")
+
+
+#: Seconds spent executing each top-level package's modules. Exclusive of the
+#: imports a module does itself, so the totals add up rather than counting
+#: the same second under three names.
+_imports: dict[str, float] = {}
+#: The imports under way, one stack per thread: the libraries load on a
+#: thread of their own while the GUI thread may be importing too, and one
+#: shared stack would hand each thread's time to the other.
+_local = threading.local()
+
+
+#: What the standard library's modules are counted under. Together, because
+#: each one is small and "json" or "ctypes" on a line of its own reads as a
+#: package somebody installed; kept, because it is still time spent starting.
+STDLIB = "Python standard library"
+
+
+def _package(name: str) -> str:
+    """The line a module's time goes on: its top-level package, or STDLIB."""
+    top = name.split(".")[0]
+    return STDLIB if top in sys.stdlib_module_names else top
+
+
+def _depth() -> list[float]:
+    stack = getattr(_local, "stack", None)
+    if stack is None:
+        stack = _local.stack = []
+    return stack
+
+
+def enabled() -> bool:
+    return _on
+
+
+class _TimedImports:
+    """A finder that times what the real finders load.
+
+    Put in front of ``sys.meta_path``, it lets the normal machinery find a
+    module and then wraps the loader, so the cost lands under the package it
+    belongs to. Time spent importing something else is subtracted, so a
+    package is not blamed for the packages it imports.
+
+    Marked rather than recognised by its class: reloading this module makes a
+    new class, and a watcher that failed to recognise one from before would be
+    installed beside it, each asking the other for every module for ever.
+    """
+
+    watcher = True
+
+    def find_spec(self, name, path=None, target=None):
+        for finder in sys.meta_path:
+            if getattr(finder, "watcher", False) or not hasattr(finder, "find_spec"):
+                continue
+            spec = finder.find_spec(name, path, target)
+            if spec is None or spec.loader is None:
+                continue
+            spec.loader = _TimedLoader(spec.loader, _package(name))
+            return spec
+        return None
+
+
+class _TimedLoader:
+    def __init__(self, loader, package: str) -> None:
+        self._loader = loader
+        self._package = package
+
+    def __getattr__(self, attribute):  # create_module, is_package, get_data, ...
+        return getattr(self._loader, attribute)
+
+    def exec_module(self, module) -> None:
+        began = time.perf_counter()
+        stack = _depth()
+        stack.append(0.0)
+        try:
+            self._loader.exec_module(module)
+        finally:
+            spent_below = stack.pop()
+            mine = time.perf_counter() - began - spent_below
+            _imports[self._package] = _imports.get(self._package, 0.0) + mine
+            if stack:  # tell whoever imported us not to count our time twice
+                stack[-1] += mine + spent_below
+
+
+def watch_imports() -> None:
+    """Start timing imports: always, since it costs nothing measurable."""
+    if not any(getattr(finder, "watcher", False) for finder in sys.meta_path):
+        sys.meta_path.insert(0, _TimedImports())
+
+
+def import_lines(most: int = 8) -> list[str]:
+    """The packages that cost the most to import, largest first."""
+    if not _imports:
+        return []
+    worst = sorted(_imports.items(), key=lambda pair: pair[1], reverse=True)[:most]
+    lines = ["The packages that took longest to import:"]
+    lines += [f"  {took:6.3f}  {package}" for package, took in worst if took >= 0.001]
+    return lines
+
+
+def _until_import(stamp: str) -> float | None:
+    """Seconds from a launcher's stamp to this module being imported."""
+    try:
+        if ":" in stamp:  # cmd's %TIME%, which is a time of day
+            hours, minutes, seconds = stamp.split(":")
+            began = int(hours) * 3600 + int(minutes) * 60 + float(seconds.replace(",", "."))
+            now = time.localtime(_STARTED_WALL)
+            since_midnight = now.tm_hour * 3600 + now.tm_min * 60 + now.tm_sec
+            since_midnight += _STARTED_WALL % 1
+            took = since_midnight - began
+            if took < 0:  # started before midnight, running after it
+                took += 86400
+        else:
+            took = _STARTED_WALL - float(stamp.replace(",", "."))
+    except (ValueError, TypeError):
+        return None
+    return took if 0 <= took <= SANE_LAUNCH_S else None
+
+
+def launcher_seconds() -> tuple[float | None, float | None]:
+    """(the script's own work, starting Python), as far as either is known."""
+    began = _until_import(os.environ.get(LAUNCH_ENV, "").strip())
+    started_python = _until_import(os.environ.get(PYTHON_ENV, "").strip())
+    if began is None:
+        return None, started_python
+    if started_python is None:
+        return began, None
+    # The second stamp is later, so less time has passed since it.
+    return max(began - started_python, 0.0), started_python
+
+
+def mark(label: str) -> None:
+    """Note that this step has just finished.
+
+    Always recorded, whether or not anybody asked for a report: it is a
+    string and a float appended to a list, and a start that turns out to
+    have been slow cannot be measured after the fact.
+    """
+    _marks.append((label, time.perf_counter()))
+
+
+def why_shown() -> str:
+    """Why the report is in the Event Log, and how to stop it -- it is only
+    there when asked for, by the option or the environment variable.
+
+    Said every time, because ``--timing`` is exactly the kind of thing that
+    gets added to a shortcut for one investigation and forgotten, and then the
+    report turns up at every start with nothing to say where it came from.
+    """
+    if FLAG in sys.argv:
+        return (
+            f"Shown because pyflashgui was started with the {FLAG} option. Leave it "
+            "out of the shortcut or command to stop this report."
+        )
+    return f"Shown because the {ENV} environment variable is set. Remove it to stop this report."
+
+
+def report_lines() -> list[str]:
+    """Each step and what it cost, slowest last so the answer is visible."""
+    if not _marks:
+        return []
+    steps = []
+    previous = _STARTED
+    for label, at in _marks:
+        steps.append((label, at - previous))
+        previous = at
+    lines = [
+        "Startup timing (seconds), from the first import in __main__",
+        f"({NOTICE_STEP} is you, and is not in the total):",
+    ]
+    # Before the clock above started, and often the largest part of the wait:
+    # the launcher's own checks, then the interpreter itself starting.
+    script, interpreter = launcher_seconds()
+    if script is not None:
+        lines.append(f"  {script:6.3f}  the launcher script (before the rest)")
+    if interpreter is not None:
+        lines.append(f"  {interpreter:6.3f}  starting Python (before the rest)")
+    lines += [f"  {took:6.3f}  {label}" for label, took in steps]
+    work = [step for step in steps if step[0] != NOTICE_STEP]
+    lines.append(f"  {sum(took for _, took in work):6.3f}  total, not counting the wait")
+    label, took = max(work or steps, key=lambda step: step[1])
+    lines.append(f"The longest step was {label}, at {took:.3f} s")
+    return lines + import_lines()
+
+
+def started_at() -> float:
+    """The wall clock as this module was imported, which is as near as
+    anything gets to when the process began."""
+    return _STARTED_WALL
+
+
+def step_times() -> list[tuple[str, float]]:
+    """Each step and how long it took, the wait for the notice left out.
+
+    The launcher's own work and Python starting come first when the
+    launcher stamped them: a dependency check that installs something is a
+    slow start too, and nothing after Python starts would show it.
+    """
+    out: list[tuple[str, float]] = []
+    script, interpreter = launcher_seconds()
+    if script is not None:
+        out.append(("the launcher script", script))
+    if interpreter is not None:
+        out.append(("starting Python", interpreter))
+    previous = _STARTED
+    for label, at in _marks:
+        if label != NOTICE_STEP:
+            out.append((label, at - previous))
+        previous = at
+    return out
+
+
+def import_times() -> dict[str, float]:
+    """Seconds spent importing each top-level package, so far."""
+    return dict(_imports)
+
+
+def total_work() -> float:
+    """How long starting took, not counting the wait for the notice.
+
+    Zero before anything has been marked, which is what a test or a script
+    that imported this module and never started a window will see.
+    """
+    if not _marks:
+        return 0.0
+    previous, total = _STARTED, 0.0
+    for label, at in _marks:
+        if label != NOTICE_STEP:
+            total += at - previous
+        previous = at
+    return total
+
+
+def write_report(folder: Path) -> Path | None:
+    """Leave the report where it can be found again and pasted into a report."""
+    lines = report_lines()
+    if not lines:
+        return None
+    path = Path(folder) / REPORT_NAME
+    try:
+        path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    except OSError:  # a read-only folder is not worth failing a start over
+        return None
+    return path