embeddedci-openhtf 2.1.0__tar.gz → 2.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/CHANGELOG.md +7 -0
  2. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/PKG-INFO +28 -3
  3. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/README.md +27 -2
  4. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/pyproject.toml +1 -1
  5. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/src/embeddedci_openhtf/plug.py +40 -15
  6. embeddedci_openhtf-2.2.0/tests/test_docs_coverage.py +62 -0
  7. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/test_persistent.py +37 -3
  8. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/.gitignore +0 -0
  9. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/LICENSE +0 -0
  10. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/examples/analog_loopback.py +0 -0
  11. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/examples/flash_and_boot.py +0 -0
  12. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/examples/serial_smoke.py +0 -0
  13. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/examples/station.py +0 -0
  14. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/src/embeddedci_openhtf/__init__.py +0 -0
  15. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/src/embeddedci_openhtf/analog.py +0 -0
  16. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/src/embeddedci_openhtf/measurements.py +0 -0
  17. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/src/embeddedci_openhtf/phases.py +0 -0
  18. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/src/embeddedci_openhtf/pins.py +0 -0
  19. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/src/embeddedci_openhtf/power.py +0 -0
  20. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/_fake.py +0 -0
  21. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/conftest.py +0 -0
  22. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/test_analog.py +0 -0
  23. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/test_e2e_openhtf.py +0 -0
  24. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/test_measurements.py +0 -0
  25. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/test_phases.py +0 -0
  26. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/test_pins.py +0 -0
  27. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/test_plug.py +0 -0
  28. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.2.0}/tests/test_power.py +0 -0
@@ -1,5 +1,12 @@
1
1
  # Changelog — `embeddedci-openhtf`
2
2
 
3
+ ## 2.2.0
4
+
5
+ - Persistent plugs (`benchpod_plug(..., persistent=True)`) are pooled by their connection
6
+ settings (the connection and the `BenchPod` keyword arguments) instead of by plug class. Two
7
+ `benchpod_plug` calls for the same pod now share one connection (a pod serves one client at a
8
+ time), and a plug whose OpenHTF conf or environment changes gets a connection that matches.
9
+
3
10
  ## 2.1.0
4
11
 
5
12
  - 4-20 mA terminals: `current_out_phase` (and the `current_out` helper) holds a current on the
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: embeddedci-openhtf
3
- Version: 2.1.0
3
+ Version: 2.2.0
4
4
  Summary: OpenHTF plug for driving an EmbeddedCI BenchPod directly over TCP or serial (no cloud)
5
5
  Project-URL: Homepage, https://embeddedci.com
6
6
  Project-URL: Repository, https://github.com/embeddedci-com/embeddedci-python
@@ -183,6 +183,23 @@ def boot_and_rail(test, bench):
183
183
  test.measurements.rail_v = bench.power_status().rail(1).bus_voltage # volts
184
184
  ```
185
185
 
186
+ `flash_ok_measurement(name="flash_ok")` and `uart_matched_measurement(name="boot_ok")` are the
187
+ matching declarations, so a custom flash phase needs no hand-written measurement:
188
+
189
+ ```python
190
+ from embeddedci_openhtf import flash_ok_measurement, record_flash
191
+
192
+ @htf.measures(flash_ok_measurement())
193
+ @htf.plug(bench=bench)
194
+ def flash(test, bench):
195
+ result = bench.flash(file="fw.elf", target="target/stm32f4x.cfg",
196
+ swclk=11, swdio=12, nreset=True, check=False)
197
+ record_flash(test, result) # sets flash_ok and attaches openocd.log
198
+ ```
199
+
200
+ The recorders never raise on a bad result: they record the failing value, so the measurement (not
201
+ an exception) decides the phase outcome, and the OpenOCD or UART output is always attached.
202
+
186
203
  ### Analog steps
187
204
 
188
205
  The pod's DAC output and ADC input are exposed as phases (and low-level helpers).
@@ -321,8 +338,10 @@ def ripple_under_load(test, bench):
321
338
  By default the plug opens a connection per `Test.execute()` and closes it at
322
339
  teardown. On a station cycling many DUTs back-to-back, pass `persistent=True` to
323
340
  keep **one** connection open across executions (re-checked with a ping each run,
324
- reconnected if it dropped). Reuse the *same* plug class for every execution, and
325
- close it once at the end:
341
+ reconnected if it dropped). Persistent plugs are pooled by their connection settings (the
342
+ connection and the `BenchPod` keyword arguments), so two `benchpod_plug(..., persistent=True)`
343
+ calls for the same pod share one connection, and a plug whose OpenHTF conf or environment changes
344
+ gets a connection that matches. Close them once at the end:
326
345
 
327
346
  ```python
328
347
  import openhtf as htf
@@ -341,6 +360,12 @@ finally:
341
360
  close_persistent_benchpods() # also runs automatically at process exit
342
361
  ```
343
362
 
363
+ `benchpod_plug(connection=None, *, persistent=False, health_check=True, **pod_kwargs)` returns a
364
+ `BenchPodPlug` subclass with those values as class attributes (`connection`, `persistent`,
365
+ `health_check`, `pod_kwargs`). `health_check=False` skips the ping before a pooled connection is
366
+ reused. Inside a phase, `bench.pod` is the connected `BenchPod`; any other attribute the plug does
367
+ not have is looked up on it, which is why `bench.power_on()` works.
368
+
344
369
  ## Examples
345
370
 
346
371
  * [`examples/flash_and_boot.py`](examples/flash_and_boot.py) — flash over SWD then
@@ -157,6 +157,23 @@ def boot_and_rail(test, bench):
157
157
  test.measurements.rail_v = bench.power_status().rail(1).bus_voltage # volts
158
158
  ```
159
159
 
160
+ `flash_ok_measurement(name="flash_ok")` and `uart_matched_measurement(name="boot_ok")` are the
161
+ matching declarations, so a custom flash phase needs no hand-written measurement:
162
+
163
+ ```python
164
+ from embeddedci_openhtf import flash_ok_measurement, record_flash
165
+
166
+ @htf.measures(flash_ok_measurement())
167
+ @htf.plug(bench=bench)
168
+ def flash(test, bench):
169
+ result = bench.flash(file="fw.elf", target="target/stm32f4x.cfg",
170
+ swclk=11, swdio=12, nreset=True, check=False)
171
+ record_flash(test, result) # sets flash_ok and attaches openocd.log
172
+ ```
173
+
174
+ The recorders never raise on a bad result: they record the failing value, so the measurement (not
175
+ an exception) decides the phase outcome, and the OpenOCD or UART output is always attached.
176
+
160
177
  ### Analog steps
161
178
 
162
179
  The pod's DAC output and ADC input are exposed as phases (and low-level helpers).
@@ -295,8 +312,10 @@ def ripple_under_load(test, bench):
295
312
  By default the plug opens a connection per `Test.execute()` and closes it at
296
313
  teardown. On a station cycling many DUTs back-to-back, pass `persistent=True` to
297
314
  keep **one** connection open across executions (re-checked with a ping each run,
298
- reconnected if it dropped). Reuse the *same* plug class for every execution, and
299
- close it once at the end:
315
+ reconnected if it dropped). Persistent plugs are pooled by their connection settings (the
316
+ connection and the `BenchPod` keyword arguments), so two `benchpod_plug(..., persistent=True)`
317
+ calls for the same pod share one connection, and a plug whose OpenHTF conf or environment changes
318
+ gets a connection that matches. Close them once at the end:
300
319
 
301
320
  ```python
302
321
  import openhtf as htf
@@ -315,6 +334,12 @@ finally:
315
334
  close_persistent_benchpods() # also runs automatically at process exit
316
335
  ```
317
336
 
337
+ `benchpod_plug(connection=None, *, persistent=False, health_check=True, **pod_kwargs)` returns a
338
+ `BenchPodPlug` subclass with those values as class attributes (`connection`, `persistent`,
339
+ `health_check`, `pod_kwargs`). `health_check=False` skips the ping before a pooled connection is
340
+ reused. Inside a phase, `bench.pod` is the connected `BenchPod`; any other attribute the plug does
341
+ not have is looked up on it, which is why `bench.power_on()` works.
342
+
318
343
  ## Examples
319
344
 
320
345
  * [`examples/flash_and_boot.py`](examples/flash_and_boot.py) — flash over SWD then
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "embeddedci-openhtf"
7
- version = "2.1.0"
7
+ version = "2.2.0"
8
8
  description = "OpenHTF plug for driving an EmbeddedCI BenchPod directly over TCP or serial (no cloud)"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -54,6 +54,7 @@ station that cycles many DUTs back-to-back, pass ``persistent=True`` to
54
54
  :func:`benchpod_plug` to keep one connection open across executions (re-checked
55
55
  with a ping each run and reconnected if it dropped); close it explicitly with
56
56
  :func:`close_persistent_benchpods` (also run automatically at process exit).
57
+ Persistent plugs with the same connection settings share one connection.
57
58
 
58
59
  Unknown attribute access proxies to the underlying
59
60
  :class:`~embeddedci.benchpod.BenchPod`, so ``bench.flash(...)`` /
@@ -67,7 +68,7 @@ import atexit
67
68
  import os
68
69
  import threading
69
70
  from types import MappingProxyType
70
- from typing import Any, Dict, Mapping, Optional
71
+ from typing import Any, Dict, Hashable, Mapping, Optional
71
72
 
72
73
  import openhtf as htf
73
74
  from openhtf.plugs import BasePlug
@@ -105,12 +106,36 @@ htf.conf.declare(
105
106
  default_value=None,
106
107
  )
107
108
 
108
- # Process-wide pool of persistent connections, keyed by the bound plug class (one
109
- # per benchpod_plug(persistent=True) call). Survives across test executions.
110
- _PERSISTENT_POOL: Dict[type, BenchPod] = {}
109
+ # Process-wide pool of persistent connections, keyed by the connection settings (the connection
110
+ # and the BenchPod keywords, see _pool_key). Plugs with the same settings share one connection,
111
+ # which a pod that serves one client at a time needs, and a plug whose settings change (an OpenHTF
112
+ # conf value, an env var) gets a connection that matches them. Survives across test executions.
113
+ _PERSISTENT_POOL: Dict[Hashable, BenchPod] = {}
111
114
  _PERSISTENT_LOCK = threading.Lock()
112
115
 
113
116
 
117
+ def _key_part(value: Any) -> Hashable:
118
+ """A hashable stand-in for one setting: the value itself when hashable and plain, its
119
+ contents for a dict, list or set (a wiring map), and its identity for any other object (an
120
+ injected transport, a Wiring), which is the same pod only when it is the same object."""
121
+ if value is None or isinstance(value, (bool, int, float, str, bytes)):
122
+ return value
123
+ if isinstance(value, Mapping):
124
+ return ("map", tuple(sorted((str(k), _key_part(v)) for k, v in value.items())))
125
+ if isinstance(value, (list, tuple)):
126
+ return ("seq", tuple(_key_part(v) for v in value))
127
+ if isinstance(value, (set, frozenset)):
128
+ return ("set", tuple(sorted(repr(_key_part(v)) for v in value)))
129
+ if isinstance(value, os.PathLike):
130
+ return ("path", os.fspath(value))
131
+ return ("obj", id(value))
132
+
133
+
134
+ def _pool_key(conn: Optional[str], pod_kwargs: Mapping[str, Any]) -> Hashable:
135
+ """The pool key for a connection and its BenchPod keywords."""
136
+ return (conn, tuple(sorted((k, _key_part(v)) for k, v in pod_kwargs.items())))
137
+
138
+
114
139
  def _conf_value(name: str) -> Any:
115
140
  """The OpenHTF conf value for ``name``, or ``None`` when it has none."""
116
141
  try:
@@ -138,12 +163,13 @@ def close_persistent_benchpods() -> None:
138
163
  atexit.register(close_persistent_benchpods)
139
164
 
140
165
 
141
- def _acquire_persistent(cls: type, conn: Optional[str],
142
- pod_kwargs: Mapping[str, Any], health_check: bool) -> BenchPod:
143
- """Return the pooled connection for ``cls``, opening (or reopening, if a
166
+ def _acquire_persistent(conn: Optional[str], pod_kwargs: Mapping[str, Any],
167
+ health_check: bool) -> BenchPod:
168
+ """Return the pooled connection for these settings, opening (or reopening, if a
144
169
  health-check ping fails) it as needed."""
170
+ key = _pool_key(conn, pod_kwargs)
145
171
  with _PERSISTENT_LOCK:
146
- pod = _PERSISTENT_POOL.get(cls)
172
+ pod = _PERSISTENT_POOL.get(key)
147
173
  if pod is not None and health_check:
148
174
  try:
149
175
  pod.ping() # cheap liveness check; reconnect if the link died
@@ -153,10 +179,10 @@ def _acquire_persistent(cls: type, conn: Optional[str],
153
179
  except Exception:
154
180
  pass
155
181
  pod = None
156
- _PERSISTENT_POOL.pop(cls, None)
182
+ _PERSISTENT_POOL.pop(key, None)
157
183
  if pod is None:
158
184
  pod = BenchPod(conn, **pod_kwargs)
159
- _PERSISTENT_POOL[cls] = pod
185
+ _PERSISTENT_POOL[key] = pod
160
186
  return pod
161
187
 
162
188
 
@@ -214,8 +240,7 @@ class BenchPodPlug(BasePlug):
214
240
  pod_kwargs.setdefault("la_voltage", float(benchpod_la_voltage))
215
241
  if cls.persistent:
216
242
  #: The connected SDK client (shared, kept open across executions).
217
- self.pod: BenchPod = _acquire_persistent(
218
- cls, conn, pod_kwargs, cls.health_check)
243
+ self.pod: BenchPod = _acquire_persistent(conn, pod_kwargs, cls.health_check)
219
244
  else:
220
245
  # Direct TCP/serial connections never lease.
221
246
  self.pod = BenchPod(conn, **pod_kwargs)
@@ -258,9 +283,9 @@ def benchpod_plug(connection: Optional[str] = None, *, persistent: bool = False,
258
283
  @htf.plug(bench=benchpod_plug("/dev/ttyACM0"))
259
284
  def phase(test, bench): ...
260
285
 
261
- Set ``persistent=True`` to keep one connection open across test executions
262
- (reuse the *same* returned class for every ``Test.execute()`` so they share
263
- it); see :func:`close_persistent_benchpods`. Extra keyword args are forwarded
286
+ Set ``persistent=True`` to keep one connection open across test executions;
287
+ persistent plugs with the same connection and keyword arguments share it,
288
+ whichever ``benchpod_plug`` call made them. See :func:`close_persistent_benchpods`. Extra keyword args are forwarded
264
289
  to ``BenchPod(...)``: ``la_voltage=`` (volts), ``wiring=`` (a dict, a
265
290
  ``.json``/``.toml`` path or a :class:`~embeddedci.benchpod.Wiring`, which then
266
291
  supplies the channels, baud and power rail a phase leaves out), ``timeout=``
@@ -0,0 +1,62 @@
1
+ """Every public name of embeddedci-openhtf is documented in its README.
2
+
3
+ Covers ``embeddedci_openhtf.__all__``, the public attributes and methods of ``BenchPodPlug``, and
4
+ the OpenHTF conf keys the plug declares. Each must appear inside a code span or code block of
5
+ ``README.md``. A name left out on purpose goes in ``ALLOWLIST`` with the reason.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import inspect
11
+ import re
12
+ from pathlib import Path
13
+ from typing import Dict, List, Set
14
+
15
+ import embeddedci_openhtf
16
+ from embeddedci_openhtf import plug as plug_module
17
+
18
+ README = Path(__file__).resolve().parents[1] / "README.md"
19
+
20
+ #: name -> why it is not in the README.
21
+ ALLOWLIST: Dict[str, str] = {
22
+ "tearDown": "OpenHTF plug lifecycle hook, called by OpenHTF, not by users",
23
+ "__version__": "standard package metadata",
24
+ }
25
+
26
+
27
+ def _code_text() -> str:
28
+ text = README.read_text(encoding="utf-8")
29
+ fenced = re.compile(r"^```.*?^```", re.M | re.S)
30
+ return "\n".join(fenced.findall(text) + re.findall(r"`([^`\n]+)`", fenced.sub("", text)))
31
+
32
+
33
+ def public_names() -> Set[str]:
34
+ names = set(embeddedci_openhtf.__all__)
35
+ for name, value in vars(embeddedci_openhtf.BenchPodPlug).items():
36
+ if not name.startswith("_") and (inspect.isfunction(value) or not callable(value)):
37
+ names.add(name)
38
+ names.add("pod") # set per instance in __init__
39
+ source = inspect.getsource(plug_module)
40
+ names.update(re.findall(r"htf\.conf\.declare\(\s*\"(\w+)\"", source))
41
+ return names
42
+
43
+
44
+ def _missing() -> List[str]:
45
+ text = _code_text()
46
+ return sorted(n for n in public_names() if n not in ALLOWLIST
47
+ and not re.search(r"(?<!\w)" + re.escape(n) + r"(?!\w)", text))
48
+
49
+
50
+ def test_names_are_found():
51
+ assert {"BenchPodPlug", "benchpod_plug", "persistent", "benchpod_timeout"} <= public_names()
52
+
53
+
54
+ def test_every_public_name_is_documented():
55
+ missing = _missing()
56
+ assert not missing, ("names missing from packages/embeddedci-openhtf/README.md (document them "
57
+ "or add them to ALLOWLIST with a reason): " + ", ".join(missing))
58
+
59
+
60
+ def test_allowlist_is_still_needed():
61
+ stale = sorted(n for n in ALLOWLIST if n not in public_names())
62
+ assert not stale, "ALLOWLIST names that are no longer public: " + ", ".join(stale)
@@ -8,7 +8,7 @@ from embeddedci_openhtf import (
8
8
  close_persistent_benchpods,
9
9
  power_phase,
10
10
  )
11
- from embeddedci_openhtf.plug import _PERSISTENT_POOL
11
+ from embeddedci_openhtf.plug import _PERSISTENT_POOL, _pool_key
12
12
  from _fake import FakeTransport
13
13
 
14
14
 
@@ -47,14 +47,48 @@ def test_persistent_reconnects_after_drop():
47
47
  bench = benchpod_plug(transport=tx, persistent=True)
48
48
  try:
49
49
  _run(power_phase(bench, on=True))
50
- pod1 = _PERSISTENT_POOL[bench]
50
+ key = _pool_key(None, {"transport": tx, "timeout": 30.0})
51
+ pod1 = _PERSISTENT_POOL[key]
51
52
  # simulate the link dying: make the health-check ping fail
52
53
  def boom():
53
54
  raise OSError("link dropped")
54
55
  tx.ping = boom
55
56
  _run(power_phase(bench, on=True))
56
57
  # the dead connection was dropped and a fresh BenchPod opened
57
- pod2 = _PERSISTENT_POOL[bench]
58
+ pod2 = _PERSISTENT_POOL[key]
58
59
  assert pod2 is not pod1
59
60
  finally:
60
61
  close_persistent_benchpods()
62
+
63
+
64
+ def test_plugs_with_the_same_settings_share_one_connection():
65
+ tx = FakeTransport()
66
+ first = benchpod_plug(transport=tx, persistent=True, la_voltage=3.3)
67
+ second = benchpod_plug(transport=tx, persistent=True, la_voltage=3.3)
68
+ try:
69
+ _run(power_phase(first, efuse=1, on=True))
70
+ _run(power_phase(second, efuse=1, on=True))
71
+ assert len(_PERSISTENT_POOL) == 1
72
+ assert len(tx.power_calls) == 2
73
+ finally:
74
+ close_persistent_benchpods()
75
+
76
+
77
+ def test_different_settings_get_their_own_connection():
78
+ tx1, tx2 = FakeTransport(), FakeTransport()
79
+ try:
80
+ _run(power_phase(benchpod_plug(transport=tx1, persistent=True), on=True))
81
+ _run(power_phase(benchpod_plug(transport=tx2, persistent=True), on=True))
82
+ _run(power_phase(benchpod_plug(transport=tx1, persistent=True, timeout=5.0), on=True))
83
+ assert len(_PERSISTENT_POOL) == 3
84
+ finally:
85
+ close_persistent_benchpods()
86
+ assert tx1.closed and tx2.closed
87
+
88
+
89
+ def test_pool_key_reads_settings_by_value():
90
+ wiring = {"signals": {"READY": 5}, "uart": {"baud": 115200}}
91
+ assert _pool_key("10.0.0.5:8080", {"wiring": wiring, "la_voltage": 3.3}) == \
92
+ _pool_key("10.0.0.5:8080", {"la_voltage": 3.3, "wiring": dict(wiring)})
93
+ assert _pool_key("10.0.0.5:8080", {}) != _pool_key("10.0.0.6:8080", {})
94
+ assert _pool_key("x", {"la_voltage": 1.8}) != _pool_key("x", {"la_voltage": 3.3})