From 969f4b43b664b79883a43297b954728de2cb745f Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Fri, 4 Sep 2026 00:17:23 +0300 Subject: [PATCH 1/2] Allow deferring the initial file listing --- README.md | 6 ++++++ docs/api.md | 5 +++++ pyquadcortex/device/device.py | 7 ++++++- pyquadcortex/protocol/client.py | 9 +++++++-- pyquadcortex/protocol/session.py | 13 ++++++++++++- tests/test_client.py | 17 +++++++++++++++++ tests/test_device.py | 9 ++++++--- tests/test_session.py | 20 +++++++++++++++++--- 8 files changed, 76 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 33c36cd..9163bd3 100644 --- a/README.md +++ b/README.md @@ -148,6 +148,12 @@ with protocol.connect() as qc: device requires, so what you get back is ready to use. As a context manager it also releases the device when the block ends; otherwise call `qc.close()`. +The default handshake also asks for the unit's full folder tree, which can keep +several hundred `FileMessage` pushes arriving after `connect()` returns. An app +that does not need an eager listing can use +`protocol.connect(initial_file_listing=False)`; `list_presets()` and the other +file APIs still fetch their data normally when called. + Closing tells the device the client is leaving, which is what Cortex Control does on quit. If you supplied your own transport and so own teardown yourself, send it with `qc.disconnect()` before you tear down. diff --git a/docs/api.md b/docs/api.md index a845644..6f982bc 100644 --- a/docs/api.md +++ b/docs/api.md @@ -93,6 +93,11 @@ outputs, and instrument tags likewise have readable names (`Input.RETURN_1`, Things worth knowing before you script against this: +- **The default connect eagerly enumerates folders.** On a populated unit that + means several hundred `FileMessage` pushes. Pass + `initial_file_listing=False` to either `protocol.connect()` or + `pyquadcortex.connect()` to defer that traffic; listing methods still fetch on + demand. - **Editing goes recall, change, save.** The device saves whatever is currently on the grid, so an edit means recalling the preset first. The methods above are built for that order; [docs/protocol.md](protocol.md) explains why. diff --git a/pyquadcortex/device/device.py b/pyquadcortex/device/device.py index dd8e22d..c20450e 100644 --- a/pyquadcortex/device/device.py +++ b/pyquadcortex/device/device.py @@ -232,7 +232,8 @@ def __repr__(self) -> str: def connect(*, timeout: float = 5.0, settle: float = 2.0, - handshake_patience: float = 30.0) -> Device: + handshake_patience: float = 30.0, + initial_file_listing: bool = True) -> Device: """Open a Quad Cortex over USB and return it as a :class:`Device`. Finds and opens the device, starts the transport, and performs the connect @@ -251,6 +252,9 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0, handshake_patience: total seconds to keep re-attempting the handshake while the unit is openable but silent. See :func:`pyquadcortex.protocol.connect`, which this passes through to. + initial_file_listing: whether to enumerate the full folder tree during + the handshake. Set false to defer that traffic until a listing is + requested explicitly. The model subscribes to the unit's pushes BEFORE the handshake runs, which is the only moment early enough to hear the handshake's own burst of state - @@ -274,5 +278,6 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0, state = DeviceState() client = protocol.connect(timeout=timeout, settle=settle, handshake_patience=handshake_patience, + initial_file_listing=initial_file_listing, before_handshake=state.listen_on) return Device(client, _owns_client=True, _state=state) diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 876114c..8a8b2f4 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -389,7 +389,8 @@ def remove_listener(self, listener): # this is the version captured on the wire. CC_VERSION = "4.0.1" - def _hello(self, timeout: float = 5.0, settle: float = 2.0): + def _hello(self, timeout: float = 5.0, settle: float = 2.0, + initial_file_listing: bool = True): """Perform the full connect handshake Cortex Control performs. Internal: :func:`pyquadcortex.protocol.connect` calls this for you, so a caller @@ -409,7 +410,9 @@ def _hello(self, timeout: float = 5.0, settle: float = 2.0): valid CC version). 3. ``Connection{connected: true}``. 4. A READ for each state type in ``_SUBSCRIBE_TYPES`` - this is the - subscription that makes the device start pushing that state. + subscription that makes the device start pushing that state. The + ``File`` READ is optional because it immediately enumerates the + entire folder tree rather than opening the push gate. Returns the echoed ResetCommsBuffers reply. After this, ``read_preset`` and the device's live-sync pushes work. @@ -438,6 +441,8 @@ def _hello(self, timeout: float = 5.0, settle: float = 2.0): self._t.send(pa.ModelRepoMessage(action=pa.MessageAction.READ)) self._t.send(pa.ConnectionMessage(connected=True)) for name in self._SUBSCRIBE_TYPES: + if name == "File" and not initial_file_listing: + continue self._t.send(registry.class_for(pa.CortexMessageType.Enum.Value(name))( action=pa.MessageAction.READ )) diff --git a/pyquadcortex/protocol/session.py b/pyquadcortex/protocol/session.py index 9103fbb..8652c01 100644 --- a/pyquadcortex/protocol/session.py +++ b/pyquadcortex/protocol/session.py @@ -81,6 +81,7 @@ def open_device(): def connect(*, timeout: float = 5.0, settle: float = 2.0, handshake_patience: float = 30.0, + initial_file_listing: bool = True, before_handshake=None) -> QuadCortex: """Open a Quad Cortex and return a connected, ready-to-use client. @@ -108,6 +109,12 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0, failing, which is why the default is 30. Each attempt restarts the full handshake (safe: it begins with a fresh session id). Set to 0 for the old single-attempt behaviour. + initial_file_listing: whether the handshake should immediately ask the + unit to enumerate its full folder tree. Keep the default for the + usual eager state burst; set this false when startup traffic matters + more than preloading listings. Explicit calls such as + :meth:`~pyquadcortex.protocol.client.QuadCortex.list_folders` still + work and fetch the listing on demand. before_handshake: optional ``callable(transport)``, called once with the started :class:`~pyquadcortex.protocol.transport.Transport` after it starts and before the handshake runs. This is the only way to @@ -141,7 +148,11 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0, while True: attempt += 1 try: - qc._hello(timeout=timeout, settle=settle) + qc._hello( + timeout=timeout, + settle=settle, + initial_file_listing=initial_file_listing, + ) break except TimeoutError: if time.monotonic() >= deadline: diff --git a/tests/test_client.py b/tests/test_client.py index e5deaed..91e7b5b 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -499,6 +499,23 @@ def test_hello_performs_full_connect_handshake(): ) +def test_hello_can_defer_only_the_initial_file_listing(): + canned = {"ResetCommsBuffersMessage": pa.ResetCommsBuffersMessage()} + qc = client.QuadCortex(FakeTransport(canned)) + + qc._hello(settle=0, initial_file_listing=False) + + subscription_names = { + type(message).__name__ + for message in qc._t.sent + if getattr(message, "action", None) == pa.MessageAction.READ + } + assert "FileMessage" not in subscription_names + assert "RecallPresetMessage" in subscription_names + assert "GeneralSettingsMessage" in subscription_names + assert "ModelRepoMessage" in subscription_names + + # -- ergonomics: no magic numbers at the call site ----------------------------- diff --git a/tests/test_device.py b/tests/test_device.py index 60cefc5..cfe60ef 100644 --- a/tests/test_device.py +++ b/tests/test_device.py @@ -351,16 +351,19 @@ def test_connect_hands_every_argument_to_the_protocol_layer(monkeypatch): openable-but-silent window. """ seen = _spy_on_protocol_connect(monkeypatch) - pyquadcortex.connect(timeout=1.5, settle=0.25, handshake_patience=45.0) + pyquadcortex.connect(timeout=1.5, settle=0.25, handshake_patience=45.0, + initial_file_listing=False) assert _without_the_hook(seen) == { - "timeout": 1.5, "settle": 0.25, "handshake_patience": 45.0} + "timeout": 1.5, "settle": 0.25, "handshake_patience": 45.0, + "initial_file_listing": False} def test_connect_passes_its_defaults_through_unchanged(monkeypatch): seen = _spy_on_protocol_connect(monkeypatch) pyquadcortex.connect() assert _without_the_hook(seen) == { - "timeout": 5.0, "settle": 2.0, "handshake_patience": 30.0} + "timeout": 5.0, "settle": 2.0, "handshake_patience": 30.0, + "initial_file_listing": True} def _spy_on_protocol_connect(monkeypatch): diff --git a/tests/test_session.py b/tests/test_session.py index 18d871c..03ba9c7 100644 --- a/tests/test_session.py +++ b/tests/test_session.py @@ -67,6 +67,17 @@ def test_connect_returns_a_handshaken_client(fake_stack): assert "ConnectionMessage" in kinds +def test_connect_can_defer_the_initial_file_listing(fake_stack): + qc = session.connect(settle=0, initial_file_listing=False) + t = FakeTransport.instances[0] + + assert not any(type(message).__name__ == "FileMessage" for message in t.sent) + assert any( + type(message).__name__ == "RecallPresetMessage" for message in t.sent + ) + qc.close() + + def test_connect_as_context_manager_releases_the_device(fake_stack): with session.connect(settle=0) as qc: assert isinstance(qc, client.QuadCortex) @@ -127,7 +138,8 @@ def test_before_handshake_runs_once_however_many_handshake_attempts_it_takes( """ attempts = {"n": 0} - def flaky_hello(self, timeout=5.0, settle=2.0): + def flaky_hello(self, timeout=5.0, settle=2.0, + initial_file_listing=True): attempts["n"] += 1 if attempts["n"] < 3: raise TimeoutError("no response for request_id=1") @@ -290,7 +302,8 @@ def stop(self, join_timeout=1.0): attempts = {"n": 0} - def flaky_hello(self, timeout=5.0, settle=2.0): + def flaky_hello(self, timeout=5.0, settle=2.0, + initial_file_listing=True): attempts["n"] += 1 if attempts["n"] < 3: raise TimeoutError("no response for request_id=1") @@ -322,7 +335,8 @@ def start(self): def stop(self, join_timeout=1.0): pass - def never_answers(self, timeout=5.0, settle=2.0): + def never_answers(self, timeout=5.0, settle=2.0, + initial_file_listing=True): raise TimeoutError("no response for request_id=1") monkeypatch.setattr(session, "open_device", lambda: QuietDevice()) From 68f2a35cafac339f55867fa7617980ad370ee388 Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Tue, 8 Sep 2026 21:53:36 +0300 Subject: [PATCH 2/2] fix: preserve eager listing defaults explicitly --- README.md | 2 +- changelog.md | 6 ++++++ docs/api.md | 5 +++-- docs/protocol.md | 5 +++++ pyquadcortex/protocol/client.py | 4 +++- pyquadcortex/protocol/session.py | 11 +++++++---- tests/test_client.py | 27 +++++++++++++++++---------- tests/test_session.py | 1 + 8 files changed, 43 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 04b25f0..8e8efa5 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ The default handshake also asks for the unit's full folder tree, which can keep several hundred `FileMessage` pushes arriving after `connect()` returns. An app that does not need an eager listing can use `protocol.connect(initial_file_listing=False)`; `list_presets()` and the other -file APIs still fetch their data normally when called. +file APIs still fetch on demand on a verified profile. Closing tells the device the client is leaving, which is what Cortex Control does on quit. If you supplied your own transport and so own teardown yourself, send it with diff --git a/changelog.md b/changelog.md index d8b2b27..54186e9 100644 --- a/changelog.md +++ b/changelog.md @@ -20,6 +20,12 @@ correction. ## Unreleased +### Initial file enumeration can be deferred + +Both connect layers accept `initial_file_listing=False`, omitting only the +handshake's eager `File` READ. The default remains eager, and listing operations +still fetch explicitly when called on a profile that verifies them. + ### The first hardware run of the profile seam, and what it corrected Run 2026-09-07 on Quad Cortex, CorOS 4.0.1 / d14e, straight after the seam diff --git a/docs/api.md b/docs/api.md index ef0fab6..937d785 100644 --- a/docs/api.md +++ b/docs/api.md @@ -97,8 +97,9 @@ Things worth knowing before you script against this: - **The default connect eagerly enumerates folders.** On a populated unit that means several hundred `FileMessage` pushes. Pass `initial_file_listing=False` to either `protocol.connect()` or - `pyquadcortex.connect()` to defer that traffic; listing methods still fetch on - demand. + `pyquadcortex.connect()` to defer that traffic. On a verified profile, + listing methods still fetch on demand; an unverified profile requires + `support=Support.EXPERIMENTAL` for those operations. - **Editing goes recall, change, save.** The device saves whatever is currently on the grid, so an edit means recalling the preset first. The methods above are built for that order; [docs/protocol.md](protocol.md) explains why. diff --git a/docs/protocol.md b/docs/protocol.md index cc166d7..7924051 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -516,6 +516,11 @@ type to clients that asked for it. `QuadCortex._SUBSCRIBE_TYPES` lists the set the library subscribes to, mirroring Cortex Control's burst. `RecallPreset` is the one that matters most (it is how a full preset is obtained), but the device appears to want the whole set before it considers the client fully connected. +The optional initial `File` READ makes this a 22-type burst by default or 21 +when deferred. A contributed CorOS 4.1.0 check on 2026-09-08 connected with the +21-type form and later enumerated all 586 folders explicitly under +`Support.EXPERIMENTAL`. Whether omitting `File` also opts out of later file +change broadcasts remains unmeasured. `QuadCortex._hello()`, which `pyquadcortex.protocol.connect()` runs for you, does the same thing with one deliberate difference: it does **not** issue a host diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 07fa98e..a91d653 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -564,7 +564,8 @@ def _hello(self, timeout: float = 5.0, settle: float = 2.0, 4. A READ for each state type in ``_SUBSCRIBE_TYPES`` - this is the subscription that makes the device start pushing that state. The ``File`` READ is optional because it immediately enumerates the - entire folder tree rather than opening the push gate. + entire folder tree. Whether it also subscribes later file changes + has not been measured. Returns the echoed ResetCommsBuffers reply. After this, ``read_preset`` and the device's live-sync pushes work. @@ -596,6 +597,7 @@ def _hello(self, timeout: float = 5.0, settle: float = 2.0, ) self._t.send(pa.ModelRepoMessage(action=pa.MessageAction.READ)) self._t.send(pa.ConnectionMessage(connected=True)) + assert "File" in self._SUBSCRIBE_TYPES for name in self._SUBSCRIBE_TYPES: if name == "File" and not initial_file_listing: continue diff --git a/pyquadcortex/protocol/session.py b/pyquadcortex/protocol/session.py index 05f9fac..11f72b0 100644 --- a/pyquadcortex/protocol/session.py +++ b/pyquadcortex/protocol/session.py @@ -264,10 +264,13 @@ def connect(*, timeout: float = 5.0, settle: float = 2.0, f"{pa.VersionMessage.DeviceType.Name(cls.DEVICE_TYPE)}, and the unit " f"says {pa.VersionMessage.DeviceType.Name(identity.device_type)}") qc = cls(transport, _owned_resources=owned, support=support) - _retry_until_patient(lambda: qc._hello( - timeout=timeout, settle=settle, - initial_file_listing=initial_file_listing), - deadline, handshake_patience) + def hello(): + return qc._hello( + timeout=timeout, settle=settle, + initial_file_listing=initial_file_listing, + ) + + _retry_until_patient(hello, deadline, handshake_patience) # Say goodbye BEFORE the transport and handle go away, since the send needs # a live transport. close() pops this list, so appending last runs it first. owned.append(qc.disconnect) diff --git a/tests/test_client.py b/tests/test_client.py index 0086211..93c99f1 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -487,6 +487,10 @@ def test_hello_performs_full_connect_handshake(): if isinstance(m, pa.RecallPresetMessage) and m.action == pa.MessageAction.READ ] assert recall_reads + assert any( + isinstance(m, pa.FileMessage) and m.action == pa.MessageAction.READ + for m in sent + ), "the default retains eager File enumeration" # ModelRepo READ is present (empirically required to open the push gate). assert any( isinstance(m, pa.ModelRepoMessage) and m.action == pa.MessageAction.READ @@ -501,19 +505,22 @@ def test_hello_performs_full_connect_handshake(): def test_hello_can_defer_only_the_initial_file_listing(): canned = {"ResetCommsBuffersMessage": pa.ResetCommsBuffersMessage()} - qc = client.QuadCortex(FakeTransport(canned)) + eager = client.QuadCortex(FakeTransport(canned)) + deferred = client.QuadCortex(FakeTransport(canned)) - qc._hello(settle=0, initial_file_listing=False) + eager._hello(settle=0) + deferred._hello(settle=0, initial_file_listing=False) - subscription_names = { - type(message).__name__ - for message in qc._t.sent + eager_reads = [ + type(message).__name__ for message in eager._t.sent if getattr(message, "action", None) == pa.MessageAction.READ - } - assert "FileMessage" not in subscription_names - assert "RecallPresetMessage" in subscription_names - assert "GeneralSettingsMessage" in subscription_names - assert "ModelRepoMessage" in subscription_names + ] + deferred_reads = [ + type(message).__name__ for message in deferred._t.sent + if getattr(message, "action", None) == pa.MessageAction.READ + ] + assert eager_reads.count("FileMessage") == 1 + assert deferred_reads == [name for name in eager_reads if name != "FileMessage"] # -- ergonomics: no magic numbers at the call site ----------------------------- diff --git a/tests/test_session.py b/tests/test_session.py index 4f3db1a..c443b66 100644 --- a/tests/test_session.py +++ b/tests/test_session.py @@ -85,6 +85,7 @@ def test_connect_returns_a_handshaken_client(fake_stack): kinds = [type(m).__name__ for m in t.sent] assert "ResetCommsBuffersMessage" in kinds assert "ConnectionMessage" in kinds + assert "FileMessage" in kinds def test_connect_can_defer_the_initial_file_listing(fake_stack):