ask-shell 0.4.0__tar.gz → 0.5.1__tar.gz

{ask_shell-0.4.0 → ask_shell-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ask-shell
-Version: 0.4.0
+Version: 0.5.1
 Summary: CLIs with prompts, shell runs, and testable flows
 Author-email: EspenAlbert <espen.albert1@gmail.com>
 License-Expression: MIT

{ask_shell-0.4.0 → ask_shell-0.5.1}/ask_shell/__init__.py

@@ -6,7 +6,7 @@ from ask_shell import shell_events
 from ask_shell import ask
 from ask_shell.settings import AskShellSettings
 
-VERSION = "0.4.0"
+VERSION = "0.5.1"
 __all__ = [
     "shell",
     "console",

{ask_shell-0.4.0 → ask_shell-0.5.1}/ask_shell/_internal/_run.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 import atexit
 import logging
 import os
+import random
 import signal
 import subprocess
 import sys
@@ -40,6 +41,7 @@ from ask_shell._internal.events import (
     ShellRunStdStarted,
 )
 from ask_shell._internal.models import (
+    AbortRetryError,
     RunIncompleteError,
     ShellConfig,
     ShellRun,
@@ -370,6 +372,49 @@ def _attempt_run(
         _runs.pop(key, None)
 
 
+def _eval_should_retry(config: ShellConfig, result: ShellRun) -> bool:
+    """Evaluate should_retry, raising AbortRetryError through if the callback raises it."""
+    try:
+        return config.should_retry(result)
+    except AbortRetryError:
+        raise
+    except Exception as e:
+        logger.warning(f"should_retry callback failed: {e!r}")
+        return False
+
+
+def _backoff_wait(attempt: int, config: ShellConfig) -> float:
+    """wait = min(initial * 2^(attempt-2), max_wait) + uniform(0, jitter)"""
+    base = min(config.retry_initial_wait * 2 ** (attempt - 2), config.retry_max_wait)
+    return base + random.uniform(0, config.retry_jitter)
+
+
+def _run_attempts(shell_run: ShellRun, output_dir: Path) -> BaseException | None:
+    config = shell_run.config
+    queue = shell_run._queue
+    for attempt in range(1, config.attempts + 1):
+        if attempt > 1:
+            wait_seconds = _backoff_wait(attempt, config)
+            logger.info(f"Backoff {wait_seconds:.2f}s before attempt {attempt}/{config.attempts}")
+            time.sleep(wait_seconds)
+            queue.put_nowait(ShellRunRetryAttempt(attempt=attempt))
+            logger.warning(f"Retrying run {shell_run} attempt {attempt} of {config.attempts}")
+        attempt_log_prefix = config.run_log_stem(attempt)
+        result = _attempt_run(shell_run, output_dir, attempt_log_prefix)
+        match result:
+            case ShellRun() if result.clean_complete:
+                return None
+            case ShellRun():
+                try:
+                    if not _eval_should_retry(config, result):
+                        return None
+                except AbortRetryError as abort:
+                    return abort
+            case BaseException():
+                return result
+    return None
+
+
 def _execute_run(shell_run: ShellRun) -> ShellRun:
     """
     Principles:
@@ -406,20 +451,7 @@ def _execute_run(shell_run: ShellRun) -> ShellRun:
     with _run_completer(shell_run, consumer_future):
         output_dir = config.run_output_dir_resolved()
         output_dir.mkdir(parents=True, exist_ok=True)
-        error: BaseException | None = None
-        for attempt in range(1, config.attempts + 1):
-            if attempt > 1:
-                queue.put_nowait(ShellRunRetryAttempt(attempt=attempt))
-                logger.warning(f"Retrying run {shell_run} attempt {attempt} of {config.attempts}")
-            attempt_log_prefix = config.run_log_stem(attempt)
-
-            result = _attempt_run(shell_run, output_dir, attempt_log_prefix)
-            match result:
-                case ShellRun() if result.clean_complete or not config.should_retry(result):
-                    break
-                case BaseException():
-                    error = result
-                    break
+        error = _run_attempts(shell_run, output_dir)
         queue.put_nowait(ShellRunAfter(run=shell_run, error=error))
         shell_run._complete(error=error, queue_consumer=consumer_future)
         return shell_run
@@ -437,6 +469,9 @@ def run(
     is_binary_call: bool | None = None,
     message_callbacks: list[Callable[[ShellRunEventT], bool]] | None = None,
     print_prefix: str | None = None,
+    retry_initial_wait: float | None = None,
+    retry_jitter: float | None = None,
+    retry_max_wait: float | None = None,
     run_log_stem_prefix: str | None = None,
     run_output_dir: Path | None | None = None,
     settings: AskShellSettings | None = None,
@@ -461,6 +496,9 @@ def run(
         is_binary_call=is_binary_call,
         message_callbacks=message_callbacks,
         print_prefix=print_prefix,
+        retry_initial_wait=retry_initial_wait,
+        retry_jitter=retry_jitter,
+        retry_max_wait=retry_max_wait,
         run_log_stem_prefix=run_log_stem_prefix,
         run_output_dir=run_output_dir,
         settings=settings,
@@ -496,6 +534,9 @@ def run_and_wait(
     is_binary_call: bool | None = None,
     message_callbacks: list[Callable[[ShellRunEventT], bool]] | None = None,
     print_prefix: str | None = None,
+    retry_initial_wait: float | None = None,
+    retry_jitter: float | None = None,
+    retry_max_wait: float | None = None,
     run_log_stem_prefix: str | None = None,
     run_output_dir: Path | None | None = None,
     settings: AskShellSettings | None = None,
@@ -520,6 +561,9 @@ def run_and_wait(
         is_binary_call=is_binary_call,
         message_callbacks=message_callbacks,
         print_prefix=print_prefix,
+        retry_initial_wait=retry_initial_wait,
+        retry_jitter=retry_jitter,
+        retry_max_wait=retry_max_wait,
         run_log_stem_prefix=run_log_stem_prefix,
         run_output_dir=run_output_dir,
         settings=settings,

{ask_shell-0.4.0 → ask_shell-0.5.1}/ask_shell/_internal/interactive.py

@@ -472,6 +472,7 @@ class question_patcher(force_interactive):
         q.application.renderer.output = output
 
     def ask_question(self, q: Question, response_type: type[T]) -> T:
+        _ = response_type  # binds generic T for return type inference
         with create_pipe_input() as inp:
             q.application.input = inp
             input_response = self._next_response(q)

{ask_shell-0.4.0 → ask_shell-0.5.1}/ask_shell/_internal/models.py

@@ -151,6 +151,9 @@ class ShellConfig(Entity):
     # retry args
     attempts: int = 1
     should_retry: Callable[[ShellRun], bool] = always_retry
+    retry_initial_wait: float = Field(default=5, description="Seconds before first retry, only used when attempts > 1")
+    retry_max_wait: float = Field(default=60, description="Cap on wait between retries")
+    retry_jitter: float = Field(default=5, description="Max random jitter added to wait")
 
     # logging/output
     print_prefix: str = Field(default=None, description="Use cwd+binary_name+first_arg if not provided")  # type: ignore
@@ -517,6 +520,10 @@ class RunIncompleteError(Exception):
         self.killed = killed
 
 
+class AbortRetryError(Exception):
+    """Raise from should_retry to stop retrying with a custom error."""
+
+
 class EmptyOutputError(Exception):
     def __init__(self, run: ShellRun, stream: Literal["stdout", "stderr"] = "stdout"):
         self.run = run

{ask_shell-0.4.0 → ask_shell-0.5.1}/ask_shell/shell.py

@@ -7,6 +7,7 @@ from ask_shell._internal._run import run_and_wait as _run_and_wait
 from ask_shell._internal._run import run_error as _run_error
 from ask_shell._internal._run import stop_runs_and_pool as _stop_runs_and_pool
 from ask_shell._internal._run import wait_on_ok_errors as _wait_on_ok_errors
+from ask_shell._internal.models import AbortRetryError as _AbortRetryError
 from ask_shell._internal.models import ShellConfig as _ShellConfig
 from ask_shell._internal.models import ShellError as _ShellError
 from ask_shell._internal.models import ShellRun as _ShellRun
@@ -20,6 +21,7 @@ run_and_wait = _run_and_wait
 run_error = _run_error
 stop_runs_and_pool = _stop_runs_and_pool
 wait_on_ok_errors = _wait_on_ok_errors
+AbortRetryError = _AbortRetryError
 ShellConfig = _ShellConfig
 ShellError = _ShellError
 ShellRun = _ShellRun

ask_shell-0.5.1/ask_shell/test_docs.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import pytest
+from pytest_examples import CodeExample, EvalExample, find_examples
+
+EXAMPLES_DIR = Path(__file__).parent.parent / "docs" / "examples"
+
+
+@pytest.mark.parametrize("example", find_examples(EXAMPLES_DIR), ids=str)
+def test_examples(example: CodeExample, eval_example: EvalExample):
+    eval_example.set_config(line_length=120, target_version="py313", ruff_ignore=["I001", "T"])  # pyright: ignore[reportArgumentType]
+    prefix = example.prefix_settings()
+    if prefix.get("test", "").startswith("skip"):
+        pytest.skip(prefix["test"])
+    if eval_example.update_examples:
+        eval_example.format(example)
+        eval_example.run_print_update(example)
+    else:
+        eval_example.lint(example)
+        eval_example.run_print_check(example)

{ask_shell-0.4.0 → ask_shell-0.5.1}/pyproject.toml

@@ -2,7 +2,7 @@
 
 [project]
 name = "ask-shell"
-version = "0.4.0"
+version = "0.5.1"
 description = "CLIs with prompts, shell runs, and testable flows"
 requires-python = ">=3.13"
 license = "MIT"
@@ -10,9 +10,9 @@ license-files = ["LICENSE"]
 readme = "README.md"
 authors = [{ name = "EspenAlbert", email = "espen.albert1@gmail.com" }]
 classifiers = [
-    "Development Status :: 4 - Beta",
-    "Programming Language :: Python :: 3.13",
-    "Programming Language :: Python :: 3.14",
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
   "model-lib[toml]",
@@ -28,12 +28,7 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.sdist]
 include = ["*/**/*.py", "*/py.typed"]
-exclude = [
-  "*_examples.py",
-  "*_test.py",
-  "conftest.py",
-  "test_*.json",
-]
+exclude = ["*_examples.py", "*_test.py", "conftest.py", "test_*.json"]
 
 # === DO_NOT_EDIT: path-sync pkg-ext ===
 [tool.pkg-ext]
@@ -41,6 +36,12 @@ tag_prefix = "v"
 max_bump_type = "minor"
 # === OK_EDIT: path-sync pkg-ext ===
 
+[tool.pkg-ext.groups.shell]
+examples_include = [
+  "AbortRetryError",
+]
+
+
 # === DO_NOT_EDIT: path-sync ruff ===
 [tool.ruff]
 line-length = 120
@@ -55,12 +56,13 @@ target-version = "py313"
 # UP046: use type parameters on functions instead of TypeVar
 # UP047: use type parameters instead of `Generic[T]` subclass
 extend-ignore = ["E501", "UP006", "UP007", "UP035", "UP040", "UP046", "UP047"]
-extend-select = ["Q", "RUF100", "C90", "UP", "I", "T"]
+extend-select = ["Q", "RUF100", "C90", "UP", "I", "T", "FURB"]
 # === OK_EDIT: path-sync ruff ===
 
 # === DO_NOT_EDIT: path-sync pytest ===
 [tool.pytest.ini_options]
-addopts = "-s -vv --log-cli-level=INFO"
+addopts = "-s -vv --log-cli-level=INFO -m 'not manual'"
+markers = ["manual: test requires manual env setup (not run in CI)"]
 python_files = ["*_test.py", "test_*.py"]
 asyncio_mode = "auto"
 # === OK_EDIT: path-sync pytest ===
@@ -71,22 +73,37 @@ omit = ["*_test.py"]
 exclude_lines = ["no cov", "if __name__ == .__main__.:"]
 # === OK_EDIT: path-sync coverage ===
 
+# === DO_NOT_EDIT: path-sync vulture ===
+[tool.vulture]
+min_confidence = 80
+ignore_names = ["mock_*", "Mock*", "*_mock"]
+exclude = [".venv/", "*test.py"]
+# === OK_EDIT: path-sync vulture ===
+
+# === DO_NOT_EDIT: path-sync dev-lint ===
 [dependency-groups]
-dev = [
+dev-lint = [
   "pyright>=1.1",
+  "ruff>=0.14",
+  "vulture>=2.14",
+]
+# === OK_EDIT: path-sync dev-lint ===
+dev-test = [
   "pytest>=9.0",
   "pytest-asyncio>=0.24",
   "pytest-cov>=7.0",
+  "pytest-examples>=0.0.18",
   "pytest-model-lib",
-  "ruff>=0.14",
+  "pytest-regressions>=2.6",
 ]
-
+# === DO_NOT_EDIT: path-sync dev ===
+dev = [{include-group = "dev-lint"}, {include-group = "dev-test"}]
+# === OK_EDIT: path-sync dev ===
+# === DO_NOT_EDIT: path-sync release ===
+release = ["pkg-ext"]
+# === OK_EDIT: path-sync release ===
 # === DO_NOT_EDIT: path-sync docs ===
 docs = [
   "mkdocs-material>=9.5",
 ]
 # === OK_EDIT: path-sync docs ===
-
-# === DO_NOT_EDIT: path-sync release ===
-release = ["pkg-ext"]
-# === OK_EDIT: path-sync release ===