simulo 0.26.0__tar.gz → 0.27.0__tar.gz

{simulo-0.26.0/src/simulo.egg-info → simulo-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.26.0
+Version: 0.27.0
 Summary: Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -75,6 +75,19 @@ To download a curated collection of runnable projects, use `simulo install sampl
 It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
 `cat README.md` open the sample index.
 
+Choose a destination with `--directory` and a Git branch, tag, or commit with
+`--ref`. You can use either option on its own or combine them:
+
+```bash
+simulo install samples --directory robotics-examples --ref main
+cd robotics-examples
+```
+
+The destination must not exist, and its parent directory must already exist.
+The directory appears only after the clone and requested checkout succeed.
+Use a tag or full commit ID instead of `main` to select a fixed revision.
+With `--ref`, the checkout is detached at the selected commit.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.26.0 → simulo-0.27.0}/PYPI.md

@@ -35,6 +35,19 @@ To download a curated collection of runnable projects, use `simulo install sampl
 It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
 `cat README.md` open the sample index.
 
+Choose a destination with `--directory` and a Git branch, tag, or commit with
+`--ref`. You can use either option on its own or combine them:
+
+```bash
+simulo install samples --directory robotics-examples --ref main
+cd robotics-examples
+```
+
+The destination must not exist, and its parent directory must already exist.
+The directory appears only after the clone and requested checkout succeed.
+Use a tag or full commit ID instead of `main` to select a fixed revision.
+With `--ref`, the checkout is detached at the selected commit.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.26.0 → simulo-0.27.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.26.0"
+version = "0.27.0"
 description = "Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo-0.26.0 → simulo-0.27.0}/src/simulo/_client/cli.py

@@ -131,6 +131,7 @@ import json
 import math
 import os
 import re
+import shlex
 import shutil
 import socket
 import sys
@@ -194,7 +195,12 @@ from simulo._client.discovery import discover, import_app_module
 from simulo._client.export_api import DEFAULT_EXPORT_FORMAT, ExportApiClient, ExportApiError
 from simulo._client.export_bundle import PolicyBundleError, extract_policy_bundle
 from simulo._client.identity_api import IdentityApiClient, IdentityApiError
-from simulo._client.install_samples import InstallSamplesError, InstallSamplesUsageError, install_samples
+from simulo._client.install_samples import (
+    DEFAULT_SAMPLES_DIRECTORY_NAME,
+    InstallSamplesError,
+    InstallSamplesUsageError,
+    install_samples,
+)
 from simulo._client.jobs_api import JobsApiClient, JobsApiError, JobsApiHTTPError, JobsApiUnavailable
 from simulo._client.login import LoginError, perform_login
 from simulo._client.mode import DISCOVERY
@@ -8349,14 +8355,33 @@ def _build_parser() -> argparse.ArgumentParser:
     install_sub = install.add_subparsers(dest="install_command", required=True)
     samples = install_sub.add_parser(
         "samples",
-        help="Clone the sample collection into ./simulo-samples with full Git history.",
+        help="Clone the sample collection into ./simulo-samples by default with full Git history.",
+    )
+    samples.add_argument(
+        "--directory",
+        metavar="PATH",
+        type=Path,
+        help="Install into PATH instead of ./simulo-samples. PATH's parent directory must already exist.",
+    )
+    samples.add_argument(
+        "--ref",
+        metavar="REF",
+        help="Check out Git branch, tag, or commit REF after cloning.",
     )
 
     def _handle_install_samples(args: argparse.Namespace, extras: Sequence[str]) -> int:
         if extras:
             samples.error(f"unrecognized arguments: {' '.join(extras)}")
+        directory = args.directory
+        if directory is None:
+            parent_directory = Path.cwd()
+            directory_name = DEFAULT_SAMPLES_DIRECTORY_NAME
+        else:
+            target = directory if directory.is_absolute() else Path.cwd() / directory
+            parent_directory = target.parent
+            directory_name = target.name
         try:
-            installed = install_samples(Path.cwd())
+            installed = install_samples(parent_directory, directory_name=directory_name, ref=args.ref)
         except InstallSamplesUsageError as exc:
             print(f"error: {exc}", file=sys.stderr)
             print("Nothing was installed.", file=sys.stderr)
@@ -8365,12 +8390,21 @@ def _build_parser() -> argparse.ArgumentParser:
             print(f"error: {exc}", file=sys.stderr)
             print("Nothing was installed.", file=sys.stderr)
             return 1
-        print(
-            f"Installed the Simulo samples in {installed.path} "
-            "(a normal Git clone: history, branches, and git pull all work)."
-        )
+        if args.ref is None:
+            print(
+                f"Installed the Simulo samples in {installed.path} "
+                "(a normal Git clone: history, branches, and git pull all work)."
+            )
+        else:
+            print(
+                f"Installed the Simulo samples in {installed.path} "
+                f"(a normal Git clone pinned to {args.ref!r}; the checkout is detached)."
+            )
         print("Next steps:")
-        print("  cd simulo-samples")
+        if directory is None:
+            print("  cd simulo-samples")
+        else:
+            print(f"  cd {shlex.quote(str(installed.path))}")
         print("  cat README.md")
         print("README.md is the sample index; each sample folder has its own app.py to run with simulo run.")
         return 0

{simulo-0.26.0 → simulo-0.27.0}/src/simulo/_client/http.py

@@ -48,7 +48,7 @@ class HttpError(RuntimeError):
 
 
 class HttpUnavailable(HttpError):
-    """The endpoint cannot be reached at all (nothing listening / DNS failure)."""
+    """The endpoint is unreachable or its response times out."""
 
 
 class HttpHTTPError(HttpError):
@@ -373,6 +373,8 @@ def request_bytes(
         raise _structured_http_error(exc) from exc
     except urllib.error.URLError as exc:
         raise HttpUnavailable(_unavailable_message(url, unavailable_hint, exc.reason)) from exc
+    except TimeoutError as exc:
+        raise HttpUnavailable(_unavailable_message(url, unavailable_hint, exc)) from exc
 
 
 def request_json(

{simulo-0.26.0 → simulo-0.27.0}/src/simulo/_client/install_samples.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import re
 import shutil
 import subprocess
 import sys
@@ -134,6 +135,8 @@ def _remove_staging_directory(staging: Path, identity: tuple[int, int]) -> None:
         print(f"warning: partial samples install path no longer belongs to this invocation: {staging}", file=sys.stderr)
         return
     try:
+        if not os.path.islink(staging):
+            os.chmod(staging, 0o700)
         shutil.rmtree(staging, onerror=_remove_read_only_path)
     except OSError:
         print(f"warning: could not remove partial samples install at {staging}", file=sys.stderr)
@@ -160,6 +163,11 @@ def _target_exists_error(target: Path) -> InstallSamplesUsageError:
     return InstallSamplesUsageError(f"{target} already exists.")
 
 
+def _path_exists(path: Path) -> bool:
+    """Return whether *path* exists, including a dangling symbolic link."""
+    return os.path.lexists(path)
+
+
 def _git_is_reachable_through_working_directory(
     named_git_path: Path, git_executable: Path, working_directory: Path
 ) -> bool:
@@ -190,11 +198,14 @@ def install_samples(
     *,
     repository_url: str = SAMPLES_REPOSITORY_URL,
     directory_name: str = DEFAULT_SAMPLES_DIRECTORY_NAME,
+    ref: str | None = None,
     timeout_s: int = CLONE_TIMEOUT_S,
 ) -> InstalledSamples:
     """Clone samples into *parent_directory* and reveal them atomically."""
     target = parent_directory / directory_name
-    if target.exists():
+    if not parent_directory.is_dir():
+        raise InstallSamplesUsageError(f"Parent directory {parent_directory} does not exist or is not a directory.")
+    if _path_exists(target):
         raise _target_exists_error(target)
 
     git_path = shutil.which("git")
@@ -223,7 +234,10 @@ def install_samples(
     staging_identity = _directory_identity(staging)
 
     print("Cloning the samples with full history; this can take a minute.", file=sys.stderr)
-    argv = [str(git_executable), "clone", "--", repository_url, str(staging)]
+    argv = [str(git_executable), "clone"]
+    if ref is not None:
+        argv.append("--no-checkout")
+    argv.extend(["--", repository_url, str(staging)])
     try:
         completed = _run_git(argv, timeout_s=timeout_s, env=_git_environment())
     except subprocess.TimeoutExpired as exc:
@@ -249,11 +263,131 @@ def install_samples(
             explain_public_repository=True,
         )
 
-    if not _clone_has_sample_files(staging):
+    if ref is None and not _clone_has_sample_files(staging):
         _remove_staging_directory(staging, staging_identity)
         raise _clone_failure("Git clone produced an empty working tree.", completed.stderr)
 
-    if target.exists():
+    if ref is not None:
+        try:
+            resolved = _run_git(
+                [
+                    str(git_executable),
+                    "-C",
+                    str(staging),
+                    "rev-parse",
+                    "--verify",
+                    "--end-of-options",
+                    f"{ref}^{{commit}}",
+                ],
+                timeout_s=timeout_s,
+                env=_git_environment(),
+            )
+        except subprocess.TimeoutExpired as exc:
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure(f"Git could not resolve samples reference {ref!r}: timed out.", exc.stderr) from None
+        except KeyboardInterrupt:
+            _remove_staging_directory(staging, staging_identity)
+            raise
+        except OSError as exc:
+            _remove_staging_directory(staging, staging_identity)
+            reason = exc.strerror or str(exc)
+            raise InstallSamplesError(f"Could not resolve samples reference {ref!r}: {reason}.") from None
+        if resolved.returncode != 0:
+            try:
+                resolved = _run_git(
+                    [
+                        str(git_executable),
+                        "-C",
+                        str(staging),
+                        "rev-parse",
+                        "--verify",
+                        "--end-of-options",
+                        f"refs/remotes/origin/{ref}^{{commit}}",
+                    ],
+                    timeout_s=timeout_s,
+                    env=_git_environment(),
+                )
+            except subprocess.TimeoutExpired as exc:
+                _remove_staging_directory(staging, staging_identity)
+                raise _clone_failure(
+                    f"Git could not resolve samples reference {ref!r}: timed out.", exc.stderr
+                ) from None
+            except KeyboardInterrupt:
+                _remove_staging_directory(staging, staging_identity)
+                raise
+            except OSError as exc:
+                _remove_staging_directory(staging, staging_identity)
+                reason = exc.strerror or str(exc)
+                raise InstallSamplesError(f"Could not resolve samples reference {ref!r}: {reason}.") from None
+            if resolved.returncode != 0:
+                _remove_staging_directory(staging, staging_identity)
+                raise _clone_failure(f"Git could not resolve samples reference {ref!r}.", resolved.stderr)
+        commit = resolved.stdout.strip()
+        if re.fullmatch(r"[0-9a-fA-F]{40,64}", commit) is None:
+            _remove_staging_directory(staging, staging_identity)
+            raise InstallSamplesError(f"Git could not resolve samples reference {ref!r} to a commit.")
+
+        try:
+            checked_out = _run_git(
+                [str(git_executable), "-C", str(staging), "checkout", "--detach", commit],
+                timeout_s=timeout_s,
+                env=_git_environment(),
+            )
+        except subprocess.TimeoutExpired as exc:
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure(f"Git could not check out samples reference {ref!r}: timed out.", exc.stderr) from None
+        except KeyboardInterrupt:
+            _remove_staging_directory(staging, staging_identity)
+            raise
+        except OSError as exc:
+            _remove_staging_directory(staging, staging_identity)
+            reason = exc.strerror or str(exc)
+            raise InstallSamplesError(f"Could not check out samples reference {ref!r}: {reason}.") from None
+        if checked_out.returncode != 0:
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure(f"Git could not check out samples reference {ref!r}.", checked_out.stderr)
+        if not _clone_has_sample_files(staging):
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure("Git checkout produced an empty working tree.", checked_out.stderr)
+
+        try:
+            head = _run_git(
+                [str(git_executable), "-C", str(staging), "rev-parse", "--verify", "HEAD"],
+                timeout_s=timeout_s,
+                env=_git_environment(),
+            )
+            worktree = _run_git(
+                [
+                    str(git_executable),
+                    "-C",
+                    str(staging),
+                    "diff",
+                    "--quiet",
+                    commit,
+                    "--",
+                ],
+                timeout_s=timeout_s,
+                env=_git_environment(),
+            )
+        except subprocess.TimeoutExpired as exc:
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure(f"Git could not verify samples reference {ref!r}: timed out.", exc.stderr) from None
+        except KeyboardInterrupt:
+            _remove_staging_directory(staging, staging_identity)
+            raise
+        except OSError as exc:
+            _remove_staging_directory(staging, staging_identity)
+            reason = exc.strerror or str(exc)
+            raise InstallSamplesError(f"Could not verify samples reference {ref!r}: {reason}.") from None
+        if head.returncode != 0 or worktree.returncode not in (0, 1):
+            _remove_staging_directory(staging, staging_identity)
+            stderr = head.stderr if head.returncode != 0 else worktree.stderr
+            raise _clone_failure(f"Git could not verify samples reference {ref!r}.", stderr)
+        if head.stdout.strip().lower() != commit.lower() or worktree.returncode != 0:
+            _remove_staging_directory(staging, staging_identity)
+            raise InstallSamplesError("Git checkout did not leave the requested samples revision clean.")
+
+    if _path_exists(target):
         _remove_staging_directory(staging, staging_identity)
         raise _target_exists_error(target)
 

{simulo-0.26.0 → simulo-0.27.0}/src/simulo/_client/preflight_api.py

@@ -17,18 +17,10 @@ always returns a :class:`PreflightOutcome`, either a genuine
 for the CLI to print verbatim before proceeding. Only a genuinely
 well-formed 200 response can carry a ``blocking`` finding.
 
-The final ``except Exception`` in :meth:`PreflightApiClient.evaluate` is
-deliberate, not sloppy: measured against this codebase's own ``http.py``,
-``urllib.request.urlopen``'s connect/send-phase failures surface as
-``urllib.error.URLError`` (wrapped here as the thin client's ``HttpUnavailable``),
-but a peer that accepts the connection and then simply never answers (this
-PR's own connection-timeout test reproduces it) times out INSIDE
-``http.client.HTTPConnection.getresponse()`` — a call site ``http.py``'s
-existing ``except urllib.error.URLError`` does not wrap, so a bare
-``socket.timeout``/``TimeoutError`` can reach this call site unwrapped. The
-broad catch is the safety net for exactly that gap (and for anything else
-unanticipated) — preflight must not add a second instance of this failure class to the
-submit path.
+The shared HTTP helper wraps connection failures and response timeouts as
+``HttpUnavailable``. The final ``except Exception`` in
+:meth:`PreflightApiClient.evaluate` preserves the fail-open contract for other
+unexpected errors: only a well-formed findings response may block submission.
 """
 
 from __future__ import annotations

{simulo-0.26.0 → simulo-0.27.0/src/simulo.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.26.0
+Version: 0.27.0
 Summary: Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -75,6 +75,19 @@ To download a curated collection of runnable projects, use `simulo install sampl
 It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
 `cat README.md` open the sample index.
 
+Choose a destination with `--directory` and a Git branch, tag, or commit with
+`--ref`. You can use either option on its own or combine them:
+
+```bash
+simulo install samples --directory robotics-examples --ref main
+cd robotics-examples
+```
+
+The destination must not exist, and its parent directory must already exist.
+The directory appears only after the clone and requested checkout succeed.
+Use a tag or full commit ID instead of `main` to select a fixed revision.
+With `--ref`, the checkout is detached at the selected commit.
+
 ### Or write an app by hand
 
 ```python