pyflashgui 0.1.0__py3-none-any.whl

pyflashgui/core/installation.py

@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Where pyflashgui is running from: which Python, which environment, which copy.
+
+For About and the diagnostics report. A machine with more than one Python --
+one in Program Files, one in the user's folder, a virtual environment made
+for testing -- can start pyflashgui from any of them, and the version numbers
+alone say nothing about which. Worse, ``python -m pyflashgui`` run inside a
+source folder imports the package from that folder whether or not the
+environment has pyflashgui installed, and an installed copy in the same
+environment is then silently not the one running.
+
+Read from the interpreter and the package metadata, nothing imported or run.
+"""
+
+from __future__ import annotations
+
+import json
+import site
+import sys
+from importlib import metadata
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+import pyflashgui
+
+#: The folder the running pyflashgui package was imported from.
+PACKAGE = Path(pyflashgui.__file__).resolve().parent
+
+
+def in_virtual_environment() -> bool:
+    return sys.prefix != sys.base_prefix
+
+
+def site_folders() -> list[str]:
+    """Where this environment installs packages, the user's own folder included."""
+    folders = list(site.getsitepackages())
+    if site.ENABLE_USER_SITE:
+        folders.append(site.getusersitepackages())
+    return folders
+
+
+def installed(folders: list[str] | None = None) -> metadata.Distribution | None:
+    """pyflashgui as this environment has it installed, or None.
+
+    Looked for in the environment's own folders only. The whole of sys.path
+    would include the folder Python was started in, and a source folder has
+    setuptools' ``pyflashgui.egg-info`` lying in it from a build, which is not
+    an installation of anything.
+    """
+    found = metadata.distributions(name="pyflashgui", path=folders or site_folders())
+    return next(iter(found), None)
+
+
+def _editable_root(dist: metadata.Distribution) -> Path | None:
+    """The source folder of an editable install, from pip's direct_url.json."""
+    try:
+        said = json.loads(dist.read_text("direct_url.json") or "{}")
+    except (OSError, ValueError):
+        return None
+    if not said.get("dir_info", {}).get("editable"):
+        return None
+    url = urlparse(said.get("url", ""))
+    if url.scheme != "file":
+        return None
+    path = unquote(url.path)
+    # file:///C:/Git/pyflashgui parses to /C:/Git/pyflashgui on Windows.
+    if len(path) > 2 and path[0] == "/" and path[2] == ":":
+        path = path[1:]
+    return Path(url.netloc + path if url.netloc else path)
+
+
+#: How the running copy got here: what origin() answers.
+FROZEN = "frozen"  # the Windows installer's build
+PIP = "pip"  # installed with pip, and the copy running
+EDITABLE = "editable"  # an editable install of a source folder, and the copy running
+NOT_INSTALLED = "not installed"  # nothing in this environment: a folder's copy
+OTHER_PIP = "other pip"  # a folder's copy, beside a pip install that is not running
+OTHER_EDITABLE = "other editable"  # a folder's copy, beside an editable install of another
+
+
+def origin(package: Path = PACKAGE) -> tuple[str, Path | None, str]:
+    """(kind, the editable install's source folder, the installed version).
+
+    The case worth catching is the running copy not being the installed one:
+    started from inside a source folder, Python imports the folder, and the
+    environment's own pyflashgui -- or the absence of one -- is not what is
+    running.
+    """
+    if getattr(sys, "frozen", False):
+        return FROZEN, None, ""
+    if (dist := installed()) is None:
+        return NOT_INSTALLED, None, ""
+    if (root := _editable_root(dist)) is not None:
+        return (EDITABLE if _same(root / "pyflashgui", package) else OTHER_EDITABLE), root, ""
+    if _same(Path(str(dist.locate_file("pyflashgui"))), package):
+        return PIP, None, dist.version
+    return OTHER_PIP, None, dist.version
+
+
+def how_installed(package: Path = PACKAGE) -> str:
+    """How the running copy of pyflashgui got here, as a report would say it."""
+    kind, root, version = origin(package)
+    return {
+        FROZEN: "the Windows installer's build",
+        PIP: "pip",
+        EDITABLE: f"pip, editable, from {root}",
+        NOT_INSTALLED: "not installed in this environment: imported from the folder above",
+        OTHER_PIP: (
+            f"imported from the folder above, not the pip install ({version}) in this environment"
+        ),
+        OTHER_EDITABLE: (
+            f"imported from the folder above, not the editable install of {root} "
+            "in this environment"
+        ),
+    }[kind]
+
+
+def _same(a: Path, b: Path) -> bool:
+    try:
+        return a.resolve() == b.resolve()
+    except OSError:
+        return False
+
+
+def report() -> list[tuple[str, str]]:
+    """(label, value) lines: the interpreter, its environment, and the package."""
+    if getattr(sys, "frozen", False):
+        return [("Installed", f"{how_installed()}, in {Path(sys.executable).parent}")]
+    lines = [("Interpreter", sys.executable)]
+    if in_virtual_environment():
+        lines.append(("Environment", f"{sys.prefix} (made from {sys.base_prefix})"))
+    else:
+        lines.append(("Environment", f"{sys.prefix} (no virtual environment)"))
+    lines.append(("Package", str(PACKAGE)))
+    lines.append(("Installed", how_installed()))
+    return lines

pyflashgui/core/layout.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""The dock arrangement, kept with the workspace rather than in QSettings.
+
+Qt hands out an opaque block of bytes for a window's dock layout and for a
+splitter's position, and the obvious home for those is QSettings, which is
+where they used to live. But QSettings is a per-machine store -- a registry
+hive on Windows -- and a workspace has to be one folder: something that can be
+copied to a backup, kept in version control, or sent to someone else whole. A layout left
+behind in the registry would be the one part of a workspace that could not travel.
+
+So the bytes go in a small JSON file beside the settings, base64 encoded
+because that is what JSON can carry. Nobody is meant to read them; what
+matters is that they are *in* the folder.
+
+What stays in QSettings is where the window sits on the screen, which belongs
+to this desk and these monitors rather than to the work: switching product
+should rearrange the panes, not move the window to where it was when somebody
+last used that product on a different machine.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+
+
+class Layout:
+    """Opaque Qt state, by key, saved in one file with the workspace."""
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._data: dict[str, str] = {}
+        if path.exists():
+            try:
+                loaded = json.loads(path.read_text(encoding="utf-8"))
+                self._data = {k: v for k, v in loaded.items() if isinstance(v, str)}
+            except (OSError, ValueError, AttributeError):
+                self._data = {}  # a truncated write, or a hand-edited file
+
+    def get(self, key: str) -> bytes | None:
+        """The bytes stored under this key, or None if there are none.
+
+        None rather than empty bytes: Qt's restoreState treats an empty state
+        as a state, and answers it by leaving the window with no docks at all.
+        """
+        encoded = self._data.get(key)
+        if not encoded:
+            return None
+        try:
+            return base64.b64decode(encoded)
+        except ValueError:
+            return None
+
+    def set(self, key: str, value: bytes | None) -> None:
+        if value is None or len(value) == 0:
+            self.remove(key)
+            return
+        self._data[key] = base64.b64encode(bytes(value)).decode("ascii")
+        self.save()
+
+    def remove(self, key: str) -> None:
+        if self._data.pop(key, None) is not None:
+            self.save()
+
+    def keys(self) -> list[str]:
+        return sorted(self._data)
+
+    def save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(json.dumps(self._data, indent=2, sort_keys=True), encoding="utf-8")

pyflashgui/core/memory_map.py

@@ -0,0 +1,234 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""What will be written where: firmware images laid over a target's memory.
+
+Worked out before anything is sent, from the same bytes that will be sent.
+A file linked for the wrong part, a binary given the wrong address and two
+files that both claim the same sector are all visible here, where finding
+them costs nothing, rather than part way through programming a board.
+
+Nothing here touches a probe or Qt. It is handed images and regions and
+answers with plain data, which is what makes it testable without either.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+
+from pyflashgui.core.events import ERROR, WARNING
+from pyflashgui.core.images import Image
+
+FLASH = "flash"
+RAM = "ram"
+ROM = "rom"
+OTHER = "other"
+
+
+@dataclass(frozen=True)
+class Region:
+    """One stretch of a target's memory, and what kind of memory it is."""
+
+    name: str
+    start: int
+    length: int
+    kind: str  # one of FLASH, RAM, ROM, OTHER
+    #: What is erased at a time, in bytes. 0 where nothing is: RAM, ROM.
+    sector_size: int = 0
+    #: What is programmed at a time, in bytes. 0 where it does not apply.
+    page_size: int = 0
+    #: The region this one is another address for, if it is one. A device may
+    #: show the same flash at several addresses and take writes at only one.
+    alias_of: str = ""
+
+    @property
+    def end(self) -> int:
+        """The address after the last byte."""
+        return self.start + self.length
+
+    def __contains__(self, address: int) -> bool:
+        return self.start <= address < self.end
+
+
+@dataclass(frozen=True)
+class Piece:
+    """Part of one file's data that falls in one region, or in none."""
+
+    source: str  # the file's name
+    address: int
+    length: int
+    region: Region | None
+
+    @property
+    def end(self) -> int:
+        return self.address + self.length
+
+
+@dataclass(frozen=True)
+class Usage:
+    """How much of one flash region the files take up."""
+
+    region: Region
+    used: int  # bytes the files write
+    sectors: int  # sectors those bytes touch, each of which is erased whole
+
+    @property
+    def erased(self) -> int:
+        """Bytes erased to make room: every touched sector, all of it."""
+        return self.sectors * self.region.sector_size
+
+    @property
+    def fraction(self) -> float:
+        return self.used / self.region.length if self.region.length else 0.0
+
+
+@dataclass(frozen=True)
+class Problem:
+    """Something about the layout that needs looking at before programming."""
+
+    level: str  # WARNING or ERROR, as the Event Log has them
+    message: str
+
+
+@dataclass
+class Layout:
+    """Every piece of every file, where it lands, and what is wrong with that."""
+
+    pieces: list[Piece] = field(default_factory=list)
+    problems: list[Problem] = field(default_factory=list)
+    usage: list[Usage] = field(default_factory=list)
+    #: False when the target's memory is not known, so nothing could be
+    #: checked against it: the pieces are listed and none is called wrong.
+    checked: bool = True
+
+    @property
+    def programmable(self) -> bool:
+        """Whether programming can go ahead: nothing here is an error."""
+        return not any(p.level == ERROR for p in self.problems)
+
+
+def region_at(regions: Sequence[Region], address: int) -> Region | None:
+    for region in regions:
+        if address in region:
+            return region
+    return None
+
+
+def _split(source: str, address: int, length: int, regions: Sequence[Region]) -> list[Piece]:
+    """One run of bytes, cut wherever it crosses from one region to another."""
+    pieces = []
+    end = address + length
+    while address < end:
+        region = region_at(regions, address)
+        if region is not None:
+            stop = min(end, region.end)
+        else:
+            # Up to the next region that starts inside the run, or all of it.
+            starts = [r.start for r in regions if address < r.start < end]
+            stop = min(starts, default=end)
+        pieces.append(Piece(source, address, stop - address, region))
+        address = stop
+    return pieces
+
+
+def _span(address: int, end: int) -> str:
+    return f"{address:08X} to {end - 1:08X}"
+
+
+def _bytes(count: int) -> str:
+    return "1 byte" if count == 1 else f"{count} bytes"
+
+
+def _overlaps(pieces: Iterable[Piece]) -> list[Problem]:
+    """Where two runs of bytes claim the same addresses.
+
+    An error whichever files they are from: the second to be written wins, and
+    which is second is not something anybody chose.
+    """
+    problems = []
+    ordered = sorted(pieces, key=lambda p: (p.address, p.end))
+    reach: Piece | None = None  # the piece seen so far that ends furthest on
+    for piece in ordered:
+        if reach is not None and piece.address < reach.end:
+            end = min(piece.end, reach.end)
+            who = (
+                f"{reach.source} and {piece.source} both write"
+                if reach.source != piece.source
+                else f"{piece.source} writes twice to"
+            )
+            problems.append(Problem(ERROR, f"{who} {_span(piece.address, end)}."))
+        if reach is None or piece.end > reach.end:
+            reach = piece
+    return problems
+
+
+def _placement(piece: Piece, complete: bool = True) -> Problem | None:
+    """What is wrong with where one piece lands, if anything is."""
+    what = f"{piece.source}: {_bytes(piece.length)} at {_span(piece.address, piece.end)}"
+    region = piece.region
+    if region is None:
+        if not complete:
+            return Problem(
+                WARNING,
+                f"{what} are outside the memory listed for this target, which may not "
+                "be all of it.",
+            )
+        return Problem(ERROR, f"{what} are outside the target's memory.")
+    if region.alias_of:
+        return Problem(
+            ERROR,
+            f"{what} are in {region.name}, which is another address for "
+            f"{region.alias_of} and cannot be programmed through.",
+        )
+    if region.kind == RAM:
+        # Not refused: loading a program into RAM to run it is a real thing
+        # to do. But it is not what a file meant for flash should be doing.
+        return Problem(
+            WARNING, f"{what} are in RAM ({region.name}), and will be lost at the next reset."
+        )
+    if region.kind != FLASH:
+        return Problem(ERROR, f"{what} are in {region.name}, which cannot be written.")
+    return None
+
+
+def _usage(pieces: Iterable[Piece], regions: Sequence[Region]) -> list[Usage]:
+    """What each flash region holds, for the ones anything is written to."""
+    out = []
+    for region in regions:
+        if region.kind != FLASH or region.alias_of:
+            continue
+        mine = [p for p in pieces if p.region is region]
+        if not mine:
+            continue
+        sectors: set[int] = set()
+        if region.sector_size:
+            for piece in mine:
+                first = (piece.address - region.start) // region.sector_size
+                last = (piece.end - 1 - region.start) // region.sector_size
+                sectors.update(range(first, last + 1))
+        out.append(Usage(region, used=sum(p.length for p in mine), sectors=len(sectors)))
+    return out
+
+
+def lay_out(images: Iterable[Image], regions: Sequence[Region], complete: bool = True) -> Layout:
+    """Where every byte of these files would go on a target with this memory.
+
+    ``complete`` says whether the regions are every address the target can
+    be written at. Where they may not be, bytes outside them are a warning
+    and not an error: refusing a file that the target would have taken is
+    worse than passing on one that it will refuse for itself.
+
+    With no regions -- a target whose memory is not known until it is
+    connected to -- the pieces are still listed and overlaps still found, and
+    ``checked`` says that nothing was compared with the target.
+    """
+    layout = Layout(checked=bool(regions))
+    for image in images:
+        for segment in image.segments:
+            layout.pieces += _split(image.name, segment.address, len(segment), regions)
+    layout.problems += _overlaps(layout.pieces)
+    if layout.checked:
+        found = (_placement(piece, complete) for piece in layout.pieces)
+        layout.problems += [p for p in found if p is not None]
+        layout.usage = _usage(layout.pieces, regions)
+    return layout

pyflashgui/core/packages.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Which packages pyflashgui runs on, and which versions of them are here.
+
+For About and the diagnostics report. The list is read rather than written
+down here, so it cannot fall behind: a source folder's ``pyproject.toml`` is
+what the launcher installs from, and anything else -- a pip installation, or
+the Windows build, which carries the metadata for this -- has the installed
+package's own record of what it requires.
+
+Nothing is imported to find a version. The metadata says, and importing some
+of these (pyOCD brings a disassembler) would take longer than the report does.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from collections.abc import Callable
+from importlib import metadata
+from pathlib import Path
+
+#: The folder pyproject.toml is in, for a source folder.
+ROOT = Path(__file__).resolve().parent.parent.parent
+
+_REQUIREMENT = re.compile(r"\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[([^\]]*)\])?")
+_EXTRA = re.compile(r"""extra\s*==\s*["']([^"']+)["']""")
+
+
+class Requirement:
+    """One line of a requirements list: a name, the extras asked of it, and
+    the extra it belongs to, if any."""
+
+    def __init__(self, text: str) -> None:
+        spec, _, marker = text.partition(";")
+        found = _REQUIREMENT.match(spec)
+        if found is None:
+            raise ValueError(f"not a requirement: {text!r}")
+        self.name = found.group(1)
+        self.extras = {e.strip() for e in (found.group(2) or "").split(",") if e.strip()}
+        extra = _EXTRA.search(marker)
+        self.extra = extra.group(1) if extra else None
+
+    @property
+    def key(self) -> str:
+        """The name as pip compares them: PySide6_Essentials is PySide6-Essentials."""
+        return normalise(self.name)
+
+
+def normalise(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def declared(root: Path = ROOT) -> list[Requirement]:
+    """pyflashgui's own requirements: the dependencies, then the "all" extra."""
+    pyproject = root / "pyproject.toml"
+    try:
+        project = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"]
+        lines = list(project["dependencies"])
+        optional = project.get("optional-dependencies", {}).get("all", [])
+        lines += [f'{line}; extra == "all"' for line in optional]
+    except (OSError, KeyError, tomllib.TOMLDecodeError):
+        lines = metadata.requires("pyflashgui") or []
+    # Dev tools are the contributor's, not the application's.
+    return [r for r in map(Requirement, lines) if r.extra in (None, "all")]
+
+
+def version(name: str) -> str | None:
+    try:
+        return metadata.version(name)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def pulled_in(
+    direct: list[Requirement],
+    requires: Callable[[str], list[str] | None] = metadata.requires,
+    have: Callable[[str], str | None] = version,
+) -> list[str]:
+    """What the direct requirements brought with them, by name, installed ones only.
+
+    A requirement behind an environment marker -- Windows only, an older
+    Python -- is counted when it is installed and left out when it is not,
+    which answers the marker without having to evaluate it.
+    """
+    seen = {r.key for r in direct}
+    found: dict[str, str] = {}
+    queue = [r for r in direct if have(r.name)]
+    while queue:
+        parent = queue.pop()
+        try:
+            lines = requires(parent.name) or []
+        except metadata.PackageNotFoundError:
+            continue
+        for line in lines:
+            child = Requirement(line)
+            if child.extra is not None and child.extra not in parent.extras:
+                continue
+            if child.key in seen or not have(child.name):
+                continue
+            seen.add(child.key)
+            found[child.key] = child.name
+            queue.append(child)
+    return sorted(found.values(), key=str.lower)

pyflashgui/core/paths.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Where the machine's own things live.
+
+The settings and the layout live in a workspace -- see ``core/workspaces.py``
+-- because they are about the product being worked on rather than about this
+computer. What is here is the folder the workspaces all sit under.
+
+Windows:  %APPDATA%\\pyflashgui        (e.g. C:\\Users\\you\\AppData\\Roaming\\pyflashgui)
+Linux:    $XDG_CONFIG_HOME/pyflashgui  (default ~/.config/pyflashgui)
+macOS:    ~/Library/Application Support/pyflashgui
+
+Set ``PYFLASHGUI_HOME`` to override (used by the tests).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from pyflashgui import APP_NAME
+
+
+def made(path: Path) -> Path:
+    """The folder, made if it is not there. Asked about before it is made.
+
+    ``mkdir(exist_ok=True)`` is one call and looks cheaper than a question
+    followed by a call, and on a local disc it is. On a profile redirected
+    to a network share, or one a scanner is watching, creating a directory
+    is the expensive operation and asking whether it exists is not: half a
+    second went on two of these at startup on such a machine, and these
+    functions are called all over the place.
+    """
+    if not path.is_dir():
+        path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def user_dir() -> Path:
+    if override := os.environ.get("PYFLASHGUI_HOME"):
+        base = Path(override)
+    elif sys.platform == "win32":
+        base = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) / APP_NAME
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Application Support" / APP_NAME
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / APP_NAME
+    return made(base)

pyflashgui/core/settings.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Persistent key/value store for things the GUI remembers (the target, the
+last used probe, ...). One JSON file, dotted keys, saved on change.
+
+Kept separate from QSettings (which holds window layout) so the contents are
+human readable and easy to hand-edit or version control.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class Settings:
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._data: dict[str, Any] = {}
+        if path.exists():
+            try:
+                self._data = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                self._data = {}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        self._data[key] = value
+        self.save()
+
+    def keys(self) -> list[str]:
+        return sorted(self._data)
+
+    def remove(self, key: str) -> None:
+        """Forget a setting, so that whatever default applies applies again."""
+        if self._data.pop(key, None) is not None:
+            self.save()
+
+    def save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(json.dumps(self._data, indent=2, sort_keys=True), encoding="utf-8")