pyflashgui 0.1.0__py3-none-any.whl

pyflashgui/core/compare.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""What was read from a target against what a file says should be there.
+
+The same question Verify asks, the other way about: Verify reads what the
+files cover and says whether it matches, and this takes what has already been
+read -- any stretch of memory, from any time -- and says where a file agrees
+with it and where it does not.
+
+A file and a read rarely cover the same addresses. Only where they overlap is
+there anything to compare, and what each has that the other does not is
+counted and said rather than called a difference: flash the file does not
+mention is not flash the file says is wrong.
+
+Nothing here touches a probe or Qt.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from pyflashgui.core.images import Image, Segment
+
+SAME, DIFFERENT = 0, 1
+
+
+@dataclass(frozen=True)
+class Comparison:
+    """Where a file and a read agree, byte by byte over the read."""
+
+    #: The file's name, for saying what was compared with.
+    name: str
+    #: Where the read starts.
+    address: int
+    #: A byte for each byte read: DIFFERENT where the file has another value
+    #: there, SAME where it has the same or says nothing.
+    differs: bytes
+    #: A byte for each byte read: 1 where the file has a value for it.
+    covered: bytes
+    #: The file's value for each byte read, where it has one.
+    file: bytes
+    #: Bytes the file has at addresses that were not read.
+    outside: int
+
+    @property
+    def compared(self) -> int:
+        """Bytes that both have, which is all that could be compared."""
+        return self.covered.count(1)
+
+    @property
+    def different(self) -> int:
+        return self.differs.count(DIFFERENT)
+
+    @property
+    def unmentioned(self) -> int:
+        """Bytes read that the file says nothing about."""
+        return len(self.covered) - self.compared
+
+    @property
+    def first(self) -> int | None:
+        """The offset of the first byte that differs, or None when none does."""
+        at = self.differs.find(DIFFERENT)
+        return at if at >= 0 else None
+
+    def run_from(self, offset: int) -> int:
+        """How many bytes in a row differ, starting at this one."""
+        end = self.differs.find(SAME, offset)
+        return (len(self.differs) if end < 0 else end) - offset
+
+    def next_run(self, after: int | None) -> int | None:
+        """Where the next stretch of differing bytes starts, going round at the end.
+
+        ``after`` is where the last one shown starts, or None for the first
+        of all. None back when nothing differs.
+        """
+        if self.first is None:
+            return None
+        if after is None:
+            return self.first
+        end = self.differs.find(SAME, after)
+        at = -1 if end < 0 else self.differs.find(DIFFERENT, end)
+        return at if at >= 0 else self.first
+
+    def previous_run(self, before: int | None) -> int | None:
+        """Where the stretch of differing bytes before this one starts, going round."""
+        if self.first is None:
+            return None
+        last = self.differs.rfind(DIFFERENT, 0, before) if before else -1
+        if last < 0:
+            last = self.differs.rfind(DIFFERENT)
+        # Back from its last byte to its first: the byte after the one
+        # before it that does not differ.
+        return self.differs.rfind(SAME, 0, last) + 1
+
+
+#: Any byte but zero becomes DIFFERENT: what two bytes exclusive-or to is
+#: zero only where they are the same.
+_ANY_BIT = bytes([SAME]) + bytes([DIFFERENT]) * 255
+
+
+def _unlike(one: bytes, other: bytes) -> bytes:
+    """A byte for each pair: DIFFERENT where the two are not the same.
+
+    As two whole numbers, exclusive-ored: a megabyte compared a byte at a
+    time in Python is a second of a window that does not answer.
+    """
+    mixed = int.from_bytes(one, "big") ^ int.from_bytes(other, "big")
+    return mixed.to_bytes(len(one), "big").translate(_ANY_BIT)
+
+
+def compare(address: int, data: bytes, image: Image) -> Comparison:
+    """Lay a file over what was read from ``address``, and mark where they differ."""
+    file = bytearray(len(data))
+    covered = bytearray(len(data))
+    differs = bytearray(len(data))
+    outside = 0
+    end = address + len(data)
+    for segment in image.segments:
+        start = max(segment.address, address)
+        stop = min(segment.end, end)
+        overlap = max(0, stop - start)
+        outside += len(segment) - overlap
+        if overlap:
+            at, within = start - address, start - segment.address
+            wanted = segment.data[within : within + overlap]
+            file[at : at + overlap] = wanted
+            covered[at : at + overlap] = b"\x01" * overlap
+            differs[at : at + overlap] = _unlike(wanted, data[at : at + overlap])
+    return Comparison(
+        name=image.name,
+        address=address,
+        differs=bytes(differs),
+        covered=bytes(covered),
+        file=bytes(file),
+        outside=outside,
+    )
+
+
+def compare_all(segments: Sequence[Segment], image: Image) -> Comparison:
+    """Lay a file over several runs of memory, one after another.
+
+    For what is shown in pieces, as a file with gaps in it is. The marks
+    are for the pieces end to end, in the order given, and ``address`` is
+    where the first starts: where a later byte is, is for whoever holds the
+    pieces to say.
+    """
+    made = [compare(segment.address, segment.data, image) for segment in segments]
+    covered = b"".join(one.covered for one in made)
+    return Comparison(
+        name=image.name,
+        address=segments[0].address if segments else 0,
+        differs=b"".join(one.differs for one in made),
+        covered=covered,
+        file=b"".join(one.file for one in made),
+        outside=image.size - covered.count(1),
+    )

pyflashgui/core/context.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""What the panes are handed: where things live, and where to say things.
+
+Keep this small and stable: everything a pane needs to remember something or
+to tell the user something should be reachable from ``ctx``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pyflashgui.core import paths, timing, workspaces
+from pyflashgui.core.events import EventLog
+from pyflashgui.core.layout import Layout
+from pyflashgui.core.settings import Settings
+
+
+class Context:
+    def __init__(self, events: EventLog | None = None) -> None:
+        # Marked in three because the whole of it is folders being made and
+        # two files being read, which costs nothing on a local disc and a
+        # surprising amount on a profile that is redirected to a network
+        # share or watched by a scanner.
+        self.user_dir: Path = paths.user_dir()
+        timing.mark("user folder")
+        #: Which product is being worked on. Everything below belongs to it.
+        self.workspace: str = workspaces.active()
+        self.workspace_dir: Path = workspaces.active_dir()
+        timing.mark("workspace folders")
+        self.settings = Settings(workspaces.settings_path())
+        #: The dock arrangement, in the workspace folder rather than in
+        #: QSettings, so that the workspace is one thing that can be copied.
+        self.layout = Layout(workspaces.layout_path())
+        timing.mark("settings and layout files")
+        #: Everything said to the user goes through here, with a level.
+        self.events = events if events is not None else EventLog()

pyflashgui/core/events.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Everything the application has to say, and how much it matters.
+
+Every line that reaches the Event Log comes through here, with a level. That
+one change buys two things.
+
+The first is that a failure cannot be lost. The Event Log is a pane like any
+other and can be closed, and closing it must not mean "throw away anything
+you were going to tell me" -- press Program with no probe connected, and the
+button would simply do nothing. So a warning or an error opens the pane; a
+plain note does not, so closing it still means what it should mean, which is
+"stop chattering at me".
+
+The second is that the appearance of a line is decided in one place rather
+than at every call site, so how warnings and errors look is a change to the
+sink and nowhere else.
+
+Levels are strings rather than an enum on purpose: they are passed about as
+plain text, and nothing has to be imported to name one.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QObject, Signal
+
+INFORMATION = "information"
+WARNING = "warning"
+ERROR = "error"
+#: Something that was wrong is right again, or something worked: a board
+#: verified, a probe came back. Not an escalation of anything -- it is the one
+#: piece of news a log of failures otherwise never carries, and reading back
+#: through red to find out whether a fault ever cleared is a poor way to
+#: spend a morning.
+GOOD = "good"
+
+#: In the order they escalate, with GOOD off to the side. Anything
+#: unrecognised is treated as information: a mistyped level must not be able
+#: to make the pane spring open, nor to silently swallow the message.
+LEVELS = (INFORMATION, GOOD, WARNING, ERROR)
+
+#: The levels that mean something needs looking at.
+PROBLEMS = (WARNING, ERROR)
+
+
+class EventLog(QObject):
+    """The one way in. What listens is somebody else's business."""
+
+    posted = Signal(str, str)  # message, level
+
+    def post(self, message: str, level: str = INFORMATION) -> None:
+        # Emitted rather than called: messages arrive from worker threads --
+        # a flash in progress, the exception hook -- and a Qt widget may
+        # only be touched from the GUI thread. A queued signal is the crossing.
+        self.posted.emit(str(message), level if level in LEVELS else INFORMATION)
+
+    def information(self, message: str) -> None:
+        """Something happened. Worth recording, not worth interrupting for."""
+        self.post(message, INFORMATION)
+
+    def warning(self, message: str) -> None:
+        """What you asked for did not happen, or did not happen as asked."""
+        self.post(message, WARNING)
+
+    def error(self, message: str) -> None:
+        """Something went wrong that nobody asked for."""
+        self.post(message, ERROR)
+
+    def good(self, message: str) -> None:
+        """Something that was wrong is right again."""
+        self.post(message, GOOD)

pyflashgui/core/excepthook.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Put unhandled exceptions in the Event Log instead of nowhere.
+
+pyflashgui is started with ``pythonw.exe``, which has no console. An exception
+raised inside a Qt slot does not propagate anywhere useful: PySide prints the
+traceback to a standard error stream that does not exist, the slot simply
+does not finish, and the window carries on looking perfectly healthy.
+
+A stale call to a widget method -- ``.text()`` on what had become a combo box
+-- is enough: nothing is logged, no dialog appears, and whatever the slot was
+doing is left half done.
+
+So the hook routes tracebacks to the Event Log, where somebody can see them.
+Delivery goes through a signal because an exception can be raised on any
+thread and Qt widgets may only be touched from the GUI one.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+import traceback
+from collections.abc import Callable
+
+from PySide6.QtCore import QObject, Qt, QtMsgType, Signal, Slot, qInstallMessageHandler
+
+from pyflashgui.core.events import ERROR, INFORMATION
+
+#: Said of a Python traceback and of nothing else. Qt complains through the
+#: same handler about things that are often not pyflashgui's doing at all -- a
+#: platform plugin, a window manager -- and telling somebody those are bugs in
+#: this application is both wrong and unhelpful.
+BUG = "Unhandled error (this is a bug in pyflashgui; the action it interrupted did not finish):"
+
+
+class ExceptionLogger(QObject):
+    """Sends unhandled exceptions to a sink on the GUI thread."""
+
+    caught = Signal(str, str)  # message, level
+
+    def __init__(self, sink: Callable[[str, str], None]) -> None:
+        super().__init__()
+        self._sink = sink
+        self._previous = None
+        self._previous_thread = None
+        self._previous_qt = None
+        self._seen: set[str] = set()
+        # Queued: emitted from a worker thread, delivered on the GUI thread.
+        self.caught.connect(self._deliver, Qt.QueuedConnection)
+
+    def install(self) -> None:
+        self._previous = sys.excepthook
+        sys.excepthook = self._hook
+        # Worker threads have their own hook, and protocol work happens on
+        # them: an SDO read that dies must not die quietly either.
+        self._previous_thread = threading.excepthook
+        threading.excepthook = self._thread_hook
+        # Qt complains through its own channel, and those complaints are
+        # often the explanation -- a signal connected to nothing, a widget
+        # touched off the GUI thread.
+        self._previous_qt = qInstallMessageHandler(self._qt_hook)
+
+    def remove(self) -> None:
+        if self._previous is not None:
+            sys.excepthook = self._previous
+            self._previous = None
+        if self._previous_thread is not None:
+            threading.excepthook = self._previous_thread
+            self._previous_thread = None
+        qInstallMessageHandler(self._previous_qt)
+        self._previous_qt = None
+
+    def _thread_hook(self, args) -> None:
+        text = "".join(
+            traceback.format_exception(args.exc_type, args.exc_value, args.exc_traceback)
+        ).rstrip()
+        name = getattr(args.thread, "name", "?")
+        self.caught.emit(f"{BUG}\non thread {name}:\n{text}", ERROR)
+        if self._previous_thread is not None:
+            self._previous_thread(args)
+
+    def _qt_hook(self, mode, context, message) -> None:
+        # Critical and fatal are worth interrupting for. A Qt warning is
+        # usually the explanation of something else rather than the something
+        # else -- "unable to set geometry", "this plugin does not support
+        # propagateSizeHints" -- so it is recorded and left there, or the
+        # Event Log would spring open at every start on some machines.
+        if mode in (QtMsgType.QtCriticalMsg, QtMsgType.QtFatalMsg):
+            self.caught.emit(f"Qt: {message}", ERROR)
+        elif mode == QtMsgType.QtWarningMsg:
+            self.caught.emit(f"Qt: {message}", INFORMATION)
+        if self._previous_qt is not None:
+            self._previous_qt(mode, context, message)
+
+    def _hook(self, exc_type, exc, tb) -> None:
+        text = "".join(traceback.format_exception(exc_type, exc, tb)).rstrip()
+        self.caught.emit(f"{BUG}\n{text}", ERROR)
+        if self._previous is not None:
+            self._previous(exc_type, exc, tb)  # keep stderr working when there is one
+
+    @Slot(str, str)
+    def _deliver(self, text: str, level: str) -> None:
+        # A fault inside a repeating timer would otherwise fill the log with
+        # the same traceback fifty times a second.
+        key = text.rsplit("\n", 1)[-1]
+        if key in self._seen:
+            return
+        self._seen.add(key)
+        self._sink(text, level)