pyscopegui 0.1.0__py3-none-any.whl

pyscopegui/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""pyscopegui — oscilloscopes and logic analysers in one view, on one time axis."""
+
+__version__ = "0.1.0"
+APP_NAME = "pyscopegui"  # single place to change the display name

pyscopegui/__main__.py

@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""Entry point: `python -m pyscopegui`, or the `pyscopegui` command pip installs."""
+
+import importlib
+import os
+import sys
+
+from PySide6.QtWidgets import QApplication
+
+from pyscopegui import APP_NAME
+
+#: Imported by ``--selftest``. These are the modules a packaged build is most
+#: likely to be missing, because they are loaded by name at run time and so no
+#: static analysis can see them.
+SELFTEST_MODULES = (
+    "pyqtgraph",
+    "numpy",
+    "pyscopegui.ui.main_window",
+)
+
+
+def selftest() -> int:
+    """Import everything a build could plausibly be missing. Exit code only:
+    a windowed build has nowhere to print to."""
+    failures = []
+    for name in SELFTEST_MODULES:
+        try:
+            importlib.import_module(name)
+        except Exception as exc:
+            failures.append(f"{name}: {exc}")
+    # Every back end's module, asked for the way the instrument list asks.
+    try:
+        from pyscopegui import backends
+
+        for name, backend in backends.BACKENDS.items():
+            try:
+                getattr(importlib.import_module(backend.module), backend.cls)
+            except Exception as exc:
+                failures.append(f"back end {name}: {exc}")
+    except Exception as exc:
+        failures.append(f"pyscopegui.backends: {exc}")
+
+    try:
+        from pyscopegui import resources
+
+        if not resources.path("pyscopegui.ico").is_file():
+            failures.append("pyscopegui/resources/pyscopegui.ico: not shipped with this build")
+    except Exception as exc:
+        failures.append(f"pyscopegui.resources: {exc}")
+
+    # The manual is package data, so it is exactly the kind of file a build
+    # drops silently. Every page, by name: a manual that still opens is the
+    # worst way for a missing page to be found.
+    try:
+        from pyscopegui.help import missing_images, missing_pages
+
+        for page in missing_pages():
+            failures.append(f"pyscopegui/help/{page}: not shipped with this build")
+        for image in missing_images():
+            failures.append(f"pyscopegui/help/{image}: shown in the manual but not shipped")
+    except Exception as exc:
+        failures.append(f"pyscopegui.help: {exc}")
+
+    # Help > Licences reads these at run time from beside the executable. A
+    # build that ships them where it cannot see them would show empty tabs.
+    try:
+        from pyscopegui.ui.help_menu import missing_licence_files
+
+        failures += [
+            f"{name}: not found beside the application"
+            for name in missing_licence_files(getattr(sys, "frozen", False))
+        ]
+    except Exception as exc:
+        failures.append(f"pyscopegui.ui.help_menu: {exc}")
+
+    if failures:
+        sys.stderr.write("selftest failures:" + "".join(f"\n  {f}" for f in failures) + "\n")
+        return 1
+    return 0
+
+
+#: Who Windows thinks the windows belong to. Without one, a pyscopegui started
+#: from source is grouped under pythonw.exe and the taskbar shows Python's
+#: icon whatever the window says -- the window icon only reaches the title bar.
+APP_USER_MODEL_ID = "davhodg.pyscopegui"
+
+
+def set_icon(app) -> None:
+    """The application icon, before any window exists.
+
+    The .ico rather than the PNG: it holds each size drawn for that size, and
+    Qt picks the nearest one.
+    """
+    from PySide6.QtGui import QIcon
+
+    from pyscopegui import resources
+
+    if sys.platform == "win32":
+        try:
+            import ctypes
+
+            ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(APP_USER_MODEL_ID)
+        except (AttributeError, OSError):  # an unusual shell: the title bar still has it
+            pass
+    app.setWindowIcon(QIcon(str(resources.path("pyscopegui.ico"))))
+
+
+#: The libraries Qt's X11 plugin needs that Debian, Ubuntu and Linux Mint can
+#: leave out, each with the package it comes in. Without one, Qt stops with
+#: "could not load the Qt platform plugin xcb" and does not say which.
+XCB_LIBRARIES = (
+    ("libxcb-cursor.so.0", "libxcb-cursor0"),
+    ("libxcb-icccm.so.4", "libxcb-icccm4"),
+    ("libxcb-image.so.0", "libxcb-image0"),
+    ("libxcb-keysyms.so.1", "libxcb-keysyms1"),
+    ("libxcb-render-util.so.0", "libxcb-render-util0"),
+    ("libxkbcommon-x11.so.0", "libxkbcommon-x11-0"),
+)
+
+
+def uses_xcb(environ=None) -> bool:
+    """Whether Qt will draw through X11 here, where XCB_LIBRARIES are needed."""
+    if not sys.platform.startswith("linux"):
+        return False
+    environ = os.environ if environ is None else environ
+    chosen = environ.get("QT_QPA_PLATFORM", "")
+    if chosen:
+        return chosen.startswith("xcb")
+    return environ.get("XDG_SESSION_TYPE") != "wayland"
+
+
+def missing_xcb_packages(load=None) -> list[str]:
+    """The packages to install for the XCB_LIBRARIES that cannot be loaded."""
+    if load is None:
+        import ctypes
+
+        load = ctypes.CDLL
+    missing = []
+    for library, package in XCB_LIBRARIES:
+        try:
+            load(library)
+        except OSError:
+            missing.append(package)
+    return missing
+
+
+def main() -> int:
+    if "--selftest" in sys.argv:
+        return selftest()
+    if uses_xcb() and (missing := missing_xcb_packages()):
+        sys.stderr.write(
+            "Qt needs libraries this system does not have to draw the window. On Debian,\n"
+            "Ubuntu and Linux Mint:\n\n"
+            f"    sudo apt install {' '.join(missing)}\n"
+        )
+        return 1
+    app = QApplication.instance() or QApplication(sys.argv)
+    app.setApplicationName(APP_NAME)
+    app.setOrganizationName(APP_NAME)  # QSettings uses these two for the registry/ini path
+    set_icon(app)
+    # Before anything is drawn, so the window opens in the colours chosen.
+    from pyscopegui.ui import theme
+
+    theme.apply(theme.chosen())
+
+    # Imported here rather than at the top of the file so that a library
+    # which is not installed becomes a dialog. Started from pyscopegui.cmd
+    # there is no console -- it runs pythonw -- so an ImportError on the way
+    # up is a window that never appears and not one word about why.
+    try:
+        from pyscopegui.ui.main_window import MainWindow
+    except Exception as exc:
+        # Not ImportError alone: a library that is installed and will not
+        # load fails however it likes.
+        from pyscopegui.ui import messages
+
+        messages.critical(None, f"{APP_NAME} cannot start", why_it_cannot_start(exc))
+        sys.stderr and sys.stderr.write(why_it_cannot_start(exc) + "\n")
+        return 1
+
+    window = MainWindow()
+    window.show()
+    return app.exec()
+
+
+def why_it_cannot_start(failed: BaseException) -> str:
+    """What to tell somebody whose libraries would not load, and what to do.
+
+    Two different faults. A library that is not there is put right by
+    installing it. One that is there and will not load is usually two
+    libraries that no longer agree, and installing again changes nothing: it
+    wants the name of the file that failed, so that the pair can be found.
+    """
+    if isinstance(failed, ModuleNotFoundError):
+        return (
+            f"A library {APP_NAME} needs is missing:\n\n    {failed}\n\n"
+            "Start it with pyscopegui.cmd (or pyscopegui.sh), which installs "
+            "anything missing before starting, or install it with pip."
+        )
+    import traceback
+
+    where = traceback.extract_tb(failed.__traceback__)
+    place = f"\n    in {where[-1].filename}, line {where[-1].lineno}" if where else ""
+    return (
+        f"A library {APP_NAME} needs is installed but would not load:\n\n"
+        f"    {type(failed).__name__}: {failed}{place}\n\n"
+        "This is usually two libraries that no longer agree, after a new release "
+        "of one of them. Upgrading the one named above, or going back a version "
+        "of the one it was loading, normally puts it right; in a source folder, "
+        "deleting .venv and starting the launcher installs them all again."
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyscopegui/backends/__init__.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""The instruments pyscopegui can read, by name.
+
+Each is a module imported only when it is asked for, which is how python-can
+keeps its adapters: a back end may need a maker's library that is not on this
+machine, and one that cannot load must not take the others with it. The
+maker's library is never bundled: it is installed separately.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import NamedTuple
+
+from PySide6.QtCore import QObject
+
+from pyscopegui.backends.base import Instrument, Setting
+
+
+class Backend(NamedTuple):
+    module: str
+    cls: str
+    #: What the instrument list calls it.
+    title: str
+    #: A word for it, to tell its channels from another instrument's.
+    short: str
+
+
+#: Name -> where it lives. The name is what is remembered between runs.
+BACKENDS: dict[str, Backend] = {
+    "demo": Backend("pyscopegui.backends.demo", "DemoInstrument", "Demo signals", "Demo"),
+    "picoscope2000": Backend(
+        "pyscopegui.backends.picoscope2000", "PicoScope2000", "PicoScope 2204A (ps2000)", "Pico"
+    ),
+    "rigol1000z": Backend(
+        "pyscopegui.backends.rigol1000z", "Rigol1000Z", "Rigol DS1000Z series (network)", "Rigol"
+    ),
+}
+
+#: Chosen on a first run: something to look at with nothing plugged in.
+DEFAULT = "demo"
+
+
+def names() -> list[str]:
+    return list(BACKENDS)
+
+
+def title(name: str) -> str:
+    return BACKENDS[name].title
+
+
+def short(name: str) -> str:
+    return BACKENDS[name].short
+
+
+def settings(name: str) -> tuple[Setting, ...]:
+    """What this instrument lets you set. Needs its module, not its library."""
+    backend = BACKENDS[name]
+    return getattr(importlib.import_module(backend.module), backend.cls).SETTINGS
+
+
+def create(name: str, parent: QObject | None = None, options: dict | None = None) -> Instrument:
+    """Make the instrument called this. ImportError if its library is missing."""
+    backend = BACKENDS[name]
+    module = importlib.import_module(backend.module)
+    return getattr(module, backend.cls)(parent, options)

pyscopegui/backends/base.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""What every instrument looks like to the rest of pyscopegui.
+
+A scope, a logic analyser and a board of your own all come down to the same
+thing: a set of channels, sampled evenly, arriving a block at a time. A back
+end turns whatever its hardware speaks into that, and nothing above it knows
+which one it is talking to.
+
+Samples are counted rather than timestamped. A block says which sample it
+starts at and the rate they were taken at, so the time of any sample is its
+number over the rate -- exact, and free of the jitter in when a block
+happened to reach the computer, which is milliseconds and would otherwise be
+drawn as if the signal had it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from PySide6.QtCore import QObject, Signal
+
+ANALOG = "analog"
+DIGITAL = "digital"
+
+
+@dataclass(frozen=True)
+class Channel:
+    """One input of an instrument."""
+
+    #: What the instrument calls it, and what its samples arrive under.
+    key: str
+    name: str
+    kind: str = ANALOG
+    #: What an analog sample is measured in. A digital one is 0 or 1.
+    unit: str = "V"
+    #: The most an analog channel can read, either side of zero, as it is set
+    #: up now: 5.0 on a range of ±5 V. Zero where there is no such limit.
+    full_scale: float = 0.0
+    #: How it is set up, in a line, to be read beside its name: "1 V/div, 10x, DC".
+    detail: str = ""
+    #: The group its settings are listed under, so that choosing the channel
+    #: can show them: "Channel A". Empty where it has none.
+    group: str = ""
+
+
+@dataclass(frozen=True)
+class Setting:
+    """One thing about an instrument that can be chosen: a range, a rate.
+
+    Described rather than drawn, so that a back end needs no widgets of its
+    own and every instrument's settings look alike. A setting with choices is
+    a list to pick from, one whose default is True or False is a tick box,
+    one whose default is text is a box to type in, and anything else is a
+    number.
+    """
+
+    #: What it is saved under, and what the instrument is handed it as.
+    key: str
+    label: str
+    default: object
+    #: (value, what the list calls it), for a setting picked from a list.
+    choices: tuple[tuple[object, str], ...] = ()
+    #: For a number: its limits, how many decimal places, and what it is in.
+    minimum: float = 0.0
+    maximum: float = 0.0
+    decimals: int = 0
+    unit: str = ""
+    #: How far its arrows move it. Zero is through 1, 2, 5, 10, 20, 50: for a
+    #: number that runs over many powers of ten, where no one step suits.
+    step: float = 0.0
+    #: The heading it is listed under. Headings that start "Channel " are
+    #: the same settings over again for each channel, and are shown one
+    #: channel at a time.
+    group: str = ""
+    #: Taken up as the instrument runs, with what is on the plot kept.
+    #: Anything else starts the run again, from an empty plot.
+    live: bool = False
+    #: (key, value) of another setting this one depends on: it has a say only
+    #: while that one is at that value, and is greyed out otherwise.
+    needs: tuple[str, object] | None = None
+    tip: str = ""
+
+
+@dataclass(frozen=True)
+class Block:
+    """A run of evenly spaced samples of every channel, all the same length."""
+
+    #: The number of its first sample, counted from when the instrument started.
+    first: int
+    #: Samples per second.
+    rate: float
+    #: Channel key -> samples: float32 in the channel's unit for an analog
+    #: channel, uint8 holding 0 or 1 for a digital one.
+    data: dict[str, np.ndarray]
+    #: The samples before this one were not taken, on purpose: the instrument
+    #: stopped reading for a moment to do something else. Drawn as a gap like
+    #: any other, and not reported as samples lost.
+    after_pause: bool = False
+    #: A capture complete in itself, taken by the instrument around its own
+    #: trigger, rather than the next stretch of a stream. It takes the place
+    #: of whatever was held; ``first`` is nought.
+    sweep: bool = False
+    #: In a sweep, the sample the instrument's trigger is at, or None if it
+    #: was set to take the sweep without one.
+    trigger: int | None = None
+    #: In a sweep, whether the signal crossed the level there, as opposed to
+    #: the instrument giving up waiting and taking the sweep anyway.
+    triggered: bool = False
+
+    def __len__(self) -> int:
+        return len(next(iter(self.data.values()), ()))
+
+
+class Instrument(QObject):
+    """A source of samples. Subclass it, and add the class to ``BACKENDS``.
+
+    Made with a parent and its own settings: whatever settings.json holds
+    under ``instrument.<name>``, which may be nothing, or not a dictionary.
+    """
+
+    #: A ``Block``. Emitted on the GUI thread, or queued to it from another.
+    block = Signal(object)
+    #: Open, or not: connected to, and ready to be started.
+    opened_changed = Signal(bool)
+    #: Running, or not.
+    state_changed = Signal(bool)
+    #: Something went wrong that stopped it, in words for the Event Log.
+    error = Signal(str)
+    #: Something worth recording that is not a problem: which scope was found.
+    note = Signal(str)
+    #: It is still running, but what it is sending is not what was asked for.
+    warning = Signal(str)
+
+    #: What can be set, in the order it should be listed, before anything
+    #: is known about the instrument that is plugged in.
+    SETTINGS: tuple[Setting, ...] = ()
+
+    def settings_offered(self) -> tuple[Setting, ...]:
+        """What can be set on this one. Asked again once it is open, when a
+        back end may know more: which ranges this model has."""
+        return self.SETTINGS
+
+    @property
+    def sweeps(self) -> bool:
+        """Whether it sends sweeps, each complete in itself, rather than a stream."""
+        return False
+
+    def set_trigger(
+        self, source: str | None, level: float, rising: bool, position: float, auto: bool
+    ) -> None:
+        """What to trigger on, for an instrument that sends sweeps and so
+        triggers itself. ``auto`` is to take a sweep anyway when no trigger
+        comes. An instrument that streams is triggered by pyscopegui, and
+        need do nothing here."""
+
+    def set(self, key: str, value: object) -> None:
+        """Take up a setting. A ``live`` one may arrive while running; any
+        other arrives while stopped, and is used at the next start."""
+
+    @property
+    def is_open(self) -> bool:
+        raise NotImplementedError
+
+    def open(self) -> None:
+        """Connect to the instrument, which may take seconds and happen on a
+        thread: ``opened_changed`` says when it has, or that it could not."""
+        raise NotImplementedError
+
+    def close(self) -> None:
+        """Stop, and let go of the instrument, so that another program can have it."""
+        raise NotImplementedError
+
+    def channels(self) -> list[Channel]:
+        """The inputs it has, in the order they should be listed."""
+        raise NotImplementedError
+
+    @property
+    def rate(self) -> float:
+        """Samples per second, the same for every channel."""
+        raise NotImplementedError
+
+    @property
+    def running(self) -> bool:
+        raise NotImplementedError
+
+    def start(self) -> None:
+        """Begin sending blocks, counting samples from zero again. Opens the
+        instrument first if it is not open."""
+        raise NotImplementedError
+
+    def stop(self) -> None:
+        """Stop sending blocks. Stopping one that is not running is not an error."""
+        raise NotImplementedError

pyscopegui/backends/demo.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 davhodg
+"""An instrument that needs no hardware: two analog and four digital channels.
+
+Something to look at on a first run, and what the tests read. Every sample is
+a function of its number alone, so the same stretch of time always holds the
+same data whichever blocks it happened to arrive in.
+"""
+
+from __future__ import annotations
+
+import time
+
+import numpy as np
+from PySide6.QtCore import QObject, QTimer
+
+from pyscopegui.backends.base import DIGITAL, Block, Channel, Instrument
+
+RATE = 100_000.0
+#: How often a block is sent. Twenty a second is smooth to watch and far
+#: fewer calls than Python would notice.
+TICK_MS = 50
+#: The most one block holds. A computer that was asleep, or a window dragged
+#: for a second, would otherwise be answered with everything it missed at once.
+MOST_S = 0.5
+
+SINE_HZ = 50.0
+RAMP_HZ = 7.0
+#: Samples per half period of the fastest digital channel: 1 kHz at RATE.
+#: Each channel after it is half the rate of the one before, as a counter's bits are.
+CLOCK_HALF = 50
+
+CHANNELS = [
+    Channel("A", "A: sine", full_scale=2.0),
+    Channel("B", "B: ramp", full_scale=0.5),
+    *(Channel(f"D{bit}", f"D{bit}", DIGITAL, "") for bit in range(4)),
+]
+
+
+def samples(first: int, count: int) -> dict[str, np.ndarray]:
+    """What every channel reads for ``count`` samples starting at ``first``."""
+    n = np.arange(first, first + count, dtype=np.int64)
+    t = n / RATE
+    data = {
+        "A": (2.0 * np.sin(2 * np.pi * SINE_HZ * t)).astype(np.float32),
+        "B": ((t * RAMP_HZ) % 1.0 - 0.5).astype(np.float32),
+    }
+    counter = n // CLOCK_HALF
+    for bit in range(4):
+        data[f"D{bit}"] = ((counter >> bit) & 1).astype(np.uint8)
+    return data
+
+
+class DemoInstrument(Instrument):
+    def __init__(self, parent: QObject | None = None, options: dict | None = None) -> None:
+        super().__init__(parent)
+        self._timer = QTimer(self, interval=TICK_MS, timeout=self._tick)
+        self._started = 0.0
+        self._sent = 0
+        self._is_open = False
+
+    def channels(self) -> list[Channel]:
+        return list(CHANNELS)
+
+    @property
+    def rate(self) -> float:
+        return RATE
+
+    @property
+    def running(self) -> bool:
+        return self._timer.isActive()
+
+    @property
+    def is_open(self) -> bool:
+        return self._is_open
+
+    def open(self) -> None:
+        if not self._is_open:
+            self._is_open = True
+            self.opened_changed.emit(True)
+
+    def close(self) -> None:
+        self.stop()
+        if self._is_open:
+            self._is_open = False
+            self.opened_changed.emit(False)
+
+    def start(self) -> None:
+        if self.running:
+            return
+        self.open()
+        self._started = time.perf_counter()
+        self._sent = 0
+        self._timer.start()
+        self.state_changed.emit(True)
+
+    def stop(self) -> None:
+        if not self.running:
+            return
+        self._timer.stop()
+        self.state_changed.emit(False)
+
+    def _tick(self) -> None:
+        """Send the samples that have fallen due since the last block."""
+        due = int((time.perf_counter() - self._started) * RATE) - self._sent
+        if due > MOST_S * RATE:
+            # Skipped rather than made up late: the sample count is the clock,
+            # so the gap is said as a gap and the capture keeps its time.
+            self._sent += due - int(MOST_S * RATE)
+            due = int(MOST_S * RATE)
+        if due <= 0:
+            return
+        self.block.emit(Block(self._sent, RATE, samples(self._sent, due)))
+        self._sent += due