protocol-validation-suite-framework-apis 26.7.1__py3-none-any.whl

Protocol_Validation_Suite_APIs/CODE_REVIEW_REPORT.md

@@ -0,0 +1,616 @@
+# Code Review Report — Protocol_Validation_Suite_APIs
+
+**Reviewer disposition:** by-the-book, strict.
+**Scope:** all hand-written Python in `Protocol_Validation_Suite_APIs/`.
+**Excluded:** auto-generated `stubs/GRPC_pb2.py` and `stubs/GRPC_pb2_grpc.py` (generated, "DO NOT EDIT"); docstring/inline-comment prose (except where a docstring asserts a wrong *type* or a contract the code contradicts).
+
+**Files reviewed:**
+- `__init__.py`
+- `models.py`
+- `protocol_validation_suite_apis.py`
+- `_client.py`
+- `_decorators.py`
+- `_utils.py`
+
+### Summary
+
+| Severity | Count | IDs |
+|---|---|---|
+| 🔴 Critical | 5 | C1–C5 |
+| 🟠 High | 8 | C6–C13 |
+| 🟡 Medium | 17 | S1–S17 |
+
+**Most urgent:** C1 and C2 are outright functional bugs that hit real callers. C6 is the systemic issue — the catch-all decorator masks C1, C7, C13 and every other failure as a silent `None`. Fix C6's swallowing behavior first, because it currently hides the rest.
+
+---
+
+## 🔴 Critical — Functional defects
+
+---
+
+### C1. `Selected_Step_Numbers` type mismatch — `list[int]` sent to a `repeated string` field
+
+**Location:** `_client.py:394` (definition of type at `models.py:51`)
+
+**What is wrong:**
+The proto defines `Compile_Details.Selected_Step_Numbers` as **`repeated string`**. `compile_sequence` passes `compile_sequence_details.selected_step_numbers` straight through, and `CompileSequenceRequest.selected_step_numbers` is typed `list[int]`.
+
+```python
+# _client.py:391-397
+request = GRPC_pb2.Compile_Details(
+    Sequence_Name=compile_sequence_details.sequence_name,
+    Variable_Name=compile_sequence_details.variable_name,
+    Selected_Step_Numbers=compile_sequence_details.selected_step_numbers,  # list[int] -> repeated string
+    Skip_Migrate=compile_sequence_details.skip_migrate,
+    Run_Sequence_Manager=compile_sequence_details.run_sequence_manager,
+)
+```
+
+**Why it is critical:**
+protobuf raises `TypeError` when serializing `int` into a `string` field. Any caller passing a non-empty `selected_step_numbers` list gets a hard failure. Because of the catch-all decorator (C6), that failure is swallowed and the caller silently receives `None` instead of a compile result — the feature simply does not work and gives no signal that it broke.
+
+**Suggested fix:**
+Convert to strings before building the message:
+
+```python
+Selected_Step_Numbers=[str(step) for step in compile_sequence_details.selected_step_numbers],
+```
+
+---
+
+### C2. `run_sequence` returns a protobuf message but is typed and documented as `str`
+
+**Location:** `_client.py:503-504`
+
+**What is wrong:**
+`Get_Report_Details` returns a `Report_Details` message whose payload is the `Report_Folder_Path` field. The code returns the whole message object, while the signature says `-> str` and the docstring promises "Absolute path to the generated report directory."
+
+```python
+# _client.py:503-504
+report_path = self.stub.Get_Report_Details(GRPC_pb2.Trigger(Trigger=True))
+return report_path   # <-- returns a Report_Details message, not a str
+```
+
+**Why it is critical:**
+The documented and annotated return type is violated. Callers that do `os.path.exists(result)`, string concatenation, or logging on the return value get a protobuf object and either crash or behave incorrectly. This breaks the primary success-path contract of the method.
+
+**Suggested fix:**
+
+```python
+report_details = self.stub.Get_Report_Details(GRPC_pb2.Trigger(Trigger=True))
+return report_details.Report_Folder_Path
+```
+
+---
+
+### C3. Inconsistent return contract in `run_sequence` — error path returns a human sentence
+
+**Location:** `_client.py:499` and `_client.py:506`
+
+**What is wrong:**
+The same function returns three structurally different things:
+- success → a report path
+- runtime errors → `"Sequence run encountered errors: ..."` (line 499)
+- compile failure → `"Sequence compilation failed, cannot run sequence ..."` (line 506)
+
+```python
+# _client.py:499
+return "Sequence run encountered errors: " + ";\n ".join(parts)
+...
+# _client.py:506
+return f"Sequence compilation failed, cannot run sequence {run_sequence_details.sequence_name} - {response.Message}."
+```
+
+**Why it is critical:**
+A caller cannot programmatically distinguish success from failure without string-sniffing the return value. Automation code built on this API cannot reliably branch on outcome, which defeats the purpose of an automation SDK.
+
+**Suggested fix:**
+Return a structured result instead of overloaded prose, e.g. a dataclass:
+
+```python
+@dataclass
+class RunSequenceResult:
+    success: bool
+    report_path: str | None = None
+    errors: list[tuple[int, str]] | None = None
+    message: str | None = None
+```
+
+…and populate `success`/`report_path`/`errors`/`message` on each path so callers branch on fields, not strings.
+
+---
+
+### C4. Dead branch: `step is None` can never be true
+
+**Location:** `_client.py:489-490`
+
+**What is wrong:**
+`errors` only ever receives tuples where `step_number_int is not None` (guarded at `_client.py:465`). So in the reporting loop, `step` is never `None`.
+
+```python
+# _client.py:465-466  -- guard ensures step is never None when added
+if step_number_int is not None:
+    errors.add((step_number_int, info))
+...
+# _client.py:489-490  -- therefore unreachable
+if step is None:
+    step_label = "Step Unknown"
+```
+
+**Why it is critical (correctness):**
+Unreachable code signals a logic gap: either the guard at line 465 is wrong (some errors with unknown step should be captured but are being dropped), or the `None` branch is stale. Either way the intent and the code disagree, which is exactly the kind of latent defect a strict review must flag.
+
+**Suggested fix:**
+Decide the intent. If unknown-step errors should be reported, remove the `is not None` guard at line 465 and keep the `None` branch. If not, remove the dead `if step is None` branch entirely.
+
+---
+
+### C5. Comment/logic contradiction on end-of-sequence detection
+
+**Location:** `_client.py:468-472` vs `_client.py:491-492`
+
+**What is wrong:**
+The loop comment says `step_number_int == 0` is "Completion of Sequence" and `-1` is "Error before the start of sequence." But the label logic only special-cases `-1` as `"End of Sequence"` and formats `0` as `"Step 0"`.
+
+```python
+# _client.py:468-472
+# -- Completion of Sequence (step_number_int == 0)
+# -- Error before the start of sequence (step_number_int == -1)
+if step_number_int in [0, -1]:
+    break
+...
+# _client.py:491-494
+elif step == -1:
+    step_label = "End of Sequence"
+else:
+    step_label = f"Step {step}"   # step == 0 falls here -> "Step 0"
+```
+
+**Why it is critical:**
+The two pieces of logic disagree about what `0` and `-1` mean. `-1` is documented as "error before start" but labeled "End of Sequence"; `0` is documented as "completion" but rendered as an ordinary "Step 0". Error reports emitted to users will be mislabeled, and the mismatch strongly suggests the sentinel handling is wrong.
+
+**Suggested fix:**
+Make labels match the documented semantics, e.g.:
+
+```python
+if step == -1:
+    step_label = "Before Sequence Start"
+elif step == 0:
+    step_label = "End of Sequence"
+else:
+    step_label = f"Step {step}"
+```
+
+(Confirm the true sentinel meaning with the server contract before finalizing.)
+
+---
+
+## 🟠 High — Robustness / correctness
+
+---
+
+### C6. Blanket `@handle_exceptions` swallows everything and returns `None`
+
+**Location:** `_decorators.py:34-41`
+
+**What is wrong:**
+Every public method is wrapped so that **any** exception is printed and converted to `None`.
+
+```python
+# _decorators.py:35-41
+def wrapper(*args, **kwargs):
+    try:
+        return func(*args, **kwargs)
+    except Exception as e:
+        print(f"[ERROR] Exception occurred in '{func_name}': {e}")
+        traceback.print_exc()
+        return None
+```
+
+**Why it is critical:**
+- Functions documented `-> bool` / `-> str` / `-> dict` can silently return `None`, violating their type contract on every error path.
+- It masks real bugs (C1, C7, C13) — failures become silent `None`s with no exception to catch.
+- `launch_server` documents `Raises: FileNotFoundError` (`_client.py:71`), `_wait_until_server_is_ready` documents `Raises: TimeoutError`, and `get_paths` documents `Raises: FileNotFoundError, JSONDecodeError` — but the decorator guarantees none of these can ever propagate. Docstring and behavior are in direct conflict.
+- `print` for error reporting is inappropriate for a library; use `logging`.
+
+**Suggested fix:**
+- Do not blanket-swallow. Catch specific, expected exceptions where recovery is meaningful and let the rest propagate.
+- Replace `print` with the `logging` module.
+- If a "graceful" mode is genuinely required, make it opt-in and return a typed result (never `None` masquerading as `bool`/`str`).
+
+---
+
+### C7. `close_server` crashes / no-ops if the server was never launched
+
+**Location:** `_client.py:205`
+
+**What is wrong:**
+`self.stub` is `None` until `_init_grpc_channel` runs. `close_server` dereferences it unconditionally.
+
+```python
+# _client.py:204-205
+trigger = Trigger(Trigger=False)
+response = self.stub.Close_Server(trigger)   # AttributeError if stub is None
+```
+
+**Why it is critical:**
+If `launch_server` failed or was never called, this raises `AttributeError`, which C6 converts to `None`. The caller believes shutdown happened when it did not — resource/process cleanup is skipped silently.
+
+**Suggested fix:**
+
+```python
+if self.stub is not None:
+    self.stub.Close_Server(Trigger(Trigger=False))
+```
+
+…and still run the process/thread teardown below it regardless.
+
+---
+
+### C8. `_wait_until_server_is_ready` leaks a channel and does not reuse the real one
+
+**Location:** `_client.py:172-174`
+
+**What is wrong:**
+A fresh channel is created only for the readiness probe and never closed; `_init_grpc_channel` then creates a second channel.
+
+```python
+# _client.py:172-174
+grpc.channel_ready_future(
+    grpc.insecure_channel(self.__grpc_target_host)   # created, never closed
+).result(timeout=self.__grpc_server_timeout)
+```
+
+**Why it is critical (resource leak):**
+Every launch leaks one gRPC channel. Two channels exist for the same target. Over repeated launch cycles this accumulates.
+
+**Suggested fix:**
+Create the channel once, store it, probe readiness on it, and reuse it in `_init_grpc_channel`:
+
+```python
+self.channel = grpc.insecure_channel(self.__grpc_target_host)
+grpc.channel_ready_future(self.channel).result(timeout=self.__grpc_server_timeout)
+# _init_grpc_channel then just binds the stub to self.channel
+```
+
+---
+
+### C9. Error-watcher exception "signalling" is effectively useless + thread race
+
+**Location:** `_client.py:138-152` (and read side at `_client.py:177`)
+
+**What is wrong:**
+Fatal stderr lines are appended to `_server_launch_exceptions`, but this list is only ever read inside `_wait_until_server_is_ready` on a `FutureTimeoutError`.
+
+```python
+# _client.py:177-178
+if len(self._server_launch_exceptions) > 0:
+    raise self._server_launch_exceptions[0]
+```
+
+**Why it is critical:**
+- If the server becomes reachable but the watcher later captures a fatal error, nothing surfaces it — the error is collected and ignored.
+- The list is written on a daemon thread and read on the main thread with no lock → data race.
+
+**Suggested fix:**
+- Guard `_server_launch_exceptions` with a `threading.Lock` (or use a `queue.Queue`).
+- Check for captured fatal errors after RPC calls, or fail fast when the watcher records one, rather than only on the readiness timeout.
+
+---
+
+### C10. Substring error-classification is fragile
+
+**Location:** `_client.py:124-133`
+
+**What is wrong:**
+Free-form stderr is lowercased and matched against substrings like `"unavailable"` and `"connection refused"` to decide "non-fatal."
+
+```python
+# _client.py:124-133
+conn_err_markers = ["failed to connect to all addresses", "connectex",
+                    "connection refused", "10061", "unavailable"]
+low = stripped_line.lower()
+if any(m in low for m in conn_err_markers):
+    continue
+```
+
+**Why it is critical:**
+Any legitimate fatal error whose message merely *contains* one of these words (e.g. a real failure mentioning "service unavailable") is misclassified as non-fatal and dropped, hiding genuine startup failures.
+
+**Suggested fix:**
+Classify on structured signals (gRPC status codes / typed exceptions) rather than substring matching of human-readable text. If substring matching is unavoidable, anchor it tightly and document the exact source strings.
+
+---
+
+### C11. Fragile magic-string parsing of the setup payload
+
+**Location:** `_client.py:305-308`
+
+**What is wrong:**
+`setup_interposer_board` strips a literal `"Data: "` prefix then `json.loads`.
+
+```python
+# _client.py:305-308
+if raw_data.startswith("Data: "):
+    raw_data = raw_data[len("Data: ") :]
+data = json.loads(raw_data)
+```
+
+**Why it is critical:**
+If the server omits/renames the prefix or returns non-JSON on failure, `json.loads` throws, which C6 swallows → `None`. The undocumented magic-string protocol makes the parse brittle and the failure invisible.
+
+**Suggested fix:**
+Wrap the parse defensively and handle malformed payloads explicitly:
+
+```python
+try:
+    data = json.loads(raw_data)
+except json.JSONDecodeError:
+    return "Setup InterposerBoard Failed: unrecognized server response."
+```
+
+Better: agree a structured response field with the server rather than a prefixed string.
+
+---
+
+### C12. `get_paths` opens config without an explicit encoding
+
+**Location:** `_utils.py:58`
+
+**What is wrong:**
+
+```python
+# _utils.py:58
+with open(json_path, "r") as f:   # no encoding
+    data = json.load(f)
+```
+
+**Why it is critical (portability):**
+Uses the platform default encoding, which differs across OSes/locales and can corrupt non-ASCII paths. `_client.py:45` correctly uses `encoding="utf-8"`; this one is inconsistent and non-portable.
+
+**Suggested fix:**
+
+```python
+with open(json_path, "r", encoding="utf-8") as f:
+    data = json.load(f)
+```
+
+---
+
+### C13. `Utils.get_paths` documents `Raises` but is decorated to never raise → constructor `TypeError`
+
+**Location:** `_utils.py:47-49` (fallout at `_client.py:44-45`)
+
+**What is wrong:**
+The docstring promises `FileNotFoundError` / `JSONDecodeError`, but `@handle_exceptions` converts both to `None`. That `None` then flows into the constructor:
+
+```python
+# _client.py:44-45
+self.__paths = Utils.get_paths()                  # may be None (C6)
+with open(self.__paths["ApplicationSettingsPath"], ...)   # None[...] -> TypeError
+```
+
+**Why it is critical:**
+On any config problem, `get_paths` returns `None` instead of raising, and `self.__paths["..."]` raises `TypeError: 'NoneType' object is not subscriptable`. The constructor has no defined failure mode, and the actual error (missing/invalid config) is obscured behind an unrelated `TypeError`.
+
+**Suggested fix:**
+Remove `@handle_exceptions` from `get_paths` (let config errors propagate as documented), or validate the result in `__init__`:
+
+```python
+self.__paths = Utils.get_paths()
+if not self.__paths:
+    raise RuntimeError("Failed to load paths.json configuration.")
+```
+
+---
+
+## 🟡 Medium — Coding standards / consistency
+
+---
+
+### S1. Inconsistent parameter naming between facade and client
+
+**Location:** `protocol_validation_suite_apis.py:66` vs `_client.py:265`, `_client.py:381`, `_client.py:402`
+
+The public facade uses `request`, while the client uses `setup_interposer_board_request` / `compile_sequence_details` / `run_sequence_details`.
+
+**Why it matters:** Inconsistent naming for the same concept across the call chain hurts readability and maintainability.
+
+**Suggested fix:** Pick one convention (e.g. `request`) and apply it in both layers.
+
+---
+
+### S2. Missing / inconsistent return type hints
+
+**Location:** `protocol_validation_suite_apis.py` (`launch_server`, `set_profile`, `setup_interposer_board`, `compile_sequence`, `run_sequence`, `i3s_monitor_setup`); `_client.py:381` (`compile_sequence` documented `tuple[bool, str]` but unannotated); `set_profile` unannotated while `load_project` is annotated.
+
+**Why it matters:** Documented return types without annotations defeat static analysis and IDE support; the codebase is uneven.
+
+**Suggested fix:** Add explicit return annotations matching the docstrings (e.g. `-> tuple[bool, str]`, `-> bool`, `-> str`).
+
+---
+
+### S3. `__init__.py` public surface is incomplete
+
+**Location:** `__init__.py:2-8`
+
+`SetupInterposerBoardRequest` and `ResetInterposerBoardRequest` are required arguments of public methods but are **not** exported. `ProtocolDebugResponse` is also unexported.
+
+**Why it matters:** Users must import from `.models` (a private-looking module) to call public methods — the advertised API is not self-contained.
+
+**Suggested fix:** Add the request models to the imports and `__all__`:
+
+```python
+from .models import (
+    CompileSequenceRequest, RunSequenceRequest, I3SMonitorSetupRequest,
+    SetupInterposerBoardRequest, ResetInterposerBoardRequest,
+)
+__all__ = [
+    "ProtocolValidationSuiteAPIs",
+    "CompileSequenceRequest", "RunSequenceRequest", "I3SMonitorSetupRequest",
+    "SetupInterposerBoardRequest", "ResetInterposerBoardRequest",
+]
+```
+
+---
+
+### S4. Dead / unreachable capability: `_call_protocol_debug` and `ProtocolDebugResponse`
+
+**Location:** `_client.py:536`, `models.py:89`
+
+`_call_protocol_debug` is private and has **no** facade method in `ProtocolValidationSuiteAPIs`, so it is unreachable through the public API. `ProtocolDebugResponse` exists only to serve it.
+
+**Why it matters:** Either incomplete work or dead code; both should be resolved.
+
+**Suggested fix:** Expose a public `protocol_debug(...)` method on the facade if intended, or remove `_call_protocol_debug` and `ProtocolDebugResponse` if not.
+
+---
+
+### S5. Local variable shadowing / reassigning `request` to a different message type
+
+**Location:** `_client.py:282-300`, `_client.py:415-425`
+
+`request` is built as one message type, used, then rebound to a different message type in the same scope (`Setup_Configurations` → `Request`; `Compile_Details` → `Run_Details`).
+
+**Why it matters:** Reusing one name for two distinct types hurts readability and defeats type inference.
+
+**Suggested fix:** Use distinct names, e.g. `setup_request` / `channel_request`, and `compile_request` / `run_request`.
+
+---
+
+### S6. Unused instance attribute `self._error_stream`
+
+**Location:** `_client.py:79`
+
+```python
+self._error_stream = subprocess.PIPE   # assigned, never read
+```
+
+`Popen` uses the literal `subprocess.PIPE` on the next line.
+
+**Suggested fix:** Remove the attribute.
+
+---
+
+### S7. `response` assigned but unused; channel-update success ignored
+
+**Location:** `_client.py:205`, `_client.py:300`, `_client.py:352`
+
+`Close_Server` and both `Update_*_Channels` calls capture a return value that is never inspected. Notably the channel-update `Success` is ignored, so a failed channel update still reports `"Successful."`.
+
+**Suggested fix:** Either check the returned `.Success` / `.Response_Data` and reflect it in the result, or drop the unused assignment.
+
+---
+
+### S8. `launch_server` returns `bool` but `close_server` returns `None` — asymmetric
+
+**Location:** `protocol_validation_suite_apis.py:28-38`
+
+`launch_server` forwards the client's bool (with no annotation); `close_server` drops the return.
+
+**Suggested fix:** Make the pair symmetric — return a status from `close_server` too, and annotate both.
+
+---
+
+### S9. Imports not grouped per PEP 8 / split model import
+
+**Location:** `_client.py:7-8` (third-party `grpc` interleaved with local `.stubs`); `protocol_validation_suite_apis.py:4-10` (`.models` imported in two statements); `_utils.py:1-3` (`os, json, re` not alphabetical).
+
+**Suggested fix:** Group imports as stdlib / third-party / local with blank lines between groups; consolidate the split `.models` import.
+
+---
+
+### S10. Inline/local imports instead of top-of-module
+
+**Location:** `_client.py:200-202`
+
+`Trigger` is imported inside `close_server` "to avoid circular imports," but `GRPC_pb2` is already imported at module top and used as `GRPC_pb2.Trigger` elsewhere (e.g. `_client.py:439`). The justification is false. Similarly `Debug_Configurations` is imported at top (`_client.py:20`) while every other message is namespaced via `GRPC_pb2.` — mixed styles.
+
+**Suggested fix:** Remove the local import and use `GRPC_pb2.Trigger`; standardize on the `GRPC_pb2.` namespace everywhere (drop the direct `Debug_Configurations` import).
+
+---
+
+### S11. `i3s_monitor_setup` unreachable `else` branch / duplicated body
+
+**Location:** `_client.py:588-590`
+
+`configurations` is typed `dict[str, Any] | str`; the `dict` and `str` branches are exhaustive. The "best-effort fallback" `else` is only reachable on a type-contract violation and duplicates the `dict` branch anyway.
+
+**Suggested fix:** Reduce to the two valid branches (`isinstance(..., str)` → passthrough; else `json.dumps`), or validate input and raise on unsupported types.
+
+---
+
+### S12. `handle_exceptions` name resolution is brittle and redundant
+
+**Location:** `_decorators.py:30-32`
+
+```python
+func_name = getattr(func, "__name__", None) or getattr(func, "__func__", None).__name__
+```
+
+If `func` has neither `__name__` nor `__func__`, the second `getattr` returns `None` and `.__name__` raises `AttributeError` at decoration time. Also, `functools.wraps` already provides the name.
+
+**Suggested fix:** Use `func.__name__` after `functools.wraps`, or read the name inside `wrapper` via `wrapper.__name__`; drop the fragile fallback chain.
+
+---
+
+### S13. `set_test_condition` redundant assignment
+
+**Location:** `_client.py:373`
+
+```python
+file_path = test_file_path   # pointless alias
+```
+
+**Suggested fix:** Use `test_file_path` directly and remove the alias.
+
+---
+
+### S14. `set_test_condition` always returns `True`
+
+**Location:** `_client.py:378`
+
+Returns hard-coded `True`; the only non-`True` outcome is an exception → `None` (via C6). The documented `bool` is really `True | None`.
+
+**Suggested fix:** Either let it raise on failure (return type becomes meaningful only if there is a real `False` path), or document that success is `True` and failure raises.
+
+---
+
+### S15. Facade docstring for `reset_interposer_board` names the wrong type
+
+**Location:** `protocol_validation_suite_apis.py:85`
+
+Arg documented as `SetupInterposerBoardRequest` but the parameter is `ResetInterposerBoardRequest`.
+
+**Suggested fix:** Correct the documented type to `ResetInterposerBoardRequest`.
+
+---
+
+### S16. `mass_compile_sequence` param name mismatch with docstring
+
+**Location:** `protocol_validation_suite_apis.py:141-147`
+
+Parameter is `requests`; the docstring `Args` calls it `request`.
+
+**Suggested fix:** Rename the docstring arg to `requests`.
+
+---
+
+### S17. Blank-line convention inside `models.py`
+
+**Location:** `models.py:88-89`
+
+Only one blank line between `I3SMonitorSetupRequest` and `ProtocolDebugResponse`; every other top-level class uses two (PEP 8).
+
+**Suggested fix:** Add the second blank line before `ProtocolDebugResponse`.
+
+---
+
+## Recommended fix order
+
+1. **C6** — stop the blanket swallow; it is hiding every other bug.
+2. **C1** — fix the `list[int]` → `repeated string` serialization crash.
+3. **C2** — return `report_details.Report_Folder_Path` (honor the `str` contract).
+4. **C3** — give `run_sequence` a structured, machine-checkable result.
+5. **C7, C13** — harden the launch/close/config lifecycle against `None`/uninitialized state.
+6. Remaining High (C8–C12), then Medium (S1–S17).

Protocol_Validation_Suite_APIs/__init__.py

@@ -0,0 +1,9 @@
+from .protocol_validation_suite_apis import ProtocolValidationSuiteAPIs
+from .models import CompileSequenceRequest, RunSequenceRequest, I3SMonitorSetupRequest
+
+__all__ = [
+    "ProtocolValidationSuiteAPIs",
+    "CompileSequenceRequest",
+    "RunSequenceRequest",
+    "I3SMonitorSetupRequest",
+]