Define validateReady only on PhysicalDevice

Problem: validateReady was defined twice, as a no-op on Capability and for
real on PhysicalDevice, with the MRO picking the right one. The no-op was
never reached by any driver in the library -- PhysicalDevice sits at MRO
index 2 and Capability at index 10, so it was shadowed everywhere it
mattered. It only ran for a capability mixed into something that is not a
device, and there it silently skipped the check. That also put a device
lifecycle concept in capabilities.py, which has no business defining one.

Solution: drop the fallback and keep the single definition on PhysicalDevice,
where the state machine lives; capabilities.py only calls it. Anything
hosting a capability without being a PhysicalDevice now has to answer for
readiness itself, which is the honest contract: every capability's docstring
already says to combine it with a PhysicalDevice.

The three test stubs that stand in for a device -- _RecordingAnalogDevice and
_FailingAnalogDevice, and _MinimalLockIn in testSR830 -- supply it, as they
already supply the hooks. The trade-off is the failure mode for a capability
mixed into a non-device: previously no validation at all, now an
AttributeError naming validateReady.

Note that delegating from Capability.validateReady to PhysicalDevice's would
not have worked: it is unreachable from any driver, and on a bare mixin it
raises AttributeError on the missing state attribute.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dccote

CHANGELOG.md

@@ -59,9 +59,10 @@ API changes can land even when the minor version is unchanged.
   `AttributeError: 'NoneType' object has no attribute ...` on a port that was never
   opened, or -- on a debug device -- answered as though the hardware had done it and
   posted a `did*` claiming success. The check runs before the `will` is posted, so a
-  refused call announces nothing. `PhysicalDevice.validateReady` is the real check;
-  `Capability.validateReady` is a no-op behind it in the MRO so a mixin can still be
-  exercised on its own. Methods that only report what a model supports
+  refused call announces nothing. `validateReady` is defined once, on
+  `PhysicalDevice`, where the device lifecycle belongs; `capabilities.py` only calls
+  it, so a class mixing in a capability without being a `PhysicalDevice` answers for
+  readiness itself rather than silently skipping the check. Methods that only report what a model supports
   (`supportedInputSources`, `supportedSensitivities`, `supportedTimeConstants`,
   `supportedTriggerSources`, `outletCount`) are exempt via `requiresReady=False`,
   since a UI populates its menus before connecting.

CLAUDE.md

@@ -68,7 +68,7 @@ All families **use interface-segregated capability mixins** instead of one fat b
 - An operation that changes the instrument posts `will<Stem>` before and `did<Stem>` after; a **read (`doGet*`, `doReadStream`) posts only `did<Stem>`**, to keep hot paths (a voltage sampled in a loop) at one notification instead of two. `Spectrometer.getSpectrum` is the one read that keeps a `will`, because acquiring takes an integration time.
 - **`did*` is posted whether the operation succeeded or not**, so a `will*` is always followed by its `did*` and there is no separate failure member to pair up. The **exception is still re-raised untouched** — a driver's exception type is part of its contract (`SR830Device` raises `ValueError` for an out-of-range Aux voltage, and callers rely on it). An observer decides what to do from the payload; a caller still sees the exception.
 - `user_info` is a dict of the public method's arguments by name, plus `"result"` and `"error"`, exactly one of which is non-None. Test `user_info["error"]`, not the member, to tell success from failure.
-- **The device must be initialized.** `@notifies` calls `validateReady()` first, which raises `PhysicalDevice.NotInitialized` unless the state is `Ready`, naming the operation, the class and the actual state. It runs *before* the `will` is posted, since nothing was attempted, so a guarded call posts nothing at all. `PhysicalDevice.validateReady` is the real check and sits ahead of `Capability.validateReady` (a no-op) in a driver's MRO, so a capability exercised bare in a test still works. Methods that only report what a model supports (`supported*`, `outletCount`) pass `requiresReady=False`, because a UI populates its menus before connecting.
+- **The device must be initialized.** `@notifies` calls `validateReady()` first, which raises `PhysicalDevice.NotInitialized` unless the state is `Ready`, naming the operation, the class and the actual state. It runs *before* the `will` is posted, since nothing was attempted, so a guarded call posts nothing at all. `validateReady` is defined once, on `PhysicalDevice`, where the lifecycle lives; `capabilities.py` only calls it. A class that mixes in a capability without being a `PhysicalDevice` must therefore answer for readiness itself — the test stubs that stand in for a device do exactly that. Methods that only report what a model supports (`supported*`, `outletCount`) pass `requiresReady=False`, because a UI populates its menus before connecting.
 - **Capabilities related by inheritance share one enum**, so `notification` is literally the same object on all of them and their members are interchangeable: `AnalogInputCapability`, `AnalogOutputCapability`, `AnalogIOCapability` and `AnalogInputStreamCapability` all post `AnalogNotification`; the digital trio posts `DigitalNotification`. This matters because members are keyed by identity — two same-named members in two enums would never cross-fire, so an observer would otherwise have to know whether a device mixed in the combined capability or the plain one.
 - Members are keyed by enum identity, not by their string value, so same-named members in two enums never cross-fire — which is exactly why the sharing above is necessary rather than cosmetic.
 - Composed hooks nest: `acquireWaveform` posts its own pair plus the pairs of the `configureStream` / `startStream` / `readStream` / `stopStream` calls its default implementation makes.

hardwarelibrary/capabilities.py

@@ -65,6 +65,10 @@ def notifies(did, will=None, requiresReady=True):
     observer should hear nothing at all. Pass requiresReady=False for a method
     that only reports what the instrument supports, which a UI may legitimately
     ask before connecting.
+
+    validateReady is PhysicalDevice's, which is where the device lifecycle lives;
+    a capability is meant to be mixed alongside one, so anything else hosting a
+    capability must answer for readiness itself.
     """
     def decorator(method):
         signature = inspect.signature(method)
@@ -114,17 +118,6 @@ class Capability(ABC):
     # allCapabilities() also enumerates every notification the library defines.
     notification = None
 
-    def validateReady(self, operation=None):
-        """Confirm the device is initialized before an operation touches it.
-
-        A mixin standing on its own has no device state to check, so this does
-        nothing. PhysicalDevice sits ahead of every capability in a driver's MRO
-        and overrides it with the real check, which is the one that runs on real
-        hardware; this fallback exists so a capability can still be exercised
-        bare, as the tests do.
-        """
-        pass
-
 
 # ---------------------------------------------------------------------------
 # Laser source capabilities

hardwarelibrary/tests/testCapabilities.py

@@ -157,6 +157,10 @@ class _RecordingAnalogDevice(AnalogIOCapability):
     def __init__(self):
         self.calls = []
 
+    def validateReady(self, operation=None):
+        """Stands in for a device that is open and ready."""
+        pass
+
     def doGetAnalogVoltage(self, channel):
         self.calls.append(("doGetAnalogVoltage", channel))
         return 1.5
@@ -327,6 +331,10 @@ class _FailingAnalogDevice(AnalogIOCapability):
     class Failure(RuntimeError):
         pass
 
+    def validateReady(self, operation=None):
+        """Stands in for a device that is open and ready."""
+        pass
+
     def doGetAnalogVoltage(self, channel):
         raise self.Failure("no hardware")
 

hardwarelibrary/tests/testSR830.py

@@ -233,6 +233,10 @@ class _MinimalLockIn(PhaseLockedDetectionCapability, TriggerCapability):
     the base-class optional hooks and the base getDemodulatedValues are exercised
     (SR830Device overrides all of these)."""
 
+    def validateReady(self, operation=None):
+        """Stands in for a device that is open and ready."""
+        pass
+
     def doGetInPhaseVoltage(self):
         return 0.1