simulo 0.24.0__tar.gz → 0.25.0__tar.gz

{simulo-0.24.0/src/simulo.egg-info → simulo-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.24.0
+Version: 0.25.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
@@ -71,6 +71,10 @@ required — `simulo create` only writes files to your local folder. Edit
 `app.py` for your own robot and task, then see "Log in and submit" below to
 run it.
 
+To download a curated collection of runnable projects, use `simulo install samples`.
+It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
+`cat README.md` open the sample index.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.24.0 → simulo-0.25.0}/PYPI.md

@@ -31,6 +31,10 @@ required — `simulo create` only writes files to your local folder. Edit
 `app.py` for your own robot and task, then see "Log in and submit" below to
 run it.
 
+To download a curated collection of runnable projects, use `simulo install samples`.
+It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
+`cat README.md` open the sample index.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.24.0 → simulo-0.25.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.24.0"
+version = "0.25.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.24.0 → simulo-0.25.0}/src/simulo/_client/cli.py

@@ -53,6 +53,10 @@ the packaged ``src/`` layout and never reaches a real ``pip install simulo``
 user. No network call, no auth — this only touches the local filesystem and the
 wheel's own bundled resources.
 
+``simulo install samples`` clones the public sample collection into
+``./simulo-samples`` with normal Git history. It uses neither client settings nor
+saved sign-in state; a failed clone is removed before it can appear at that path.
+
 **Auth** (``simulo login`` / ``logout`` / ``whoami``) drives the OAuth 2.0 +
 PKCE loopback flow and manages
 ``~/.simulo/credentials``.
@@ -182,6 +186,7 @@ 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.jobs_api import JobsApiClient, JobsApiError, JobsApiHTTPError, JobsApiUnavailable
 from simulo._client.login import LoginError, perform_login
 from simulo._client.mode import DISCOVERY
@@ -635,6 +640,19 @@ _MACHINE_UUID_RE = re.compile(
 )
 _MAX_CLI_ERROR_CHARS = 2048
 
+#: Clean, human-worded renderings for account/organization state error codes
+#: that reach the CLI verbatim from the wire (``code: message``) otherwise.
+#: Shared between ``_safe_cli_error_text`` (the general path: ``jobs``,
+#: ``cancel``, ``view``, ``run``, ``whoami``, ...) and ``_friendly_asset_error``
+#: (the asset-catalog surface, which wraps errors in its own ``AssetApiHTTPError``
+#: rather than ``http.HttpHTTPError``, so it cannot share the first function's
+#: isinstance check) so a person sees the identical message regardless of which
+#: command surfaced the error.
+_ACCOUNT_SUSPENDED_MESSAGE = "Your Simulo account has been suspended. Contact Simulo support to restore access."
+_ORGANIZATION_DEACTIVATED_MESSAGE = (
+    "This organization has been deactivated. Its owner can reactivate it from organization settings."
+)
+
 
 def _canonical_uuid_text(value: Any) -> Optional[str]:
     """Return one exact legacy UUID in canonical form, or ``None``."""
@@ -682,7 +700,13 @@ def _safe_cli_error_text(value: Any) -> str:
     if (isinstance(value, http.HttpHTTPError) and value.code == "account_suspended") or (
         isinstance(value, credentials.TokenRefreshError) and value.code == "account_suspended"
     ):
-        text = "Your Simulo account has been suspended. Contact Simulo support to restore access."
+        text = _ACCOUNT_SUSPENDED_MESSAGE
+    elif isinstance(value, http.HttpHTTPError) and value.code == "organization_deactivated":
+        # Unlike suspension, deactivation never disables Cognito: a stale
+        # credential still refreshes fine, and it's the org-scoped API call
+        # that returns this 403. There is deliberately no
+        # ``credentials.TokenRefreshError`` counterpart here.
+        text = _ORGANIZATION_DEACTIVATED_MESSAGE
     else:
         text = str(value)
     # A legacy UUID-prefix ambiguity is the one named compatibility exception
@@ -5729,9 +5753,21 @@ def _friendly_asset_error(exc: AssetApiHTTPError) -> str:
     The server's message leads (it already speaks user language); the quota
     case appends the catalog's required "two ways out" (delete or
     upgrade). Unrecognized codes render as the standard ``code: message``.
-    Every matched code is a shared interfaces constant, so a control-plane rename cannot
-    silently degrade this copy by drifting from a hand-typed literal here.
+    Every matched ``ASSET_*`` code is a shared interfaces constant, so a
+    control-plane rename cannot silently degrade this copy by drifting from a
+    hand-typed literal here. ``account_suspended`` and
+    ``organization_deactivated`` are the two exceptions: they are account/org
+    states, not asset-catalog concepts, so they have no shared constant here
+    either (``_safe_cli_error_text`` matches them the same way) — every asset
+    command reaches ``AssetApiHTTPError`` instead of ``http.HttpHTTPError``
+    (see ``asset_api._translate``), so it cannot share that function's
+    isinstance-gated branches and needs its own. Render the identical
+    hand-worded message either function would produce, not the raw code.
     """
+    if exc.code == "account_suspended":
+        return _ACCOUNT_SUSPENDED_MESSAGE
+    if exc.code == "organization_deactivated":
+        return _ORGANIZATION_DEACTIVATED_MESSAGE
     if exc.code == ASSET_STORAGE_QUOTA_EXCEEDED_CODE:
         return (
             f"{exc.message}\n"
@@ -8229,6 +8265,38 @@ def _build_parser() -> argparse.ArgumentParser:
 
     create.set_defaults(func=_handle_create)
 
+    install = sub.add_parser("install", help="Install a curated local collection of Simulo samples.")
+    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.",
+    )
+
+    def _handle_install_samples(args: argparse.Namespace, extras: Sequence[str]) -> int:
+        if extras:
+            samples.error(f"unrecognized arguments: {' '.join(extras)}")
+        try:
+            installed = install_samples(Path.cwd())
+        except InstallSamplesUsageError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            print("Nothing was installed.", file=sys.stderr)
+            return 2
+        except InstallSamplesError as exc:
+            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)."
+        )
+        print("Next steps:")
+        print("  cd simulo-samples")
+        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
+
+    samples.set_defaults(func=_handle_install_samples)
+
     # -- simulo asset (the FIRST nested subcommand group in this CLI) --------
     asset = sub.add_parser(
         "asset",

simulo-0.25.0/src/simulo/_client/install_samples.py

@@ -0,0 +1,267 @@
+"""Install the public Simulo sample collection with a normal Git clone."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+SAMPLES_REPOSITORY_URL = "https://github.com/simulo-org/simulo-samples.git"
+DEFAULT_SAMPLES_DIRECTORY_NAME = "simulo-samples"
+CLONE_TIMEOUT_S = 300
+_MAX_GIT_STDERR_INPUT_BYTES = 4096
+_MAX_GIT_STDERR_RENDERED_BYTES = 4096
+_GIT_OUTPUT_PREFIX = "  | git: "
+_GIT_PROGRESS_PREFIXES = (
+    "Cloning into ",
+    "Receiving objects:",
+    "Resolving deltas:",
+    "remote: Enumerating objects:",
+    "remote: Counting objects:",
+    "remote: Compressing objects:",
+    "remote: Total ",
+)
+
+
+class InstallSamplesError(RuntimeError):
+    """Raised when the samples cannot be installed."""
+
+
+class InstallSamplesUsageError(ValueError):
+    """Raised when the requested install destination is unsafe to use."""
+
+
+@dataclass(frozen=True)
+class InstalledSamples:
+    """The local sample collection created by :func:`install_samples`."""
+
+    path: Path
+
+
+def _git_environment() -> dict[str, str]:
+    """Return a non-interactive environment for a public clone."""
+    environment = dict(os.environ)
+    for key in tuple(environment):
+        if any(fragment in key.upper() for fragment in ("TOKEN", "SECRET", "CREDENTIAL")):
+            environment.pop(key)
+    environment.pop("GIT_CONFIG_PARAMETERS", None)
+    environment.update(
+        {
+            "GIT_TERMINAL_PROMPT": "0",
+            "GIT_ASKPASS": "",
+            "GCM_INTERACTIVE": "never",
+            "GIT_CONFIG_COUNT": "1",
+            "GIT_CONFIG_KEY_0": "credential.helper",
+            "GIT_CONFIG_VALUE_0": "",
+        }
+    )
+    return environment
+
+
+def _run_git(argv: list[str], *, timeout_s: int, env: dict[str, str]) -> subprocess.CompletedProcess[str]:
+    """Run Git through the one seam tests replace."""
+    return subprocess.run(argv, capture_output=True, check=False, env=env, text=True, timeout=timeout_s)
+
+
+def _stderr_tail(stderr: str | bytes | None) -> str:
+    if isinstance(stderr, bytes):
+        stderr = stderr.decode(errors="replace")
+    if not stderr:
+        return ""
+    encoded = stderr.encode("utf-8", errors="replace")
+    bounded_bytes = encoded[-_MAX_GIT_STDERR_INPUT_BYTES:]
+    was_truncated = len(bounded_bytes) < len(encoded)
+    bounded = bounded_bytes.decode("utf-8", errors="replace")
+    lines = bounded.splitlines()
+    starts_mid_line = was_truncated and encoded[-_MAX_GIT_STDERR_INPUT_BYTES - 1] not in (ord("\n"), ord("\r"))
+    if starts_mid_line and len(lines) > 1:
+        lines = lines[1:]
+    non_progress_lines = [line for line in lines if not line.startswith(_GIT_PROGRESS_PREFIXES)]
+    return _quote_git_output(non_progress_lines[-10:])
+
+
+def _quote_git_output(lines: list[str]) -> str:
+    """Prefix Git output without exceeding the CLI's rendered stderr bound."""
+    output: list[str] = []
+    output_bytes = 0
+    prefix_bytes = len(_GIT_OUTPUT_PREFIX.encode("utf-8"))
+    for line in reversed(lines):
+        printable_line = "".join(character for character in line if character.isprintable())
+        quoted_line = f"{_GIT_OUTPUT_PREFIX}{printable_line}"
+        quoted_line_bytes = len(quoted_line.encode("utf-8", errors="replace"))
+        separator_bytes = 1 if output else 0
+        if output_bytes + separator_bytes + quoted_line_bytes <= _MAX_GIT_STDERR_RENDERED_BYTES:
+            output.insert(0, quoted_line)
+            output_bytes += separator_bytes + quoted_line_bytes
+        elif not output:
+            available_line_bytes = _MAX_GIT_STDERR_RENDERED_BYTES - prefix_bytes
+            output.append(
+                _GIT_OUTPUT_PREFIX
+                + printable_line.encode("utf-8", errors="replace")[-available_line_bytes:].decode(errors="ignore")
+            )
+            break
+        else:
+            break
+    return "\n".join(output)
+
+
+def _remove_read_only_path(function: object, path: str, _exc_info: object) -> None:
+    """Make Windows Git object files writable, then retry rmtree's operation."""
+    # Known and owned Windows residual: this misses directory junctions, which Python 3.11 rmtree can follow; staging
+    # access follows inherited ACLs.
+    if not os.path.islink(path):
+        os.chmod(path, 0o700)
+    function(path)  # type: ignore[operator]
+
+
+def _directory_identity(path: Path) -> tuple[int, int]:
+    status = path.stat()
+    return status.st_dev, status.st_ino
+
+
+def _remove_staging_directory(staging: Path, identity: tuple[int, int]) -> None:
+    try:
+        current_identity = _directory_identity(staging)
+    except FileNotFoundError:
+        return
+    except OSError:
+        print(f"warning: could not inspect partial samples install at {staging}", file=sys.stderr)
+        return
+    if current_identity != identity:
+        print(f"warning: partial samples install path no longer belongs to this invocation: {staging}", file=sys.stderr)
+        return
+    try:
+        shutil.rmtree(staging, onerror=_remove_read_only_path)
+    except OSError:
+        print(f"warning: could not remove partial samples install at {staging}", file=sys.stderr)
+
+
+def _clone_failure(
+    reason: str, stderr: str | bytes | None, *, explain_public_repository: bool = False
+) -> InstallSamplesError:
+    tail = _stderr_tail(stderr)
+    explanation = (
+        "The samples repository is public and this command does not sign in.\n"
+        "An authentication error means Git could not reach the repository or its host, not that there is a problem "
+        "with your account."
+    )
+    message = f"{reason}\n{tail}" if tail else reason
+    if explain_public_repository:
+        message = f"{message}\n{explanation}"
+    return InstallSamplesError(message)
+
+
+def _target_exists_error(target: Path) -> InstallSamplesUsageError:
+    if not target.is_dir():
+        return InstallSamplesUsageError(f"{target} exists and is not a directory.")
+    return InstallSamplesUsageError(f"{target} already exists.")
+
+
+def _git_is_reachable_through_working_directory(
+    named_git_path: Path, git_executable: Path, working_directory: Path
+) -> bool:
+    """Return whether resolving Git depends on the current working directory."""
+    return not named_git_path.is_absolute() or working_directory in {
+        named_git_path.parent,
+        named_git_path.parent.resolve(),
+        git_executable.parent,
+    }
+
+
+def _clone_has_sample_files(staging: Path) -> bool:
+    """Return whether a successful clone produced a user-visible worktree entry.
+
+    An unreadable staging directory counts as no sample files. This is the only
+    filesystem read on the success path, and letting an OSError escape here would
+    abandon the staging directory and break the promise that a failed install
+    leaves nothing behind.
+    """
+    try:
+        return any(entry.name != ".git" for entry in staging.iterdir())
+    except OSError:
+        return False
+
+
+def install_samples(
+    parent_directory: Path,
+    *,
+    repository_url: str = SAMPLES_REPOSITORY_URL,
+    directory_name: str = DEFAULT_SAMPLES_DIRECTORY_NAME,
+    timeout_s: int = CLONE_TIMEOUT_S,
+) -> InstalledSamples:
+    """Clone samples into *parent_directory* and reveal them atomically."""
+    target = parent_directory / directory_name
+    if target.exists():
+        raise _target_exists_error(target)
+
+    git_path = shutil.which("git")
+    if git_path is None:
+        raise InstallSamplesError(
+            "Git is required to install samples. Get it from https://git-scm.com/downloads and try again."
+        )
+    named_git_path = Path(git_path)
+    working_directory = Path.cwd().resolve()
+    git_executable = named_git_path.resolve()
+    if _git_is_reachable_through_working_directory(named_git_path, git_executable, working_directory):
+        raise InstallSamplesError(
+            f"Refusing resolved Git executable {git_executable}: its PATH entry is relative to or resolves through "
+            "the current working directory. Run this command from a different directory, or use a Git executable "
+            "outside the working directory."
+        )
+
+    staging = parent_directory / f".{directory_name}.partial-{os.getpid()}"
+    try:
+        staging.mkdir()
+    except FileExistsError:
+        raise InstallSamplesError(f"Partial samples install path already exists: {staging}.") from None
+    except OSError as exc:
+        reason = exc.strerror or str(exc)
+        raise InstallSamplesError(f"Could not prepare samples install at {staging}: {reason}.") from None
+    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)]
+    try:
+        completed = _run_git(argv, timeout_s=timeout_s, env=_git_environment())
+    except subprocess.TimeoutExpired as exc:
+        _remove_staging_directory(staging, staging_identity)
+        raise _clone_failure(
+            f"Git clone timed out after {timeout_s} seconds. "
+            f"If your connection needs longer, clone it by hand with git clone {repository_url}.",
+            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 start Git clone: {reason}.") from None
+
+    if completed.returncode != 0:
+        _remove_staging_directory(staging, staging_identity)
+        raise _clone_failure(
+            f"Git clone failed with exit code {completed.returncode}.",
+            completed.stderr,
+            explain_public_repository=True,
+        )
+
+    if 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():
+        _remove_staging_directory(staging, staging_identity)
+        raise _target_exists_error(target)
+
+    try:
+        os.rename(staging, target)
+    except OSError as exc:
+        _remove_staging_directory(staging, staging_identity)
+        reason = exc.strerror or str(exc)
+        raise InstallSamplesError(f"Could not finish installing samples: {reason}.") from None
+
+    return InstalledSamples(path=target.resolve())

{simulo-0.24.0 → simulo-0.25.0/src/simulo.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.24.0
+Version: 0.25.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
@@ -71,6 +71,10 @@ required — `simulo create` only writes files to your local folder. Edit
 `app.py` for your own robot and task, then see "Log in and submit" below to
 run it.
 
+To download a curated collection of runnable projects, use `simulo install samples`.
+It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
+`cat README.md` open the sample index.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.24.0 → simulo-0.25.0}/src/simulo.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ src/simulo/_client/export_bundle.py
 src/simulo/_client/facades.py
 src/simulo/_client/http.py
 src/simulo/_client/identity_api.py
+src/simulo/_client/install_samples.py
 src/simulo/_client/jobs_api.py
 src/simulo/_client/learning.py
 src/simulo/_client/login.py