plesty-sdk 0.3.5.dev1__tar.gz → 0.3.6__tar.gz

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.3.6}/CHANGELOG.md

@@ -2,6 +2,108 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com).
 
+## [0.3.6] — 2026-09-03
+
+Everything the scaffolds generate now passes the gates the scaffolds ask for.
+Two generated files failed a check the SDK itself enforces — a field-test
+client with an import nothing used, and entry points on an event loop that
+Python 3.16 will not give them — and the version picker no longer strands a
+reader on a release it cannot leave. Generated projects pin `plesty-lib>=0.3.6`.
+
+### Fixed
+- Generated device and experiment entry points start through
+  `plesty.lib.service.run_server` instead of a bare `asyncio.run`. The bare
+  call worked on Windows only because importing `plesty.lib.service` installed
+  a global event-loop policy — deprecated in Python 3.14 (two warnings per
+  server start on benches already there) and removed in 3.16, where the entry
+  point would get a `ProactorEventLoop` and fail inside pyzmq for want of
+  `add_reader`. The `plesty-lib` pin floor moves to 0.3.6, the first release
+  carrying `run_server`. Existing modules keep working on 3.14 and 3.15 and
+  pick the swap up when they regenerate.
+- `plesty init field-test` no longer writes a client whose imports fail the
+  module's own lint gate. A module reached through its `DocDevice` — or through
+  any construction taking no arguments — gets a bare factory, and the generated
+  `tests/field_test_client.py` imported `functools.partial` anyway: F401, so
+  `plesty check` could not pass on a module that had just been field-tested.
+  The import is now emitted only in the branch that calls `partial`. Both
+  branches are linted in the tests; neither was before, because every fixture
+  probed into the "no hardware-free construction" path.
+  Generating against released 0.3.3 has a worse form of the same block — it
+  emits the `partial` import but not the device import, leaving `SPAWN_FACTORY`
+  an undefined name (F821). Add the `from plesty.<module> import <factory>`
+  line by hand, or regenerate once this ships.
+- The version picker no longer offers a version the reader cannot switch back
+  out of. A release built before the Read-the-Docs theme has no sidebar for the
+  picker to mount on and cannot be stamped, yet the manifest still listed it —
+  on the SDK's own docs, selecting 0.1 stranded the reader. The manifest now
+  advertises only releases that carry the picker; such a release stays
+  published and reachable at its own URL, and `/releases/` still redirects to
+  the newest one that exists. Stamping consequently runs before the manifest is
+  written, so the manifest sees the final state of every tree.
+- A module with no releases rendered a dropdown holding a single entry. The
+  picker now appears only when there is something to pick between.
+
+## [0.3.5] — 2026-08-24
+
+Documentation gains a version picker, and the two things standing between it
+and the published sites are fixed: the docs-deploy gate had been skipped since
+2026-08-21 behind a failing test collection, and releases built before the
+picker existed had no way back to the current docs.
+
+### Added
+- Every module's documentation carries a **version picker** in the sidebar.
+  Each module already deployed `latest/` from its default branch and
+  `releases/<major>.<minor>/` from each tag, but nothing linked them: a reader
+  on the release docs could not reach any other version. The picker is fed by
+  `versions.json`, fetched at page load rather than baked in — a page built
+  months ago cannot know which versions exist today. Switching versions keeps
+  the current page when the target has it, and falls back to that version's
+  index when it does not (pages come and go between releases). A deployment
+  without a manifest — a local `plesty docs serve` preview — renders no picker
+  at all.
+
+### Fixed
+- The version picker is no longer a one-way trip. Releases published before it
+  existed are never rebuilt, so switching to one landed the reader on pages
+  with no picker and no way back. Each deploy now stamps the picker's two
+  assets and the tags referencing them into any release tree that lacks them.
+  Only the `<head>` gains anything — the prose, the API reference and the
+  stylesheets a historical release was built with are untouched, which is why
+  the picker's styling moved out of `plesty-hub.css` into its own
+  `plesty-versions.css`. Idempotent, so re-running over a stamped tree does
+  nothing. A release predating the Read-the-Docs theme (plesty-sdk 0.1) has no
+  sidebar to mount on and is skipped.
+- The test suite no longer fails to collect in CI. `plesty-lib` is declared in
+  a `dev` dependency group: `tests/test_mock_test_scaffold.py` drives the
+  mock-test scaffold against a real `plesty.lib.sim.demo_device.DemoDevice`,
+  which it subclasses and runs, but nothing installed the library on a runner —
+  so `hub-check` had been failing with `ModuleNotFoundError: No module named
+  'plesty.lib'`, which in turn skipped `hub-deploy-docs` and froze the
+  published documentation. It is a group rather than a runtime dependency:
+  installing plesty-sdk must not pull the library it scaffolds modules for.
+- `versions.json` entries were origin-absolute (`"/0.3/"`), so they resolved
+  against the host rather than the module root, and the `releases/` redirect
+  stub built from them has been broken since it was written — on
+  docs.plesty.net it pointed at `docs.plesty.net/0.3/`. The manifest moves to
+  the module root, lists `latest` alongside the releases, and its URLs are
+  relative to that root, which is `/<slug>/` on docs.plesty.net and
+  `/<group>/<project>/` on GitLab Pages.
+
+### Changed
+- Both deploy modes rewrite the manifest, not only `--release`. This is what
+  gives a module that has never been tagged a picker, and what migrates
+  branches deployed by an older SDK — including their `.gitlab-ci.yml`, which
+  was previously written once at branch creation and never updated again.
+- The Pages job publishes the whole `html/` tree instead of `html/latest`, so
+  the releases the picker lists are reachable there too, and `html/index.html`
+  redirects the Pages root to `latest/`. The layout now matches what
+  docs.plesty.net already serves, so one picker runs unchanged on both.
+  **Deep links to `plesty.gitlab.io/<group>/<project>/<page>.html` move under
+  `/latest/`**; docs.plesty.net URLs are unaffected. The reference link
+  `plesty check` prints on a failing gate followed that move, so it now points
+  at docs.plesty.net — the site readers are sent to, and the one whose path is
+  independent of how Pages lays the tree out.
+
 ## [0.3.5.dev1] — 2026-08-21
 
 Development pre-release: the tutorial needs the pin option before 0.3.5 is

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-sdk
-Version: 0.3.5.dev1
+Version: 0.3.6
 Summary: Command-line application for developing Python modules compliant with the Plesty standard.
 Author: Plesty Development Team, Yunshuang Yuan, Christopher Borchers, fvrehlinger, Maximilian Heller, Michael Zopf
 License-Expression: LGPL-3.0-or-later

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.3.6}/docs/commands/check.md

@@ -146,7 +146,7 @@ failures and their guidance always print:
     Error: [Coverage] total coverage 62% below threshold
     This gate verifies: the pytest suite passes with at least 80% line coverage.
     How to fix: Reproduce with 'uv run pytest --cov=plesty' and add tests ...
-    Reference: https://plesty.gitlab.io/core/plesty-sdk/commands/check.html
+    Reference: https://docs.plesty.net/plesty-sdk/latest/commands/check.html
 ```
 
 ## Examples

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.3.6}/gl-secret-detection-report.json

@@ -7,7 +7,7 @@
       "vendor": {
         "name": "GitLab"
       },
-      "version": "7.38.1"
+      "version": "7.39.0"
     },
     "scanner": {
       "id": "gitleaks",
@@ -19,19 +19,19 @@
       "version": "8.30.1"
     },
     "type": "secret_detection",
-    "start_time": "2026-08-21T18:31:49",
-    "end_time": "2026-08-21T18:31:49",
+    "start_time": "2026-09-03T08:02:36",
+    "end_time": "2026-09-03T08:02:36",
     "status": "success",
     "observability": {
       "events": [
         {
           "event": "collect_secrets_analyzer_scan_metrics_from_pipeline",
-          "time_s": 0.480570925,
+          "time_s": 0.448937143,
           "exit_code": 0,
           "git_strategy": "FetchShallow",
-          "repo_size_kb": 468,
+          "repo_size_kb": 503,
           "commit_count": 1,
-          "bytes_scanned": 136,
+          "bytes_scanned": 415,
           "pipeline_type": "Tag"
         },
         {
@@ -40,7 +40,7 @@
           "passthrough_types": null,
           "passthrough_count": 0,
           "passthrough_auth_used": false,
-          "rules_version": "0.25.0"
+          "rules_version": "0.25.1"
         }
       ]
     }

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.3.6}/plesty/sdk/assets/check/guidance.yaml

@@ -1,6 +1,8 @@
 # Per-gate failure guidance echoed by `plesty check` (issue sdk#26).
 # Keys match the gate keys used in check_command; text is plain CLI prose.
-docs_url: https://plesty.gitlab.io/core/plesty-sdk/commands/check.html
+# docs.plesty.net, not the Pages mirror: it is the site readers are sent to,
+# and its /<slug>/latest/ path is unaffected by how Pages lays the tree out.
+docs_url: https://docs.plesty.net/plesty-sdk/latest/commands/check.html
 
 gates:
   metadata:

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.3.6}/plesty/sdk/assets/docs-build-gitlab-ci.yml

@@ -4,7 +4,7 @@ pages:
   stage: deploy
   rules:
     # The gate for creating the job, not a selector of what is published —
-    # `publish: html/latest` below uploads the whole directory. exists
+    # `publish: html` below uploads the whole directory. exists
     # matches FILE globs: the bare directory path "html/latest/" stopped
     # matching on gitlab.com between 2026-07-21 and 2026-08-10, every
     # docs-build pipeline failed with "no jobs", and Pages froze while the
@@ -14,4 +14,8 @@ pages:
   script:
     - echo "Serving documentation on GitLab pages..."
   pages:
-    publish: html/latest
+    # The whole tree, not just html/latest: the sidebar version picker needs
+    # versions.json and the releases/ it lists to be reachable from the same
+    # site. html/index.html forwards the Pages root to latest/, and the layout
+    # then matches docs.plesty.net, where the same picker runs unchanged.
+    publish: html

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.3.6}/plesty/sdk/assets/hub-theme/plesty-hub.css

@@ -24,6 +24,8 @@
 
 /* The sidebar header keeps the stock Read-the-Docs styling. */
 
+/* The version picker styles itself from plesty-versions.css. */
+
 /* Schema shields → soft rounded pills. */
 .rst-content .sd-badge {
   border-radius: 999px;

plesty_sdk-0.3.6/plesty/sdk/assets/hub-theme/plesty-versions.css

@@ -0,0 +1,49 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Plesty Development Team
+ * SPDX-FileContributor: Yunshuang Yuan
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ *
+ * Styling for the sidebar version picker (plesty-versions.js).
+ *
+ * Separate from plesty-hub.css because it is also stamped into release docs
+ * built before the picker existed. Those trees carry their own copy of
+ * plesty-hub.css, and replacing it would change how a historical page looks
+ * beyond adding the dropdown; dropping one more file in beside it does not.
+ */
+
+/* Sits at the foot of the sidebar header, under the search box. Added by the
+ * script, so a deployment without a versions.json shows no empty slot. */
+.wy-side-nav-search .plesty-versions {
+  margin: 0.75rem 0 0;
+  text-align: left;
+}
+.wy-side-nav-search .plesty-versions label {
+  display: block;
+  margin-bottom: 0.3rem;
+  color: #d9d9d9;
+  font-size: 80%;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+.wy-side-nav-search .plesty-versions select {
+  width: 100%;
+  padding: 0.3rem 0.5rem;
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 4px;
+  background: rgba(0, 0, 0, 0.2);
+  color: #fff;
+  font-size: 90%;
+  cursor: pointer;
+}
+.wy-side-nav-search .plesty-versions select:focus {
+  /* Plesty cyan, spelled out: the historical trees this file is stamped into
+     carry a plesty-hub.css from before the custom property existed. */
+  border-color: #0891b2;
+  outline: none;
+}
+/* The dropdown list itself renders in the OS palette, not the sidebar's —
+   without this the options are white-on-white on most platforms. */
+.wy-side-nav-search .plesty-versions option {
+  color: #404040;
+  background: #fff;
+}

plesty_sdk-0.3.6/plesty/sdk/assets/hub-theme/plesty-versions.js

@@ -0,0 +1,110 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Plesty Development Team
+ * SPDX-FileContributor: Yunshuang Yuan
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ *
+ * Version picker for the Read-the-Docs sidebar.
+ *
+ * Every module is deployed as a tree of independently built docs — `latest/`
+ * from the default branch, `releases/<major>.<minor>/` from each tag — under
+ * one module root, and `versions.json` at that root lists them. A page built
+ * months ago cannot know which versions exist today, so the list is read at
+ * page load rather than baked in at build time.
+ *
+ * The module root is not derivable from the URL: docs.plesty.net serves the
+ * tree at /<slug>/ and GitLab Pages at /<group>/<project>/. It is derived
+ * from this script's own location instead — the file is always at
+ * <docs-root>/_static/plesty-versions.js, and `data-root-prefix` (set by
+ * sphinx_builder) is the hop from the docs root up to the module root.
+ */
+(() => {
+  // Read synchronously: document.currentScript is null once the DOM is ready.
+  const script = document.currentScript;
+  if (!script) return;
+  const rootPrefix = script.dataset.rootPrefix;
+  const current = script.dataset.version || "latest";
+  if (!rootPrefix) return;
+
+  const docsRoot = new URL("../", script.src);
+  const moduleRoot = new URL(rootPrefix, docsRoot);
+  // Page path within this version's docs, carried across when the target
+  // version has the same page.
+  const pagePath = decodeURIComponent(location.href.slice(docsRoot.href.length));
+
+  const label = (version) =>
+    version === "latest" ? "latest (development)" : version;
+
+  /* Navigate to `path` under `target`, falling back to the target's index
+     when the page does not exist there — pages come and go between versions,
+     and a picker that lands on a 404 is worse than one that lands on a
+     landing page. A HEAD request that cannot run at all (file:// origin)
+     falls back the same way. */
+  const goTo = async (target, path) => {
+    const home = new URL(target, moduleRoot);
+    if (!path) {
+      location.assign(home);
+      return;
+    }
+    const exact = new URL(path, home);
+    try {
+      const response = await fetch(exact, { method: "HEAD" });
+      location.assign(response.ok ? exact : home);
+    } catch {
+      location.assign(home);
+    }
+  };
+
+  const render = (versions) => {
+    const container = document.querySelector(".wy-side-nav-search");
+    if (!container) return;
+
+    const picker = document.createElement("div");
+    picker.className = "plesty-versions";
+
+    const caption = document.createElement("label");
+    caption.textContent = "Version";
+    caption.htmlFor = "plesty-version-select";
+    picker.appendChild(caption);
+
+    const select = document.createElement("select");
+    select.id = "plesty-version-select";
+    for (const entry of versions) {
+      const option = document.createElement("option");
+      option.value = entry.url;
+      option.textContent = label(entry.version);
+      option.selected = entry.version === current;
+      select.appendChild(option);
+    }
+    // The running version is missing from versions.json when this build has
+    // not been indexed yet (a local preview, a tag mid-deploy). Show it so the
+    // picker never reads as if the reader were somewhere else.
+    if (!versions.some((entry) => entry.version === current)) {
+      const option = document.createElement("option");
+      option.textContent = label(current);
+      option.selected = true;
+      option.disabled = true;
+      select.insertBefore(option, select.firstChild);
+    }
+    select.addEventListener("change", () => goTo(select.value, pagePath));
+    picker.appendChild(select);
+
+    // Below the search box, so the picker does not push the search field out
+    // of its usual place under the logo.
+    container.appendChild(picker);
+  };
+
+  const ready = (run) =>
+    document.readyState === "loading"
+      ? document.addEventListener("DOMContentLoaded", run)
+      : run();
+
+  fetch(new URL("versions.json", moduleRoot))
+    .then((response) => (response.ok ? response.json() : null))
+    .then((versions) => {
+      // Nothing to pick between — no manifest (a local `plesty docs serve`
+      // preview), or a module with no releases yet, whose manifest holds only
+      // `latest`. A dropdown with one entry is furniture, not navigation.
+      if (Array.isArray(versions) && versions.length > 1) ready(() => render(versions));
+    })
+    .catch(() => {});
+})();

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.3.6}/plesty/sdk/assets/templates/template/plesty/{{module_name}}/{% if project_type in ['device', 'experiment'] %}__main__.py{% endif %}.jinja

@@ -4,9 +4,8 @@
 """Entry point for running the {{ module_name | replace('_', ' ') }} {{ project_type }} as a standalone process."""
 {% if project_type == 'device' %}
 import argparse
-import asyncio
 
-from plesty.lib.service import build_server
+from plesty.lib.service import build_server, run_server
 from plesty.lib.utils import EnvSettings
 
 from .device import Device
@@ -64,17 +63,21 @@ async def main() -> None:  # pragma: no cover
 
 if __name__ == "__main__":  # pragma: no cover
     try:
-        asyncio.run(main())
+        # Not a bare asyncio.run: pyzmq needs a loop with add_reader, which on
+        # Windows is the selector loop and not the default one. run_server asks
+        # for it explicitly — the loop policy that used to arrange it process-wide
+        # is deprecated in Python 3.14 and gone in 3.16.
+        run_server(main())
     except KeyboardInterrupt:
         print("Server stopped by user.")
 {% elif project_type == 'experiment' %}
 import argparse
-import asyncio
 from pathlib import Path
 from typing import Optional
 
 from plesty.lib.device.composite_device import CompositeDevice
 from plesty.lib.experiment import RigNotReadyError, connect_rig
+from plesty.lib.service import run_server
 from plesty.lib.utils.config import load_yaml
 
 from .experiment import Experiment
@@ -200,7 +203,10 @@ async def main() -> None:  # pragma: no cover
 
 if __name__ == "__main__":  # pragma: no cover
     try:
-        asyncio.run(main())
+        # The rig's clients are pyzmq sockets, so this run needs the same loop
+        # a device server does — see run_server. A bare asyncio.run gets the
+        # Windows default one, which has no add_reader, from Python 3.16 on.
+        run_server(main())
     except RigNotReadyError as error:
         # The diagnosis is already out (connect_rig printed and logged it);
         # this only says how the process ended, and with a non-zero status.