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

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

@@ -2,6 +2,22 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com).
 
+## [0.3.5.dev1] — 2026-08-21
+
+Development pre-release: the tutorial needs the pin option before 0.3.5 is
+ready to be called finished.
+
+### Added
+- `plesty init --lib-version VERSION` pins `plesty-lib` to what the caller
+  names instead of to the newest release on PyPI, and skips the lookup. A bare
+  version becomes a lower bound (`0.3.5.dev3` → `>=0.3.5.dev3`); a complete
+  specifier is written as given (`==0.4.0`, `>=0.3.5.dev3,<0.4`). One that PEP
+  440 cannot read is refused at the command line, before a directory is
+  created. For the tutorial: a lesson quoting a `pyproject.toml` and the file
+  its reader ends up with have to keep saying the same thing however far the
+  library has moved since the page was written — and a scaffold on an
+  air-gapped machine now pins what was asked for rather than a fallback.
+
 ## [0.3.4] — 2026-08-21
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-sdk
-Version: 0.3.4
+Version: 0.3.5.dev1
 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.4 → plesty_sdk-0.3.5.dev1}/docs/commands/init.md

@@ -41,6 +41,7 @@ name, so `plesty-foo-bar` → `foo_bar` without needing `--name`.
 | `--author` | `John Doe` | Author name written into `pyproject.toml` and `REUSE.toml` |
 | `--email` | `john.doe@example.com` | Author email written into `pyproject.toml` |
 | `--standard` | `pixel` | Compliance standard for the generated CI pipeline: `pixel`, `nebula`, or `quantum`. A fresh scaffold is a prototype, so CI starts at `pixel`; bump it alongside your releases. |
+| `--lib-version` | newest on PyPI | Pin `plesty-lib` to this version instead of looking it up. A bare version becomes a lower bound (`0.3.5.dev3` → `>=0.3.5.dev3`); a complete specifier is written as given (`==0.4.0`, `'>=0.3.5.dev3,<0.4'`). PyPI is not consulted, so the scaffold is reproducible. |
 | `--no-ci` | off | Skip generating `.gitlab-ci.yml` entirely. |
 
 ## Directory rules
@@ -126,7 +127,17 @@ The `pyproject.toml` is pre-configured with:
   no route to PyPI the pin falls back to `PLESTY_LIB_VERSION` in
   `plesty/sdk/commands/init.py`, the library the templates are written against.
   The pin is never lower than that floor: the scaffold uses that library's
-  operation kinds and rig start-up, and an older one would not run it
+  operation kinds and rig start-up, and an older one would not run it.
+  `--lib-version` overrides all of that and skips the lookup — for a tutorial,
+  whose lesson text and reader's `pyproject.toml` have to keep agreeing however
+  far the library has moved since the page was written:
+
+  ```bash
+  plesty init experiment --name scan_exp --lib-version 0.3.5.dev3
+  #   → "plesty-lib>=0.3.5.dev3"
+  plesty init experiment --name scan_exp --lib-version '>=0.3.5.dev3,<0.4'
+  #   → "plesty-lib>=0.3.5.dev3,<0.4"
+  ```
 - `pytest`, `pytest-cov`, `mypy`, and `plesty-sdk` under `[dependency-groups] dev`
   (included automatically by `uv run` — no `--extra dev` needed)
 - Sphinx docs settings under `[tool.plesty.docs]`

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

@@ -19,19 +19,19 @@
       "version": "8.30.1"
     },
     "type": "secret_detection",
-    "start_time": "2026-08-21T18:16:41",
-    "end_time": "2026-08-21T18:16:41",
+    "start_time": "2026-08-21T18:31:49",
+    "end_time": "2026-08-21T18:31:49",
     "status": "success",
     "observability": {
       "events": [
         {
           "event": "collect_secrets_analyzer_scan_metrics_from_pipeline",
-          "time_s": 0.267080436,
+          "time_s": 0.480570925,
           "exit_code": 0,
           "git_strategy": "FetchShallow",
-          "repo_size_kb": 503,
+          "repo_size_kb": 468,
           "commit_count": 1,
-          "bytes_scanned": 163,
+          "bytes_scanned": 136,
           "pipeline_type": "Tag"
         },
         {

{plesty_sdk-0.3.4 → plesty_sdk-0.3.5.dev1}/plesty/sdk/assets/templates/template/pyproject.toml.jinja

@@ -16,9 +16,9 @@ dependencies = [
   # plesty.lib.utils.config (which load_config() below uses), the operation
   # kinds @expose_to_api declares and the field test drives, and the rig
   # start-up connect_rig()/preflight(). Pinned to the newest library published
-  # when this project was scaffolded; a .devN bound is also what makes a
-  # pre-release resolvable at all.
-  "plesty-lib>={{ plesty_lib_version }}",
+  # when this project was scaffolded, or to whatever `plesty init --lib-version`
+  # asked for; a .devN bound is also what makes a pre-release resolvable at all.
+  "plesty-lib{{ plesty_lib_specifier }}",
 ]
 
 [tool.plesty]

{plesty_sdk-0.3.4 → plesty_sdk-0.3.5.dev1}/plesty/sdk/commands/init.py

@@ -21,6 +21,7 @@ from pathlib import Path
 import click
 import copier
 import yaml
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
 from packaging.version import InvalidVersion, Version
 
 from plesty.sdk.commands.field_test import scaffold_field_test
@@ -93,6 +94,50 @@ def _parse_version(version: str) -> Version | None:
         return None
 
 
+def lib_specifier(requested: str | None = None) -> str:
+    """Return the version specifier to write after ``plesty-lib`` in pyproject.
+
+    Without *requested* the pin follows PyPI (:func:`resolve_lib_version`).
+    With it, the caller decides and no lookup happens — a tutorial pins the
+    library its lesson text was written against, so the page and the file the
+    reader ends up with keep saying the same thing however far the library has
+    moved since; an air-gapped machine gets the same determinism.
+
+    Args:
+        requested: A bare version (``"0.3.5.dev3"`` → ``">=0.3.5.dev3"``) or a
+            complete specifier, which is taken as written
+            (``"==0.4.0"``, ``">=0.3.5.dev3,<0.4"``).
+
+    Returns:
+        The specifier, leading operator included.
+
+    Raises:
+        click.ClickException: If *requested* is neither a version nor a
+            specifier PEP 440 can read.
+    """
+    if requested is None:
+        return f">={resolve_lib_version()}"
+    text = requested.strip()
+    if not text:
+        raise click.ClickException("--lib-version was given nothing to pin to.")
+    if text[0] in "<>=!~":
+        try:
+            SpecifierSet(text)
+        except InvalidSpecifier as exc:
+            raise click.ClickException(
+                f"--lib-version {requested!r} is not a valid version specifier: {exc}"
+            ) from exc
+        return text
+    try:
+        Version(text)
+    except InvalidVersion as exc:
+        raise click.ClickException(
+            f"--lib-version {requested!r} is not a valid version: {exc}. Give a version "
+            "(0.3.5.dev3) or a full specifier (>=0.3.5.dev3,<0.4)."
+        ) from exc
+    return f">={text}"
+
+
 @click.command(name="init", short_help="Initialize a new Plesty project from a template.")
 @click.argument(
     "project_type",
@@ -125,6 +170,19 @@ def _parse_version(version: str) -> Version | None:
         "quantum) — bump the CI input alongside your releases."
     ),
 )
+@click.option(
+    "--lib-version",
+    default=None,
+    metavar="VERSION",
+    help=(
+        "Pin plesty-lib to this version instead of the newest published one. "
+        "A bare version becomes a lower bound (0.3.5.dev3 → >=0.3.5.dev3); a "
+        "complete specifier is written as given (==0.4.0, '>=0.3.5.dev3,<0.4'). "
+        "PyPI is not consulted, so the scaffold is reproducible — which is what "
+        "a tutorial needs: the lesson text and the reader's pyproject.toml keep "
+        "agreeing however far the library has moved since."
+    ),
+)
 @click.option(
     "--no-ci",
     is_flag=True,
@@ -150,6 +208,7 @@ def init_command(
     author: str | None,
     email: str | None,
     standard: str,
+    lib_version: str | None,
     no_ci: bool,
     force: bool,
 ) -> None:
@@ -192,6 +251,10 @@ def init_command(
         scaffold_mock_test(target_dir, force=force)
         return
 
+    # Settle the pin before anything is created: an unreadable --lib-version
+    # should not leave a directory behind for a project that never happened.
+    lib_pin = lib_specifier(lib_version)
+
     if module_name is None:
         inferred = target_dir.name.removeprefix("plesty-").replace("-", "_")
         if not MODULE_NAME_PATTERN.match(inferred):
@@ -220,7 +283,7 @@ def init_command(
         "pypi_name": pypi_name,
         "project_type": project_type,
         "year": str(datetime.date.today().year),
-        "plesty_lib_version": resolve_lib_version(),
+        "plesty_lib_specifier": lib_pin,
         "plesty_sdk_version": PLESTY_SDK_VERSION,
     }
     if author is not None:

{plesty_sdk-0.3.4 → plesty_sdk-0.3.5.dev1}/tests/test_init.py

@@ -9,6 +9,7 @@ import json
 from pathlib import Path
 from unittest.mock import patch
 
+import click
 import pytest
 from click.testing import CliRunner
 
@@ -19,6 +20,7 @@ from plesty.sdk.commands.init import (
     PLESTY_SDK_VERSION,
     _STANDARD_CI_STAGES,
     generate_gitlab_ci,
+    lib_specifier,
     resolve_lib_version,
 )
 
@@ -590,3 +592,56 @@ class TestResolveLibVersion:
     def test_answer_without_releases_falls_back(self):
         """A body that is JSON but not the expected document is not a version list."""
         assert self._resolve({"info": {"version": "9.9.9"}}) == PLESTY_LIB_VERSION
+
+
+class TestLibSpecifier:
+    """`--lib-version` decides the pin, and asking PyPI is then skipped."""
+
+    @pytest.fixture(autouse=True)
+    def no_network(self):
+        """Any lookup during these tests is a bug: a requested pin asks nobody."""
+        resolve_lib_version.cache_clear()
+        with patch(
+            "plesty.sdk.commands.init.urllib.request.urlopen",
+            side_effect=AssertionError("PyPI must not be consulted for a requested pin"),
+        ):
+            yield
+        resolve_lib_version.cache_clear()
+
+    @pytest.mark.parametrize(
+        ("requested", "expected"),
+        [
+            ("0.3.5.dev3", ">=0.3.5.dev3"),
+            ("  0.4.0  ", ">=0.4.0"),
+            ("==0.4.0", "==0.4.0"),
+            (">=0.3.5.dev3,<0.4", ">=0.3.5.dev3,<0.4"),
+            ("~=0.4.0", "~=0.4.0"),
+        ],
+    )
+    def test_requested_pin(self, requested, expected):
+        """A bare version becomes a lower bound; a specifier is taken as written."""
+        assert lib_specifier(requested) == expected
+
+    @pytest.mark.parametrize("requested", ["", "   ", "not-a-version", ">=", "=>0.4.0"])
+    def test_unreadable_request_is_refused(self, requested):
+        """A pin nothing can resolve is named at the command line, not written out."""
+        with pytest.raises(click.ClickException):
+            lib_specifier(requested)
+
+    def test_scaffold_pins_what_was_asked_for(self, tmp_path):
+        """The requested pin is what lands in the generated pyproject.toml."""
+        result = _invoke_init(
+            tmp_path, "device", "--name", "my_sensor", "--lib-version", ">=0.3.5.dev3,<0.4"
+        )
+        assert result.exit_code == 0, result.output
+        assert '"plesty-lib>=0.3.5.dev3,<0.4"' in (tmp_path / "pyproject.toml").read_text()
+
+    def test_bad_pin_creates_nothing(self, tmp_path):
+        """A refused --lib-version leaves no half-scaffolded directory behind."""
+        target = tmp_path / "plesty-my-sensor"
+        result = _invoke_init(
+            target, "device", "--name", "my_sensor", "--lib-version", "not-a-version"
+        )
+        assert result.exit_code != 0
+        assert "not a valid version" in result.output
+        assert not target.exists()