scietex.hal.spi 0.1.0__py3-none-any.whl

scietex/hal/spi/__init__.py

@@ -0,0 +1,61 @@
+"""SPI bus transport backends for scietex.hal devices."""
+
+from typing import TYPE_CHECKING, Any
+
+from .base import (
+    I2cTransport,
+    SpiTransport,
+    TransportClosed,
+    TransportError,
+    is_spi_transport,
+)
+from .fake import FakeSpiTransport
+from .gpiozero_helpers import fix_gpiozero_dual_cs_spi
+from .selection import (
+    GPIOZERO_PIN_ARGS,
+    GPIOZERO_SPI_ARGS,
+    build_default_transport,
+)
+from .spidev_spi import SpiDevTransport
+from .version import __version__ as __version__
+
+if TYPE_CHECKING:
+    from .gpiozero_spi import GpiozeroSpiTransport  # noqa: F401
+
+#: Names resolved lazily by `__getattr__`; kept out of `__all__` so a star
+#: import works on a core install without the optional gpiozero package.
+_LAZY_ATTRIBUTES = ("GpiozeroSpiTransport",)
+
+__all__ = [
+    "FakeSpiTransport",
+    "GPIOZERO_PIN_ARGS",
+    "GPIOZERO_SPI_ARGS",
+    "I2cTransport",
+    "SpiDevTransport",
+    "SpiTransport",
+    "TransportClosed",
+    "TransportError",
+    "build_default_transport",
+    "fix_gpiozero_dual_cs_spi",
+    "is_spi_transport",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve the optional gpiozero transport on first access."""
+    if name == "GpiozeroSpiTransport":
+        try:
+            from .gpiozero_spi import GpiozeroSpiTransport  # noqa: PLC0415
+        except ImportError as exc:
+            raise AttributeError(
+                "GpiozeroSpiTransport requires the optional 'gpiozero' package. "
+                "Install it with: pip install 'scietex.hal.spi[gpiozero]'"
+            ) from exc
+
+        return GpiozeroSpiTransport
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """List the module attributes, including lazily resolved names."""
+    return sorted(set(__all__) | set(globals()) | set(_LAZY_ATTRIBUTES))

scietex/hal/spi/base.py

@@ -0,0 +1,72 @@
+"""Transport protocols and exceptions shared by all bus backends."""
+
+from collections.abc import Sequence
+from typing import Protocol, runtime_checkable
+
+
+class TransportError(OSError):
+    """Raised when a bus transaction fails.
+
+    Subclasses `OSError` so callers that already handle gpiozero or spidev I/O
+    errors keep catching transport failures without changes.
+    """
+
+
+class TransportClosed(TransportError):
+    """Raised when a transaction is attempted after close()."""
+
+
+@runtime_checkable
+class SpiTransport(Protocol):
+    """Full-duplex SPI backend.
+
+    Structurally satisfied by any non-class object with callable `transfer`
+    and `close` methods. Use `is_spi_transport` for the check: it rejects
+    class objects, which `isinstance` against this protocol accepts.
+    """
+
+    def transfer(self, tx: Sequence[int]) -> list[int]:
+        """Transfer one frame and return the received words."""
+        ...
+
+    def close(self) -> None:
+        """Release the bus handle."""
+        ...
+
+
+@runtime_checkable
+class I2cTransport(Protocol):
+    """I2C backend protocol for future chips.
+
+    No implementation or device uses it yet; it keeps the transport surface
+    consistent for chips with an I2C interface.
+    """
+
+    def write(self, data: Sequence[int]) -> None:
+        """Write one frame."""
+        ...
+
+    def read(self, nbytes: int) -> bytes:
+        """Read `nbytes` bytes."""
+        ...
+
+    def write_read(self, tx: Sequence[int], nbytes: int) -> bytes:
+        """Write a frame, then read `nbytes` bytes."""
+        ...
+
+    def close(self) -> None:
+        """Release the bus handle."""
+        ...
+
+
+def is_spi_transport(obj: object) -> bool:
+    """Check whether `obj` structurally satisfies `SpiTransport`.
+
+    Requires callable `transfer` and `close` attributes and rejects class
+    objects, so a transport class itself does not count.
+    """
+    if isinstance(obj, type):
+        return False
+    return callable(getattr(obj, "transfer", None)) and callable(
+        getattr(obj, "close", None)
+    )

scietex/hal/spi/fake.py

@@ -0,0 +1,96 @@
+"""Scripted SPI transport for tests."""
+
+from collections.abc import Sequence
+
+from .base import TransportClosed, TransportError
+
+
+class FakeSpiTransport:
+    """SPI transport that replays scripted response frames.
+
+    Responses are consumed FIFO. `default` is returned once the queue is
+    empty; with `strict=False` an empty queue yields zero-filled frames
+    instead of an error. Request words are validated to ints in 0..255.
+    Frames are copied on the way in and out so that mutating a caller's list
+    cannot change a scripted response or a recorded call.
+    """
+
+    def __init__(
+        self,
+        responses: list[list[int]] | None = None,
+        default: list[int] | None = None,
+        strict: bool = True,
+    ) -> None:
+        """
+        Build a scripted transport.
+
+        :param responses: Response frames consumed FIFO; each frame must have
+            the same length as the request that consumes it.
+        :param default: Frame returned once `responses` is exhausted; when
+            omitted, an exhausted queue follows `strict`.
+        :param strict: When True an empty queue with no `default` raises
+            `TransportError`; when False it returns a zero-filled frame.
+        """
+        self._responses = (
+            [list(frame) for frame in responses] if responses is not None else []
+        )
+        self._default = list(default) if default is not None else None
+        self._strict = strict
+        self.calls: list[list[int]] = []
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        """Return True once the transport has been closed."""
+        return self._closed
+
+    def queue(self, *responses: list[int]) -> None:
+        """Append scripted response frames."""
+        self._responses.extend(list(frame) for frame in responses)
+
+    def transfer(self, tx: Sequence[int]) -> list[int]:
+        """Return the next scripted frame for `tx`.
+
+        Request words must be ints in 0..255; a malformed word raises
+        `ValueError` before the call is recorded. A frame that fails validation
+        stays at the head of the queue and is not recorded as a call, so the
+        caller can retry with a matching request.
+
+        :param tx: Request frame.
+        :return: Response frame of the same length.
+        :raises TransportClosed: If the transport is closed.
+        :raises ValueError: If a request word is not an int in 0..255.
+        :raises TransportError: If no response is available in strict mode or
+            the scripted response length does not match the request.
+        """
+        if self._closed:
+            raise TransportClosed("FakeSpiTransport is closed")
+        frame = list(tx)
+        for word in frame:
+            if not isinstance(word, int) or not 0 <= word <= 0xFF:
+                raise ValueError(
+                    f"SPI frame words must be ints in the range 0..255, got {word!r}"
+                )
+        if self._responses:
+            rx = list(self._responses[0])
+            from_queue = True
+        elif self._default is not None:
+            rx = list(self._default)
+            from_queue = False
+        elif self._strict:
+            raise TransportError("FakeSpiTransport has no scripted response")
+        else:
+            self.calls.append(frame)
+            return [0] * len(frame)
+        if len(rx) != len(frame):
+            raise TransportError(
+                f"Response length {len(rx)} does not match request length {len(frame)}"
+            )
+        if from_queue:
+            self._responses.pop(0)
+        self.calls.append(frame)
+        return rx
+
+    def close(self) -> None:
+        """Close the transport. Repeated calls have no effect."""
+        self._closed = True

scietex/hal/spi/gpiozero_helpers.py

@@ -0,0 +1,162 @@
+"""gpiozero patch that lets two hardware-SPI devices share one SPI port.
+
+gpiozero refuses to create a second hardware-SPI device on a port that is
+already in use, even when the two devices use different chip-select lines (as
+the MCP4xxx dual-potentiometer boards do). `fix_gpiozero_dual_cs_spi` replaces
+`Device.pin_factory` with a factory whose SPI classes treat only a same port and
+same device pair as a conflict. Without the Raspberry Pi pin backend the
+function is a no-op.
+"""
+
+import logging
+import os
+from typing import Any
+
+__all__ = ["fix_gpiozero_dual_cs_spi"]
+
+_LOGGER = logging.getLogger(__name__)
+
+# The factory class installed by the last successful call. It lives at module
+# scope so a later call can recognize its own factory instead of stacking
+# another subclass on top of it.
+_PATCHED_FACTORY_CLS: type | None = None
+
+
+def _fixed_factory_for(base_factory_cls: type) -> type:
+    """
+    Build a dual-CS factory subclass for `base_factory_cls`.
+
+    The base class is the active gpiozero factory type, so the patch keeps the
+    pin backend gpiozero already selected instead of forcing RPi.GPIO.
+
+    :param base_factory_cls: Local pin factory type to subclass.
+    :return: Factory class whose hardware-SPI classes only conflict on the
+        same port and device pair.
+    """
+    from gpiozero.pins.local import (  # noqa: PLC0415
+        LocalPiHardwareSPI,
+        LocalPiHardwareSPIShared,
+    )
+
+    class LocalPiHardwareSPIFixed(LocalPiHardwareSPI):
+        """Hardware SPI that conflicts only on the same port and device."""
+
+        def _conflicts_with(self, other):
+            return not (
+                isinstance(other, LocalPiHardwareSPI)
+                and (self._port, self._device) != (other._port, other._device)
+            )
+
+        @property
+        def value(self):
+            """SPI pins carry no device state, so the value is not implemented."""
+            raise NotImplementedError
+
+    class LocalPiHardwareSPISharedFixed(LocalPiHardwareSPIShared):
+        """Shared hardware SPI with the same port/device conflict rule."""
+
+        def _conflicts_with(self, other):
+            return not (
+                isinstance(other, LocalPiHardwareSPI)
+                and (self._port, self._device) != (other._port, other._device)
+            )
+
+        @property
+        def value(self):
+            """SPI pins carry no device state, so the value is not implemented."""
+            raise NotImplementedError
+
+    def _get_spi_class(self, shared, hardware):
+        """
+        Return the fixed SPI class for hardware SPI.
+
+        :param shared: Flag for shared usage of the SPI port.
+        :param hardware: Flag for hardware SPI usage.
+        :return: Fixed SPI class for hardware SPI, the parent class otherwise.
+        """
+        if hardware:
+            if shared:
+                return LocalPiHardwareSPISharedFixed
+            return LocalPiHardwareSPIFixed
+        # `base_factory_cls` is typed as plain `type` because gpiozero is an
+        # optional dependency and its factory protocol cannot be imported for
+        # static analysis.
+        factory: Any = base_factory_cls
+        return factory._get_spi_class(self, shared, hardware)
+
+    # Built with type() rather than a class statement because the base class is
+    # only known at runtime; a class statement over a variable base prevents
+    # static analysis of the MRO.
+    return type(
+        "FixedFactory",
+        (base_factory_cls,),
+        {
+            "__doc__": "Active local factory whose hardware SPI can share a port.",
+            "_get_spi_class": _get_spi_class,
+        },
+    )
+
+
+def fix_gpiozero_dual_cs_spi() -> None:
+    """
+    Patch gpiozero so two hardware-SPI devices can share one SPI port.
+
+    Installs a subclass of the active `LocalPiFactory` into
+    `Device.pin_factory`. Its SPI classes report a conflict only when both the
+    port and the device (chip select) match, instead of whenever the port
+    matches. Based on https://github.com/gpiozero/gpiozero/issues/1015
+
+    The patch applies only to gpiozero's own default `RPiGPIOFactory`. A
+    factory chosen explicitly by the application is left untouched, and the
+    function returns without patching when `GPIOZERO_PIN_FACTORY` is set
+    because gpiozero honors that variable itself. A second call recognizes the
+    factory installed by the first call and is a no-op.
+
+    The gpiozero imports are deferred so that importing this module never
+    imports gpiozero; on hosts without gpiozero or its Raspberry Pi pin backend
+    the call is a no-op.
+
+    :return: None.
+    """
+    global _PATCHED_FACTORY_CLS
+
+    if "GPIOZERO_PIN_FACTORY" in os.environ:
+        return
+
+    try:
+        # Imported lazily so the core install needs no gpiozero package.
+        from gpiozero import Device  # noqa: PLC0415
+        from gpiozero.pins.rpigpio import RPiGPIOFactory  # noqa: PLC0415
+    except Exception as exc:  # gpiozero or its pin backend is unavailable
+        _LOGGER.debug("gpiozero dual-CS patch skipped: %s", exc)
+        return
+
+    current_factory = Device.pin_factory
+    if current_factory is None:
+        try:
+            default_factory = Device._default_pin_factory()
+        except Exception:  # any backend failure means no patch
+            _LOGGER.debug(
+                "gpiozero could not choose a default pin factory", exc_info=True
+            )
+            return
+        base_factory_cls = type(default_factory)
+        if base_factory_cls is not RPiGPIOFactory:
+            _LOGGER.debug(
+                "gpiozero default factory %s is not supported; not patching",
+                base_factory_cls.__name__,
+            )
+            return
+    else:
+        base_factory_cls = type(current_factory)
+        if base_factory_cls is _PATCHED_FACTORY_CLS:
+            return
+        # Any factory the application selected is a real choice, so keep it.
+        if base_factory_cls is not RPiGPIOFactory:
+            return
+
+    if _PATCHED_FACTORY_CLS is None or not issubclass(
+        _PATCHED_FACTORY_CLS, base_factory_cls
+    ):
+        _PATCHED_FACTORY_CLS = _fixed_factory_for(base_factory_cls)
+    Device.pin_factory = _PATCHED_FACTORY_CLS()

scietex/hal/spi/gpiozero_spi.py

@@ -0,0 +1,122 @@
+"""SPI transport backed by gpiozero's hardware SPI device."""
+
+from collections.abc import Sequence
+from typing import Any
+
+from gpiozero import SPIDevice
+from gpiozero.exc import DeviceClosed
+
+from .base import TransportClosed, TransportError
+from .gpiozero_helpers import fix_gpiozero_dual_cs_spi
+from .selection import GPIOZERO_SPI_ARGS
+
+
+class _GpiozeroSpiHandle(SPIDevice):
+    """Private SPIDevice used only to obtain a shared gpiozero SPI object."""
+
+    def __init__(self, **spi_args) -> None:
+        super().__init__(shared=True, **spi_args)
+
+    @property
+    def raw(self) -> Any:
+        """Return the gpiozero SPI object held by the device."""
+        return self._spi
+
+    @property
+    def value(self):
+        """A raw SPI handle exposes no digital value."""
+        raise NotImplementedError
+
+
+class GpiozeroSpiTransport:
+    """SPI transport over a gpiozero SPI interface.
+
+    With no `spi` argument the transport builds a private gpiozero
+    `SPIDevice` from the same keyword arguments the legacy `MCP4xxx`
+    constructor accepted (`port`, `device`, `clock_pin`, `mosi_pin`,
+    `miso_pin`, `select_pin`). `shared=True` is kept so that several
+    devices can share one hardware SPI port.
+
+    Ownership follows construction: a transport that built its own handle
+    closes it. A transport wrapping a caller-supplied `spi=` never closes it
+    and does not join gpiozero's shared reference count, so the supplied
+    handle's owner must outlive the wrapper. Once the owner closes the handle,
+    this transport's transfers raise `TransportClosed`.
+    """
+
+    _SPI_ARGS = GPIOZERO_SPI_ARGS
+
+    def __init__(self, spi: Any = None, **spi_args) -> None:
+        """
+        Wrap an existing gpiozero SPI object or build a shared one.
+
+        :param spi: Existing gpiozero SPI object to wrap. The caller keeps
+            ownership and must keep it open for the lifetime of this transport;
+            when None a private `SPIDevice` is built from `spi_args` and owned
+            by this transport.
+        :param spi_args: gpiozero `SPIDevice` keywords (`port`, `device`,
+            `clock_pin`, `mosi_pin`, `miso_pin`, `select_pin`).
+        """
+        self._closed = False
+        self._owns_raw = spi is None
+        self._handle = None
+        if spi is None:
+            fix_gpiozero_dual_cs_spi()
+            self._handle = _GpiozeroSpiHandle(**spi_args)
+            self._raw = self._handle.raw
+        else:
+            self._raw = spi
+
+    @property
+    def raw(self) -> Any:
+        """Return the underlying gpiozero SPI object."""
+        return self._raw
+
+    @property
+    def closed(self) -> bool:
+        """Return True once close() has completed successfully."""
+        return self._closed
+
+    def transfer(self, tx: Sequence[int]) -> list[int]:
+        """Transfer one frame and validate the response length.
+
+        :param tx: Request frame.
+        :return: Response frame of the same length.
+        :raises TransportClosed: If this transport is closed or the owner of a
+            caller-supplied SPI handle has closed it.
+        :raises TransportError: If gpiozero returns the wrong number of words.
+        """
+        if self._closed:
+            raise TransportClosed("GpiozeroSpiTransport is closed")
+        raw_closed = getattr(self._raw, "closed", False)
+        if isinstance(raw_closed, bool) and raw_closed:
+            raise TransportClosed(
+                "The underlying gpiozero SPI handle is closed; its owner must "
+                "outlive this wrapper"
+            )
+        frame = list(tx)
+        try:
+            rx = list(self._raw.transfer(frame))
+        except DeviceClosed as exc:
+            raise TransportClosed(
+                "The underlying gpiozero SPI handle was closed by its owner"
+            ) from exc
+        if len(rx) != len(frame):
+            raise TransportError(
+                f"gpiozero returned {len(rx)} words for a {len(frame)}-word request"
+            )
+        return rx
+
+    def close(self) -> None:
+        """Close an owned SPI handle.
+
+        A wrapper around a caller-supplied handle only marks itself closed and
+        leaves that handle untouched; its owner must close it. Repeated calls
+        after a successful close have no effect; a failed close of an owned
+        handle leaves the transport open and retryable.
+        """
+        if self._closed:
+            return
+        if self._owns_raw and self._handle is not None:
+            self._handle.close()
+        self._closed = True

scietex/hal/spi/selection.py

@@ -0,0 +1,82 @@
+"""Default SPI backend selection shared by the device constructors."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import SpiTransport
+
+
+#: Keyword names accepted by both the legacy constructor and the gpiozero
+#: backend, in the order the transport forwards them.
+GPIOZERO_SPI_ARGS: tuple[str, ...] = (
+    "port",
+    "device",
+    "clock_pin",
+    "mosi_pin",
+    "miso_pin",
+    "select_pin",
+)
+
+#: Pin keywords that select the gpiozero backend; `port` and `device` alone
+#: are also valid for the spidev backend.
+GPIOZERO_PIN_ARGS: tuple[str, ...] = (
+    "clock_pin",
+    "mosi_pin",
+    "miso_pin",
+    "select_pin",
+)
+
+
+def build_default_transport(  # noqa: PLR0913
+    *,
+    port: int | None = None,
+    device: int | None = None,
+    clock_pin: int | None = None,
+    mosi_pin: int | None = None,
+    miso_pin: int | None = None,
+    select_pin: int | None = None,
+) -> "SpiTransport":
+    """
+    Build the default SPI transport from the legacy keyword arguments.
+
+    Pin keywords select the gpiozero backend and require the optional
+    ``gpiozero`` package. Without pin keywords the spidev backend is used;
+    its ``spidev`` package is imported lazily when the transport is built.
+
+    :param port: SPI port (gpiozero) or bus number (spidev).
+    :param device: SPI device number (chip select).
+    :param clock_pin: GPIO pin used as SPI clock.
+    :param mosi_pin: GPIO pin used as SPI MOSI.
+    :param miso_pin: GPIO pin used as SPI MISO.
+    :param select_pin: GPIO pin used as SPI chip select.
+    :return: SPI transport selected by the supplied keywords.
+    :raises ImportError: If pin keywords are given and gpiozero is missing.
+    """
+    supplied = {
+        "port": port,
+        "device": device,
+        "clock_pin": clock_pin,
+        "mosi_pin": mosi_pin,
+        "miso_pin": miso_pin,
+        "select_pin": select_pin,
+    }
+    if any(supplied[name] is not None for name in GPIOZERO_PIN_ARGS):
+        try:
+            # Imported lazily so the core install needs no gpiozero package.
+            from .gpiozero_spi import GpiozeroSpiTransport  # noqa: PLC0415
+        except ImportError as exc:
+            raise ImportError(
+                "The gpiozero pin keywords require the optional 'gpiozero' "
+                "package. Install it with: pip install "
+                "'scietex.hal.spi[gpiozero]'"
+            ) from exc
+        spi_args = {
+            name: supplied[name]
+            for name in GPIOZERO_SPI_ARGS
+            if supplied[name] is not None
+        }
+        return GpiozeroSpiTransport(**spi_args)
+    # Imported lazily so the core install needs no spidev package.
+    from .spidev_spi import SpiDevTransport  # noqa: PLC0415
+
+    return SpiDevTransport(bus=port or 0, device=device or 0)

scietex/hal/spi/spidev_spi.py

@@ -0,0 +1,114 @@
+"""SPI transport backed by the Linux spidev device interface."""
+
+import contextlib
+from collections.abc import Sequence
+from typing import Any
+
+from .base import TransportClosed, TransportError
+
+
+def _load_spidev():
+    """Import and return spidev.SpiDev, raising an actionable error if missing."""
+    try:
+        # Imported lazily so the core install needs no spidev package.
+        from spidev import SpiDev  # noqa: PLC0415 - kept lazy so spidev stays optional
+    except ImportError as exc:
+        raise ImportError(
+            "SpiDevTransport requires the optional 'spidev' package. "
+            "Install it with: pip install 'scietex.hal.spi[spi]'"
+        ) from exc
+    return SpiDev
+
+
+class SpiDevTransport:
+    """SPI transport over /dev/spidev<bus>.<device>.
+
+    Linux only. Requires kernel SPI (`dtparam=spi=on` in
+    /boot/firmware/config.txt, or the older /boot/config.txt), the device
+    node to exist, and read access for the current user (member of the
+    `gpio` group, or root).
+
+    Transfers use `xfer2`, which keeps CS asserted for the whole frame;
+    `xfer` would deassert CS between 8-bit words and break the 16-bit
+    MCP4xxx command+data words.
+    """
+
+    # One argument per spidev setting; the tuning surface is deliberately explicit.
+    def __init__(  # noqa: PLR0913, PLR0917
+        self,
+        bus: int = 0,
+        device: int = 0,
+        max_speed_hz: int = 500_000,
+        mode: int = 0,
+        bits_per_word: int = 8,
+        lsbfirst: bool = False,
+    ) -> None:
+        """
+        Open and configure a spidev device.
+
+        The settings are applied as ioctls on open. If any of them is
+        rejected, the handle is closed before `TransportError` is raised with
+        the original error as its cause.
+
+        :param bus: SPI bus number (`/dev/spidev<bus>.<device>`).
+        :param device: Chip-select number on the bus.
+        :param max_speed_hz: Clock frequency in Hz.
+        :param mode: SPI mode (clock polarity and phase).
+        :param bits_per_word: Word size in bits.
+        :param lsbfirst: Send the least-significant bit first when True.
+        :raises TransportError: If the device cannot be opened or configured.
+        :raises ImportError: If the optional `spidev` package is missing.
+        """
+        spidev = _load_spidev()
+        self._spi = spidev()
+        self._closed = False
+        try:
+            self._spi.open(bus, device)
+            self._spi.max_speed_hz = max_speed_hz
+            self._spi.mode = mode
+            self._spi.bits_per_word = bits_per_word
+            self._spi.lsbfirst = lsbfirst
+            self._spi.cshigh = False
+        except OSError as exc:
+            with contextlib.suppress(OSError):
+                # The original open/configuration error is the actionable one.
+                self._spi.close()
+            raise TransportError(
+                f"Failed to open or configure /dev/spidev{bus}.{device}: {exc}. "
+                "Ensure SPI is enabled (dtparam=spi=on) and that the current "
+                "user is in the 'gpio' group; the provided udev rule grants "
+                "the device to that group."
+            ) from exc
+
+    @property
+    def raw(self) -> Any:
+        """Return the underlying spidev.SpiDev object."""
+        return self._spi
+
+    @property
+    def closed(self) -> bool:
+        """Return True once close() has completed successfully."""
+        return self._closed
+
+    def transfer(self, tx: Sequence[int]) -> list[int]:
+        """Transfer one frame with CS held asserted for its full length."""
+        if self._closed:
+            raise TransportClosed("SpiDevTransport is closed")
+        frame = list(tx)
+        rx = list(self._spi.xfer2(frame))
+        if len(rx) != len(frame):
+            raise TransportError(
+                f"spidev returned {len(rx)} words for a {len(frame)}-word request"
+            )
+        return rx
+
+    def close(self) -> None:
+        """Close the device handle.
+
+        Repeated calls after a successful close have no effect; a failed close
+        leaves the transport open and retryable.
+        """
+        if self._closed:
+            return
+        self._spi.close()
+        self._closed = True

scietex/hal/spi/version.py

@@ -0,0 +1,8 @@
+"""
+Module containing the package version information.
+
+Attributes:
+    __version__ (str): The current version of the package.
+"""
+
+__version__ = "0.1.0"

scietex_hal_spi-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: scietex.hal.spi
+Version: 0.1.0
+Summary: SPI transport backends for scietex.hal devices
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Anton Bondarenko
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/bond-anton/scietex.hal.spi
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.hal.spi/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: spi
+Requires-Dist: spidev>=3.6; extra == "spi"
+Provides-Extra: gpiozero
+Requires-Dist: gpiozero>=1.6.2; extra == "gpiozero"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff==0.17.4; extra == "lint"
+Requires-Dist: ty==0.0.99; extra == "lint"
+Provides-Extra: dev
+Requires-Dist: tox>=4.46.0; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: spidev>=3.6; extra == "dev"
+Requires-Dist: gpiozero>=1.6.2; extra == "dev"
+Dynamic: license-file
+
+# scietex.hal.spi
+
+SPI transport backends shared by the `scietex.hal.*` device distributions.
+
+A transport is the narrow seam between a device driver and the bus. Devices
+send whole frames through `transfer()` and release the bus with `close()`, so
+the same driver works over `spidev`, over gpiozero's hardware SPI, or over a
+scripted fake in tests. The package ships no device code and has no runtime
+dependencies: the optional backends are imported only when they are used.
+
+## The protocol
+
+```python
+class SpiTransport(Protocol):
+    def transfer(self, tx: Sequence[int]) -> list[int]: ...
+    def close(self) -> None: ...
+```
+
+* `transfer(tx)` sends one frame of words in `0..255` and returns the received
+  words in the same order.
+* `close()` releases the bus handle; repeated calls have no effect. If the
+  underlying close fails, the transport stays open and `close()` can be
+  retried.
+* `closed` is `True` once `close()` has run. For a transport that wraps a
+  caller-supplied handle, it reports that the transport itself is closed, not
+  that the shared bus was closed.
+
+Any object with callable `transfer` and `close` methods is accepted. Use
+`is_spi_transport(obj)` for the check: unlike `isinstance(obj, SpiTransport)`,
+it rejects class objects. Use `SpiTransport` for typing only.
+
+Failures raise `TransportError`, which subclasses `OSError` so callers that
+already handle spidev or gpiozero I/O errors keep working. A transaction
+attempted after close raises `TransportClosed`, a `TransportError` subclass.
+
+## Backends
+
+| Transport | Install | Notes |
+| --- | --- | --- |
+| `SpiDevTransport` | `pip install 'scietex.hal.spi[spi]'` | Default. Opens `/dev/spidev<bus>.<device>` through `spidev`, Linux only. |
+| `GpiozeroSpiTransport` | `pip install 'scietex.hal.spi[gpiozero]'` | Wraps a gpiozero hardware SPI object. Resolved lazily as `scietex.hal.spi.GpiozeroSpiTransport`. |
+| `FakeSpiTransport` | none | In-memory backend with scripted responses, for tests without hardware. |
+
+```python
+from scietex.hal.spi import SpiDevTransport
+
+transport = SpiDevTransport(bus=0, device=0, max_speed_hz=500_000)
+transport.transfer([0x00, 43])
+transport.close()
+```
+
+`SpiDevTransport` transfers with `xfer2`, which keeps chip select asserted for
+the whole frame; `xfer` would deassert it between 8-bit words.
+
+`GpiozeroSpiTransport` builds a private shared gpiozero `SPIDevice` by default,
+or wraps one supplied with `spi=`. On a Raspberry Pi it also patches gpiozero so
+two hardware-SPI devices can share one port when they use different chip-select
+lines (`fix_gpiozero_dual_cs_spi`, also exported for callers that build their
+own gpiozero devices). Without the RPi pin backend the patch is a no-op.
+
+A bare install ships no hardware backend; constructing one raises `ImportError`
+naming the extra to install.
+
+## Default selection
+
+`build_default_transport` maps the legacy device keywords onto a backend:
+
+| Keyword | `SpiDevTransport` | `GpiozeroSpiTransport` |
+| --- | --- | --- |
+| `port` | `bus` | `port` |
+| `device` | `device` | `device` |
+| `clock_pin`, `mosi_pin`, `miso_pin`, `select_pin` | selects the gpiozero backend | forwarded as-is |
+
+```python
+from scietex.hal.spi import build_default_transport
+
+build_default_transport(port=0, device=1)  # SpiDevTransport(bus=0, device=1)
+build_default_transport(clock_pin=11, mosi_pin=10)  # GpiozeroSpiTransport(...)
+```
+
+Any pin keyword selects the gpiozero backend and requires the `gpiozero`
+extra; without pin keywords the spidev backend is built with `port or 0` and
+`device or 0`. `port` and `device` are accepted by both backends and are simply
+forwarded.
+
+The selector takes backend keywords only. Conflict rejection — passing backend
+keywords together with `transport=` or `spi=` — is the responsibility of each
+device constructor, which owns that argument surface; the selector itself raises
+`TypeError` when given a `transport=` keyword.
+
+## Ownership
+
+Create one transport per device; all channels of a device share it. The device's
+`close()` delegates to its transport.
+
+* `SpiDevTransport` always owns and closes its spidev handle.
+* `GpiozeroSpiTransport` closes only a handle it built. When it wraps a
+  caller-supplied `spi=` object, `close()` marks the transport closed but leaves
+  the shared bus open for its other users; the supplied handle's owner must
+  outlive the wrapper and close it. Once that owner closes the handle, transfers
+  through the wrapper raise `TransportClosed`.
+* `FakeSpiTransport` only flips its `closed` flag.
+
+## Linux permissions
+
+`SpiDevTransport` needs the kernel SPI device node and permission to open it.
+Enable kernel SPI first, for example with `dtparam=spi=on` in
+`/boot/firmware/config.txt` on current Raspberry Pi OS (the older path is
+`/boot/config.txt`).
+
+If the node exists but opening fails, add a udev rule. The development setup for
+these packages uses the `gpio` group; adjust the group to match your system::
+
+    SUBSYSTEM=="spidev", GROUP="gpio", MODE="0660"
+
+Install the rule under `/etc/udev/rules.d/`, reload the rules, and reconnect the
+device. The user running the process must be a member of the group named in the
+rule; on Fedora setups that group is `gpio`, because no `spi` group exists.
+
+## License
+
+This project is licensed under the **MIT License** - see the LICENSE file for details.

scietex_hal_spi-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+scietex/hal/spi/__init__.py,sha256=2xw56csGDt3Sn0r4Ef2_3y_Dol01RNGTIZ9WNLJgJL8,1828
+scietex/hal/spi/base.py,sha256=VWouwaOzr_JrNGv3iqC5iwMb10KzAxN_qVa0tc6Fh3U,2048
+scietex/hal/spi/fake.py,sha256=kXhtW1DTn41s0rDg4joyXCinh5_6T5xPa1HXti-MGBU,3731
+scietex/hal/spi/gpiozero_helpers.py,sha256=zK8_qzg-Rlw44LCvKj6Tg7TqnfAX3BkwJ_Y6epriqZg,6191
+scietex/hal/spi/gpiozero_spi.py,sha256=cZ3W-TtuDlRzrT_pBORQJ5-qZ3g0GtAES5FDyR6eCfs,4514
+scietex/hal/spi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scietex/hal/spi/selection.py,sha256=7PuZzq-HutjqUfQ9Ch8f6q-f-KwEvrmO4ZZAjGpODlM,2773
+scietex/hal/spi/spidev_spi.py,sha256=WL_mTk7tbPGG-ew33mLfF1RYzk5PSS6pw7_12x51bS8,4213
+scietex/hal/spi/version.py,sha256=-6LRwSS3coyMIQkeofZjGTMXkVG7dm2gwquyq8O_vF0,154
+scietex_hal_spi-0.1.0.dist-info/licenses/LICENSE,sha256=Kv8K8tNh4XWlpCNncypg7EhUWm4drfJp0zCGNsrp6So,1072
+scietex_hal_spi-0.1.0.dist-info/METADATA,sha256=2pN8lUA03ypAw17Fvkdzpn2c8EtTKvyJxqvo-lZmOpU,7800
+scietex_hal_spi-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+scietex_hal_spi-0.1.0.dist-info/top_level.txt,sha256=AyNTe2f94XrlwxyUGMuitoEj6mqEacwNkt8nU47GjvI,8
+scietex_hal_spi-0.1.0.dist-info/RECORD,,

scietex_hal_spi-0.1.0.dist-info/WHEEL

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

scietex_hal_spi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Bondarenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scietex_hal_spi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scietex