oep-client-python 0.0.42__tar.gz → 0.0.43__tar.gz

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.0.43
+- (EN) Added: `Host.open`, `Host.take` and `core.take` take `extensions` - named extensions (a name, or (name, data))
+  carried on the open after the owner, sent critical, so a probe that does not know one refuses it (`Unsupported`, its
+  `.tag` the named extension's with bit 7) instead of ignoring it. A broker's sharing is asked this way (oep-spec host
+  guide §7; ch32rv's `io.github.ch32-riscv-ug.share`).
+- (JA) 追加: `Host.open`、`Host.take`、`core.take` に `extensions`。名前つき拡張（名前か (名前, data)）を owner の後ろに critical で
+  付ける。知らない probe は無視せずに断る（`Unsupported`、`.tag` は bit 7 付きの名前つき拡張の tag）。broker の相乗りはこれで
+  頼む（oep-spec host ガイド §7。ch32rv の `io.github.ch32-riscv-ug.share`）。
+- (EN) Fixed: `oep-conformance` stopped before any check against oep-spec 364827b ("checker migration required"): the
+  checkers' reviewed-document pins were still oep-spec 02c08c9's. They are raised to 364827b (core §2.3 is checked by
+  the core owner case; the debug document's change is the settings' names, which the pinned checkers do not use).
+  `tools/sync_registry.sh` now records the spec documents' digests (tests/spec/DOCS_SHA256), and a test fails when a
+  sync leaves a pin behind.
+- (JA) 修正: `oep-conformance` が oep-spec 364827b に対して、検査の前に止まっていた（「checker migration required」）。検査が
+  レビュー済みとして固定する文書の hash が、oep-spec 02c08c9 のままだった。364827b に上げた（core §2.3 は core の owner の
+  確かめが見る。debug の文書の変更は設定の項目名で、固定している検査は使わない）。`tools/sync_registry.sh` は仕様の文書の
+  hash も記録し（tests/spec/DOCS_SHA256）、写したのに固定が古いままなら試験が落ちる。
+
 ## 0.0.42
 - (EN) Changed (breaking): follows oep-spec 364827b (core §2.3) - a request with a known non-repeating TLV given twice
   is malformed. The virtual bench refuses it; the conformance checkers and their models check that refusal in place of

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oep-client-python
-Version: 0.0.42
+Version: 0.0.43
 Summary: Open Embedded Probe (OEP) v1 host: serial / USB / TCP transports, the session rules, the standard interfaces, and a virtual bench
 Project-URL: Homepage, https://github.com/Open-Embedded-Probe/oep-client-python
 Project-URL: Repository, https://github.com/Open-Embedded-Probe/oep-client-python

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/pyproject.toml

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

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.42"
+__version__ = "0.0.43"

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/conformance/__init__.py

@@ -144,7 +144,7 @@ def checker_sources_sha256():
             for name in CHECKER_SOURCES}
 
 
-REVIEWED_CORE_SHA256 = 'd63f99f1809146ad41f1643526c81417b366d7a9d85af3845daee6654a229a14'   # oep-spec 02c08c9 docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = '699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e'   # oep-spec 364827b docs/oep-core.ja.md
 
 
 def require_reviewed_contract(registry, spec=None):

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/conformance/core_smoke.py

@@ -8,7 +8,7 @@ import struct
 from . import ops, require, tlvs
 from .. import conformance as _helpers
 
-REVIEWED_CORE_SHA256 = 'd63f99f1809146ad41f1643526c81417b366d7a9d85af3845daee6654a229a14'  # oep-spec 02c08c9 docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = '699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e'  # oep-spec 364827b docs/oep-core.ja.md
 
 
 class CoreSmokeChecks:

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/conformance/host_core.py

@@ -4,7 +4,7 @@ from pathlib import Path
 import struct
 from . import require,spec_identity
 
-REVIEWED_CORE_SHA256='d63f99f1809146ad41f1643526c81417b366d7a9d85af3845daee6654a229a14'
+REVIEWED_CORE_SHA256='699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e'
 CORE_OPS={'confirm':1,'list':2,'describe':3,'clock':4,'open':16,'end':17,'keepalive':18,'lock_state':19}
 # the settings' ops (core §13.5 / §13.7, transports §7.3): their numbers reviewed, their results not read here
 SETTINGS_OPS={'get':32,'set':33,'unset':34,'save':35,'state':36,'network':37}

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/conformance/host_deadline.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from . import require,spec_identity
 
 
-REVIEWED={'docs/oep-core.ja.md':'d63f99f1809146ad41f1643526c81417b366d7a9d85af3845daee6654a229a14',
+REVIEWED={'docs/oep-core.ja.md':'699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e',
           'docs/oep-transports.ja.md':'2117de20712f7dfad6c81e247cf1b0b206ccf7528fcdf70702cbfce1c17dbadc'}
 QUICK_MS=1000  # core_quick_op_max_ms
 

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/conformance/host_requests.py

@@ -12,11 +12,11 @@ from . import require, spec_identity
 REVIEWED = {
     'interfaces/oep-if-plan.ja.md': 'da8bd60af53499573c07bc33dbd8c4df93eb61a93b91dc57907f26620ae36bbf',
     'interfaces/oep-if-fixture.ja.md': '780beb7a3f9adb51fccf3441930e4c04d2bb64ef738e302195cf5a4e7c2a60a6',
-    'docs/oep-core.ja.md': 'd63f99f1809146ad41f1643526c81417b366d7a9d85af3845daee6654a229a14',
-    'interfaces/oep-if-debug.ja.md': '6743420c31bcd354dd5b4b5352f4d8bcfa695f787dbc28644dba9e9533357338',
+    'docs/oep-core.ja.md': '699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e',
+    'interfaces/oep-if-debug.ja.md': '58843357aae5afd31082b068c76c754cbd047446fe4b0aa77b5c22cbedf1f3f8',
     'interfaces/oep-if-capture.ja.md': 'ffd89a6a1abf006aea788a6b47b270e6ac0e6d8190a716f4123c4f499bd3a61e',
 }
-REVIEWED_REGISTRY_SHA256='21057dbfc117365e0b9f9d96f377ed99dbc28568efc70829bf8d53384077f44e'
+REVIEWED_REGISTRY_SHA256='278114efc9235b4c6026cd66e11ed558e0ac5afd789011973f6293ae1abffb9c'
 
 
 def reviewed_identity(spec):

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/conformance/host_wait.py

@@ -6,7 +6,7 @@ from .. import registry as _reg
 SAVE=_reg.CORE.op['save']  # fn 0's save (core §13.7)
 
 
-REVIEWED={'docs/oep-core.ja.md':'d63f99f1809146ad41f1643526c81417b366d7a9d85af3845daee6654a229a14',
+REVIEWED={'docs/oep-core.ja.md':'699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e',
           'docs/oep-transports.ja.md':'2117de20712f7dfad6c81e247cf1b0b206ccf7528fcdf70702cbfce1c17dbadc'}
 QUICK_MS=1000  # core_quick_op_max_ms
 

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/conformance/oep_smoke.py

@@ -6,10 +6,10 @@ import struct
 
 from . import ops, require, tlvs
 
-REVIEWED_INTERFACES = {  # oep-spec 02c08c9 interfaces/
+REVIEWED_INTERFACES = {  # oep-spec 364827b interfaces/
     'oep-if-fixture.ja.md': '780beb7a3f9adb51fccf3441930e4c04d2bb64ef738e302195cf5a4e7c2a60a6',
     'oep-if-plan.ja.md': 'da8bd60af53499573c07bc33dbd8c4df93eb61a93b91dc57907f26620ae36bbf',
-    'oep-if-debug.ja.md': '6743420c31bcd354dd5b4b5352f4d8bcfa695f787dbc28644dba9e9533357338',
+    'oep-if-debug.ja.md': '58843357aae5afd31082b068c76c754cbd047446fe4b0aa77b5c22cbedf1f3f8',
     'oep-if-common.ja.md': '25fed0b1b8b7f246a8b71d02cea810249803b1c3c1e9c3df466c04f38687f70c',
 }
 

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/core.py

@@ -216,15 +216,16 @@ def transports(hst: h.Host) -> list[tuple[int, int, int]]:
 
 
 def take(hst: h.Host, lease_ms: int = 3000, *, owner: str | None = None, wait_s: float = 5.0,
-         force: bool = False) -> h.Opened:
+         force: bool = False, extensions=()) -> h.Opened:
     """Take the lock as host guide §6 says: when the probe's only transport is a serial port and this host opened it
     exclusively, the previous holder cannot be there any more - force at once; otherwise wait out the holder's lease
-    (up to wait_s), and name it (InUse) if it keeps it going. force: the user asked for it."""
+    (up to wait_s), and name it (InUse) if it keeps it going. force: the user asked for it. extensions: named
+    extensions for the open, sent critical (Host.open; a broker's sharing, host guide §7)."""
     link = getattr(hst, "link", None)
     ways = transports(hst)
     only = len(ways) == 1 and ways[0][1] in SERIAL_KINDS and getattr(link, "framing", None) == "cobs" \
         and getattr(link, "transport", None) == "serial"
-    return hst.take(lease_ms, owner=owner, only_way_in=only, wait_s=wait_s, force=force)
+    return hst.take(lease_ms, owner=owner, only_way_in=only, wait_s=wait_s, force=force, extensions=extensions)
 
 
 def plan_fn(hst: h.Host) -> int:

{oep_client_python-0.0.42 → oep_client_python-0.0.43}/src/oep_client/host.py

@@ -556,13 +556,15 @@ class Host:
             raise NotV1(f"the probe speaks OEP revision {self.revision}; session requests need revision 1 or more")
 
     # ---- session --------------------------------------------------------------------------------
-    def open(self, lease_ms: int = 0, *, force: bool = False, owner: str | None = None) -> Opened:
+    def open(self, lease_ms: int = 0, *, force: bool = False, owner: str | None = None, extensions=()) -> Opened:
         """Open a new session under a new random id (core §6.4; the id goes in the header, never 0). lease_ms 0 = the
         probe's default; 1000..60000 are taken as asked. owner: who holds the lock (1-32 bytes), shown to other hosts.
         force: take the lock from another session (its resources are released first). A session this host had open
         is left behind: it ended, or the probe refuses this open locked while it holds the lock - end it first. The
         answer's boot_id is watched (core §6.5: a reboot drops the fn mapping). fn 0's describe (its max_op_ms) is read
-        first when this host has not read it yet (core §4.4)."""
+        first when this host has not read it yet (core §4.4). extensions: named extensions (core §2.2, §12) to carry, each
+        a name or (name, data), sent critical - a probe that does not know one refuses the open (Unsupported, tag the
+        named extension's with bit 7) rather than ignore it; a broker's sharing is asked this way (host guide §7)."""
         self.require_v1()
         if self.kept is not None and self.session is None:
             self.kept.before_open(self, owner)              # once: the previous run's session ended (host guide §5)
@@ -571,6 +573,12 @@ class Host:
             core.describe(self, m.CORE_FN)                  # max_op_ms before a request that changes state (core §4.4)
         sid = self.rng.randrange(1, 1 << 32)                # random, never 0 (core §6.1)
         tail = m.tlv(OWNER, owner_text(owner)) if owner else b""
+        for item in extensions:
+            name, data = (item, b"") if isinstance(item, str) else item
+            raw = name.encode("ascii")
+            if not 1 <= len(raw) <= 255:
+                raise ValueError(f"named extension {name!r}: 1 to 255 bytes (core §2.2)")
+            tail += m.tlv(m.TAG_NAMED_EXTENSION, bytes([len(raw)]) + raw + bytes(data), critical=True)
         r = self.request(m.CORE_FN, m.OP_OPEN, struct.pack("<IB", lease_ms, int(force)) + tail, session=sid)
         rd = m.Reader(r.payload)
         lease, boot_id = rd.take("II")
@@ -646,17 +654,17 @@ class Host:
         return bool(locked), remaining, owner_of(p[5:])
 
     def take(self, lease_ms: int = 3000, *, owner: str | None = None, only_way_in: bool = False,
-             wait_s: float = 5.0, force: bool = False) -> Opened:
+             wait_s: float = 5.0, force: bool = False, extensions=()) -> Opened:
         """open() the way host guide §6 takes the lock. only_way_in: this link is the probe's only transport and a
         serial port opened exclusively - whoever held the lock cannot be there any more, so it is taken by force at
         once. Otherwise the holder's lease is waited out (up to wait_s); a holder that keeps it going raises InUse,
-        naming it. force: take it anyway (the user said so)."""
+        naming it. force: take it anyway (the user said so). extensions: as open's."""
         if force or only_way_in:
-            return self.open(lease_ms, force=True, owner=owner)
+            return self.open(lease_ms, force=True, owner=owner, extensions=extensions)
         deadline = time.monotonic() + wait_s
         while True:
             try:
-                return self.open(lease_ms, owner=owner)
+                return self.open(lease_ms, owner=owner, extensions=extensions)
             except Locked as e:
                 left = deadline - time.monotonic()
                 if left <= 0 or e.remaining_ms / 1000 > left:

oep_client_python-0.0.43/tests/spec/DOCS_SHA256

@@ -0,0 +1,12 @@
+699f7eb6333b6eb6678ddcf27074c03544f0f0a6ee0ef6ccdf02edd3757f962e  docs/oep-core.ja.md
+2117de20712f7dfad6c81e247cf1b0b206ccf7528fcdf70702cbfce1c17dbadc  docs/oep-transports.ja.md
+0a3f5dc1cc1b1a9375a17461f172e5b0f5d7fd6f9a4625b029d17fc839db1060  interfaces/README.ja.md
+ffd89a6a1abf006aea788a6b47b270e6ac0e6d8190a716f4123c4f499bd3a61e  interfaces/oep-if-capture.ja.md
+25fed0b1b8b7f246a8b71d02cea810249803b1c3c1e9c3df466c04f38687f70c  interfaces/oep-if-common.ja.md
+bdca8e524a4c6befe049b5a46972d7a5c647b78d8824d3a0bf20bd0210f12e2a  interfaces/oep-if-console.ja.md
+58843357aae5afd31082b068c76c754cbd047446fe4b0aa77b5c22cbedf1f3f8  interfaces/oep-if-debug.ja.md
+780beb7a3f9adb51fccf3441930e4c04d2bb64ef738e302195cf5a4e7c2a60a6  interfaces/oep-if-fixture.ja.md
+81d5f8ae9a556f0588373494f6c97ecf1df630c7c03d83e7e83c7260d320505a  interfaces/oep-if-link.ja.md
+da8bd60af53499573c07bc33dbd8c4df93eb61a93b91dc57907f26620ae36bbf  interfaces/oep-if-plan.ja.md
+c1925c4c23f97476725b1f8a18b91ba88f15ed0db9e790dbce81d4d17ca961ea  interfaces/oep-if-restart.ja.md
+35cabaff444b53f30fc390be4dd0bcc394709de790f88cb5f9404ddc0833aeb6  interfaces/target-console-dmseq.ja.md

oep_client_python-0.0.43/tests/test_conformance_reviewed_pins.py

@@ -0,0 +1,27 @@
+"""The conformance checkers pin the spec documents they were reviewed against; a sync of the spec (tools/sync_registry.sh,
+tests/spec/DOCS_SHA256 and the registry copy) without the checkers' review moved with it fails here."""
+import hashlib
+from pathlib import Path
+
+from oep_client import conformance
+from oep_client.conformance import core_smoke, host_core, host_deadline, host_requests, host_wait, oep_smoke
+
+SPEC = Path(__file__).parent / "spec"
+DOCS = dict(reversed(line.split("  ", 1)) for line in (SPEC / "DOCS_SHA256").read_text().split("\n") if line)
+
+
+def test_the_reviewed_core_is_the_synced_one():
+    for pin in (conformance.REVIEWED_CORE_SHA256, core_smoke.REVIEWED_CORE_SHA256, host_core.REVIEWED_CORE_SHA256):
+        assert pin == DOCS["docs/oep-core.ja.md"]
+
+
+def test_the_reviewed_documents_are_the_synced_ones():
+    for table in (host_wait.REVIEWED, host_deadline.REVIEWED, host_requests.REVIEWED):
+        for name, digest in table.items():
+            assert digest == DOCS[name], name
+    for name, digest in oep_smoke.REVIEWED_INTERFACES.items():
+        assert digest == DOCS["interfaces/" + name], name
+
+
+def test_the_reviewed_registry_is_the_synced_one():
+    assert host_requests.REVIEWED_REGISTRY_SHA256 == hashlib.sha256((SPEC / "oep-v1.toml").read_bytes()).hexdigest()

oep_client_python-0.0.43/tests/test_open_extensions.py

@@ -0,0 +1,57 @@
+"""Host.open's named extensions (core §2.2, §12; host guide §7: a broker's sharing is asked by one, sent critical)."""
+import random
+
+import pytest
+
+from oep_client import core, endpoint, host as h, message as m, registry, virtual_bench as vb
+
+SHARE = "io.github.ch32-riscv-ug.share"
+
+
+class Clock:
+    def __init__(self):
+        self.ms = 0
+
+    def __call__(self):
+        return self.ms
+
+
+def host_on(ep):
+    sent = []
+
+    def send(b):
+        sent.append(bytes(b))
+        return ep.handle(b, 0)
+    hst = h.Host(send, rng=random.Random(7))
+    return hst, sent
+
+
+def test_a_named_extension_goes_after_the_owner_critical():
+    """open carries `name_len name data` under the named extension's tag with bit 7, after the owner."""
+    hst, sent = host_on(endpoint.Endpoint(vb.p4_x035(), Clock()))
+    with pytest.raises(h.Unsupported):
+        hst.open(3000, owner="tests", extensions=[SHARE, ("io.example.with-data", b"\x01\x02")])
+    tail = m.Request.unpack(sent[-1]).payload[5:]                         # after lease_ms(u32) force(u8)
+    owner = m.tlv(registry.CORE.tlv["open"]["owner"], b"tests")
+    share = m.tlv(m.TAG_NAMED_EXTENSION, bytes([len(SHARE)]) + SHARE.encode(), critical=True)
+    data = m.tlv(m.TAG_NAMED_EXTENSION, bytes([20]) + b"io.example.with-data" + b"\x01\x02", critical=True)
+    assert tail == owner + share + data
+
+
+def test_a_probe_that_does_not_know_it_refuses_the_open():
+    """The virtual bench knows no named extension: a critical one is refused unsupported, its tag as received, and no
+    session is opened - a broker's client opens again without it (host guide §7)."""
+    ep = endpoint.Endpoint(vb.p4_x035(), Clock())
+    hst, _ = host_on(ep)
+    with pytest.raises(h.Unsupported) as e:
+        core.take(hst, 3000, owner="tests", extensions=[SHARE])
+    assert e.value.tag == m.TAG_NAMED_EXTENSION | m.TAG_CRITICAL and hst.session is None
+    assert hst.open(3000, owner="tests").lease_ms == 3000                # without it, the open is taken
+
+
+def test_a_name_out_of_its_length_is_refused_before_sending():
+    hst, sent = host_on(endpoint.Endpoint(vb.p4_x035(), Clock()))
+    with pytest.raises(ValueError):
+        hst.open(3000, extensions=[""])
+    with pytest.raises(ValueError):
+        hst.open(3000, extensions=["x" * 256])