oep-client-python 0.0.4__tar.gz → 0.0.5__tar.gz

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.0.5
+- (EN) USB (python-libusb1) streams close cleanly and at exit: the IN transfers are cancelled and taken back by the event thread before the handle and the context go. A program that ended without closing the link hung at exit, or libusb aborted.
+- (JA) USB（python-libusb1）の stream は、終了時にも片付いて閉じる: IN の転送を取り消し、event thread が取り戻してから handle と context を閉じる。link を閉じずに終わったプログラムが終了で固まったり、libusb が abort したりしていた。
+- (EN) `core.plan_apply` refused as unavailable names what holds the pins when the settings say so (`core.PinsTaken`: another fn's saved plan, a slot).
+- (JA) `core.plan_apply` が unavailable で断られたとき、設定から分かれば何がピンを持っているかを示す（`core.PinsTaken`: 別の fn の保存した plan、スロット）。
+- (EN) Fake probe: a read from the last mark of a kind that is not there starts now, not at the oldest byte (oep-if-common §1.2).
+- (JA) 偽の probe: その kind のマークが無いときの「最後のマークから」の read は、一番古い位置ではなく今から（oep-if-common §1.2）。
+
 ## 0.0.4
 - (EN) Fake serial port: a candidate that is only its 0x00 is not raw after the 200 ms gap (the probe firmware had the same bug: a stray 0x00 reached the target's console).
 - (JA) 偽のシリアルの口: 0x00 だけの候補は、200 ms の後も生のバイトにしない（probe の firmware にも同じバグがあり、target のコンソールに 0x00 が届いていた）。

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.4
+Version: 0.0.5
 Summary: Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe
 Project-URL: Homepage, https://github.com/Open-Embedded-Probe/oep-client-python
 Project-URL: Repository, https://github.com/Open-Embedded-Probe/oep-client-python
@@ -43,7 +43,7 @@ uv run pytest                     # in a checkout
 `oep-client` is another project, so the distribution is named `oep-client-python`.
 
 Releases: run the GitHub Actions workflow Release (workflow_dispatch, version X.Y.Z or X.Y.ZbN). `tools/prepare_release.py`
-sets the version in pyproject.toml and `oep_client.__version__` and turns CHANGELOG.md's Unreleased into that version; after
+sets the version in pyproject.toml, uv.lock and `oep_client.__version__` and turns CHANGELOG.md's Unreleased into that version; after
 the tests and the build it commits, tags, makes the GitHub Release and publishes to PyPI (Trusted Publishing). Record changes
 under Unreleased in CHANGELOG.md, (EN) and (JA).
 

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/README.ja.md

@@ -18,7 +18,7 @@ uv run pytest                                                            # in a
 oep-spec から写す。PyPI の `oep-client` は別のプロジェクトなので、配布名は `oep-client-python`。
 
 リリースは GitHub Actions の Release（workflow_dispatch、version = X.Y.Z か X.Y.ZbN）: `tools/prepare_release.py` が
-pyproject.toml と `oep_client.__version__` を書き換え、CHANGELOG.md の Unreleased をその版にし、試験と build の後に commit と tag、
+pyproject.toml、uv.lock、`oep_client.__version__` を書き換え、CHANGELOG.md の Unreleased をその版にし、試験と build の後に commit と tag、
 GitHub Release、PyPI（Trusted Publishing）へ出す。変更は CHANGELOG.md の Unreleased に (EN) / (JA) で書き足しておく。
 
 ## モジュール（`oep_client`）

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/README.md

@@ -21,7 +21,7 @@ uv run pytest                     # in a checkout
 `oep-client` is another project, so the distribution is named `oep-client-python`.
 
 Releases: run the GitHub Actions workflow Release (workflow_dispatch, version X.Y.Z or X.Y.ZbN). `tools/prepare_release.py`
-sets the version in pyproject.toml and `oep_client.__version__` and turns CHANGELOG.md's Unreleased into that version; after
+sets the version in pyproject.toml, uv.lock and `oep_client.__version__` and turns CHANGELOG.md's Unreleased into that version; after
 the tests and the build it commits, tags, makes the GitHub Release and publishes to PyPI (Trusted Publishing). Record changes
 under Unreleased in CHANGELOG.md, (EN) and (JA).
 

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oep-client-python"
-version = "0.0.4"
+version = "0.0.5"
 description = "Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a fake probe"
 readme = "README.md"
 license = "MIT"

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.4"
+__version__ = "0.0.5"

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/src/oep_client/core.py

@@ -109,7 +109,47 @@ def plan_apply(hst: h.Host, assignments: list[tuple[int, int, int]]) -> None:
     all interfaces accept their roles or nothing changes. The plan is the
     session's resource: kept over an explicit end, released at a lease lapse or a force takeover (oep-core §9)."""
     tlv = b"".join(bytes([TAG_ROLE_ASSIGNMENT, 5]) + struct.pack("<HBH", fn, role, ch) for fn, role, ch in assignments)
-    hst.call(m.CORE_FN, OP_PLAN_APPLY, tlv)
+    try:
+        hst.call(m.CORE_FN, OP_PLAN_APPLY, tlv)
+    except h.Rejected as e:
+        if e.result.detail != m.UNAVAILABLE:
+            raise
+        why = _pin_holders(hst, assignments)
+        if why:
+            raise PinsTaken(e.result, why) from None
+        raise
+
+
+class PinsTaken(h.Rejected):
+    """plan_apply refused (unavailable) and the probe's settings say why: a pin kept by another fn's saved plan or by a
+    slot (oep.probe.config). `holders`: (channel, what holds it)."""
+
+    def __init__(self, result, holders: list[tuple[int, str]]):
+        super().__init__(result)
+        self.holders = holders
+
+    def __str__(self) -> str:
+        return "pins taken: " + "; ".join(f"channel {ch} by {who}" for ch, who in self.holders) + \
+            " (oep config show; oep config remove <probe> plan <fn> frees a saved plan)"
+
+
+def _pin_holders(hst: h.Host, assignments: list[tuple[int, int, int]]) -> list[tuple[int, str]]:
+    """What the settings keep on the channels asked for (best effort: an empty list when there is no oep.probe.config
+    or it cannot be read)."""
+    from . import config
+    try:
+        items = config.ProbeConfig(hst).items()
+    except (LookupError, h.OepError):
+        return []
+    fns = {fn for fn, _, _ in assignments}
+    out = []
+    for fn, role, ch in assignments:
+        for it in items:
+            if isinstance(it, config.Plan) and it.channel == ch and it.fn not in fns:
+                out.append((ch, f"the saved plan of fn {it.fn} (role {it.role})"))
+            elif isinstance(it, config.Slot) and ch in it.pins:
+                out.append((ch, f"slot {it.slot} {it.name}"))
+    return out
 
 
 def plan_release(hst: h.Host, fns: list[int] | tuple[int, ...] = ()) -> None:

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/src/oep_client/endpoint.py

@@ -923,7 +923,7 @@ class Endpoint:
                 pos = s.end
             elif frm == 3:
                 hits = [mk for mk in s.marks if arg == 0 or mk[2] == arg]
-                pos = hits[-1][1] if hits else s.base
+                pos = hits[-1][1] if hits else s.end                 # no such mark: from now (common §1.2)
             else:
                 raise Reject(m.UNSUPPORTED)
             flags = 0

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/src/oep_client/usb_stream.py

@@ -10,6 +10,7 @@ transfer; if its timeout hits first, pyusb raises and the bytes already received
 
 from __future__ import annotations
 
+import atexit
 import threading
 import time
 
@@ -114,15 +115,21 @@ class UsbAsyncStream:
         self.timeout = 0.05
         self._buffer = bytearray()
         self._cond = threading.Condition()
-        self._closed = False
+        self._closed = False           # no more resubmits (close() started)
+        self._stop = False             # the event thread ends (every transfer is back)
         self._transfers = []
+        self._active = 0               # transfers submitted and not yet back for good
         for _ in range(self.DEPTH):
             t = handle.getTransfer()
             t.setBulk(endpoint_in, self.URB_SIZE, callback=self._done, timeout=0)
             t.submit()
             self._transfers.append(t)
+            self._active += 1
         self._events = threading.Thread(target=self._run, daemon=True)
         self._events.start()
+        # Closed at exit too: left to usb1's own finalizers, the context went while the event thread was inside
+        # handleEventsTimeout with transfers out - the process hung at exit or libusb aborted (usbi_mutex_destroy).
+        atexit.register(self.close)
 
     @classmethod
     def open(cls, vid: int, pid: int, serial: str | None = None) -> "UsbAsyncStream":
@@ -158,14 +165,23 @@ class UsbAsyncStream:
                     self._buffer += data
                     self._cond.notify_all()
         if not self._closed and status in (usb1.TRANSFER_COMPLETED, usb1.TRANSFER_TIMED_OUT):
-            transfer.submit()
+            try:
+                transfer.submit()
+                return
+            except usb1.USBError:
+                pass
+        with self._cond:
+            self._active -= 1          # back for good (cancelled, failed, or closing)
+            self._cond.notify_all()
 
     def _run(self) -> None:
-        while not self._closed:
+        while not self._stop:
             try:
                 self.context.handleEventsTimeout(0.1)
             except self._usb1.USBErrorInterrupted:
                 continue
+            except self._usb1.USBError:
+                break
 
     @property
     def in_waiting(self) -> int:
@@ -195,15 +211,27 @@ class UsbAsyncStream:
             self._buffer.clear()
 
     def close(self) -> None:
+        """Cancel the IN transfers and let the event thread take them back before the handle and the context go
+        (closing with transfers still out hung the process or aborted libusb). Safe to call twice (atexit)."""
+        if self._closed:
+            return
         self._closed = True
+        atexit.unregister(self.close)
         for t in self._transfers:
             try:
                 t.cancel()
             except self._usb1.USBError:
                 pass
-        self._events.join(timeout=0.5)
+        deadline = time.monotonic() + 1.0
+        with self._cond:
+            while self._active > 0 and self._events.is_alive() and time.monotonic() < deadline:
+                self._cond.wait(0.05)
+        self._stop = True
+        self._events.join(timeout=1.0)
         try:
             self.handle.releaseInterface(self.interface)
+        except self._usb1.USBError:
+            pass
         finally:
             self.handle.close()
             self.context.close()

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/tests/test_config.py

@@ -97,3 +97,14 @@ def test_slot_takes_the_only_wire_by_default(monkeypatch):
     assert cli.main(["config", "slot", "x", "--name", "v003", "--attach", "at-boot", "--retry", "1"]) == 0
     (slot,) = [i for i in config.ProbeConfig(hst).items() if isinstance(i, config.Slot)]
     assert slot.wire_fn == 1 and slot.pins == (16, 0xFFFF)
+
+
+def test_a_plan_refused_for_a_saved_plan_names_the_holder():
+    import pytest
+    from oep_client import core
+    ep, hst = open_bench()
+    cfg = config.ProbeConfig(hst)
+    cfg.set([config.Plan(5, 1, 20), config.Plan(5, 2, 21)])        # fixture.uart keeps 20 / 21 as a setting
+    with pytest.raises(core.PinsTaken) as e:
+        core.plan_apply(hst, [(4, 1, 21)])                          # gpio wants 21
+    assert e.value.holders == [(21, "the saved plan of fn 5 (role 2)")] and "fn 5" in str(e.value)

{oep_client_python-0.0.4 → oep_client_python-0.0.5}/tests/test_fake_spec.py

@@ -383,3 +383,16 @@ def test_the_closing_0x00_of_a_frame_is_not_raw_after_the_gap():
     port.tick()
     sid = ep.stream_keys[(ep._conn_at(1, p[0]), 2)]
     assert bytes(ep.streams[sid].written) == b""                   # no stray 0x00 at the target
+
+
+def test_read_from_a_last_mark_that_is_not_there_is_from_now():
+    ep, h = bench()
+    p = ep.pairs[1][0]
+    r = h.raw(1, 0x02, bytes([0]) + m.tlv(0x03, struct.pack("<HH", *p), critical=True))
+    uart_fn = 5
+    h.ok(0, m.OP_PLAN_APPLY, m.tlv(0x90, struct.pack("<HBH", uart_fn, 1, 20)) + m.tlv(0x90, struct.pack("<HBH", uart_fn, 2, 21)))
+    h.ok(uart_fn, 0x01, struct.pack("<I", 115200))
+    ep.uart_rx(uart_fn, b"old output")
+    reset = reg.TARGET_CONSOLE.enum["mark_kind"]["reset"]
+    got = h.raw(uart_fn, 0x02, struct.pack("<BQH", 3, reset, 64), session=False).payload
+    assert struct.unpack_from("<Q", got)[0] == 10 and got[9:] == b""   # no reset mark: from now, not the old bytes

oep_client_python-0.0.5/tests/test_usb_stream.py

@@ -0,0 +1,96 @@
+"""UsbAsyncStream closes cleanly: the IN transfers are cancelled and taken back by the event thread before the handle and
+the context go (closing with transfers out hung the process at exit or aborted libusb), and close is hooked to exit."""
+
+import atexit
+import sys
+import threading
+import types
+
+import pytest
+
+
+class FakeUsb1(types.ModuleType):
+    TRANSFER_COMPLETED, TRANSFER_TIMED_OUT, TRANSFER_CANCELLED = 0, 2, 3
+
+    class USBError(Exception):
+        pass
+
+    class USBErrorInterrupted(USBError):
+        pass
+
+
+usb1 = FakeUsb1("usb1")
+
+
+class Transfer:
+    def __init__(self, ctx):
+        self.ctx, self.status, self.out = ctx, None, False
+
+    def setBulk(self, ep, size, callback, timeout):
+        self.callback = callback
+
+    def submit(self):
+        self.out = True
+
+    def cancel(self):
+        self.ctx.pending.append(self)                  # comes back as cancelled on a later event pass, like libusb
+
+    def getStatus(self):
+        return self.status
+
+
+class Context:
+    def __init__(self):
+        self.pending, self.lock, self.closed = [], threading.Lock(), False
+
+    def handleEventsTimeout(self, t):
+        import time
+        time.sleep(0.005)
+        while self.pending:
+            tr = self.pending.pop(0)
+            tr.out, tr.status = False, usb1.TRANSFER_CANCELLED
+            tr.callback(tr)
+
+    def close(self):
+        self.closed = True
+
+
+class Handle:
+    def __init__(self, ctx):
+        self.ctx, self.transfers, self.closed_with_out = ctx, [], None
+
+    def getTransfer(self):
+        t = Transfer(self.ctx)
+        self.transfers.append(t)
+        return t
+
+    def releaseInterface(self, n):
+        pass
+
+    def close(self):
+        self.closed_with_out = sum(t.out for t in self.transfers)
+
+
+@pytest.fixture
+def stream(monkeypatch):
+    monkeypatch.setitem(sys.modules, "usb1", usb1)
+    from oep_client import usb_stream
+    ctx = Context()
+    h = Handle(ctx)
+    s = usb_stream.UsbAsyncStream(ctx, h, 0x81, 0x01, 0)
+    return s, ctx, h
+
+
+def test_close_takes_every_transfer_back_before_the_handle_goes(stream):
+    s, ctx, h = stream
+    s.close()
+    assert h.closed_with_out == 0 and ctx.closed and not s._events.is_alive()
+    s.close()                                          # twice (atexit after an explicit close): nothing more
+
+
+def test_close_is_hooked_to_exit(stream, monkeypatch):
+    s, ctx, h = stream
+    calls = []
+    monkeypatch.setattr(atexit, "unregister", lambda f: calls.append(f))
+    s.close()
+    assert calls == [s.close]                          # it was registered, and an explicit close takes it off