ask-shell 0.6.0__tar.gz → 0.8.0__tar.gz

{ask_shell-0.6.0 → ask_shell-0.8.0}/PKG-INFO

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

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/__init__.py

@@ -5,12 +5,14 @@ from ask_shell import console
 from ask_shell import shell_events
 from ask_shell import ask
 from ask_shell.settings import AskShellSettings
+from ask_shell.settings import ShellRunSummary
 
-VERSION = "0.6.0"
+VERSION = "0.8.0"
 __all__ = [
     "shell",
     "console",
     "shell_events",
     "ask",
     "AskShellSettings",
+    "ShellRunSummary",
 ]

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/_internal/_run.py

@@ -34,6 +34,7 @@ from zero_3rdparty.future import add_done_callback, add_error_logging, chain_fut
 from ask_shell._internal.events import (
     ShellRunAfter,
     ShellRunBefore,
+    ShellRunCallbackT,
     ShellRunPOpenStarted,
     ShellRunRetryAttempt,
     ShellRunStdOutput,
@@ -45,7 +46,6 @@ from ask_shell._internal.models import (
     RunIncompleteError,
     ShellConfig,
     ShellRun,
-    ShellRunEventT,
     ShellRunQueueT,
 )
 from ask_shell.settings import AskShellSettings, _global_settings
@@ -467,7 +467,7 @@ def run(
     env: dict[str, str] | None = None,
     extra_popen_kwargs: dict | None = None,
     is_binary_call: bool | None = None,
-    message_callbacks: list[Callable[[ShellRunEventT], bool]] | None = None,
+    message_callbacks: list[ShellRunCallbackT] | None = None,
     print_prefix: str | None = None,
     retry_initial_wait: float | None = None,
     retry_jitter: float | None = None,
@@ -484,6 +484,7 @@ def run(
     start_timeout: float | None = None,
     terminal_width: int | None = None,
     skip_interactive_check: bool | None = None,
+    mute_shell_summary: bool | None = None,
 ) -> ShellRun:
     config = _as_config(
         config,
@@ -510,6 +511,7 @@ def run(
         skip_os_env=skip_os_env,
         terminal_width=terminal_width,
         skip_interactive_check=skip_interactive_check,
+        mute_shell_summary=mute_shell_summary,
     )
     assert not config.user_input, (
         "run() does not support user_input (only 1 should be active at a time), use run_and_wait() instead"
@@ -532,7 +534,7 @@ def run_and_wait(
     env: dict[str, str] | None = None,
     extra_popen_kwargs: dict | None = None,
     is_binary_call: bool | None = None,
-    message_callbacks: list[Callable[[ShellRunEventT], bool]] | None = None,
+    message_callbacks: list[ShellRunCallbackT] | None = None,
     print_prefix: str | None = None,
     retry_initial_wait: float | None = None,
     retry_jitter: float | None = None,
@@ -549,6 +551,7 @@ def run_and_wait(
     user_input: bool | None = None,
     terminal_width: int | None = None,
     skip_interactive_check: bool | None = None,
+    mute_shell_summary: bool | None = None,
 ) -> ShellRun:
     config = _as_config(
         script,
@@ -576,6 +579,7 @@ def run_and_wait(
         terminal_width=terminal_width,
         skip_interactive_check=skip_interactive_check,
         skip_progress_output=skip_progress_output,
+        mute_shell_summary=mute_shell_summary,
     )
     run = ShellRun(config)
     future = _pool.submit(_execute_run, run)

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/_internal/_run_env.py

@@ -35,3 +35,12 @@ def interactive_shell() -> bool:
         logger.debug(f"Interactive shell not available: {non_interactive_reason}")
         return False
     return True
+
+
+def resolve_terminal_dimensions(
+    settings: AskShellSettings | None = None,
+) -> tuple[int | None, int | None]:
+    if interactive_shell():
+        return None, None
+    settings = settings or AskShellSettings.from_env()
+    return settings.terminal_width, settings.terminal_height

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/_internal/models.py

@@ -172,6 +172,9 @@ class ShellConfig(Entity):
         default=False,
         description="Skip transitive std out/err output, useful for large outputs that are not needed in the logs when running parallel scripts",
     )
+    mute_shell_summary: bool = Field(
+        default=False, description="Skip shell summary logging useful when you want to ✅ or ❌ in the logs"
+    )
     terminal_width: int | None = 999
 
     # advanced settings

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/_internal/rich_live.py

@@ -13,6 +13,8 @@ from rich.style import Style
 from zero_3rdparty.error import error_and_traceback
 from zero_3rdparty.id_creator import simple_id
 
+from ask_shell._internal._run_env import resolve_terminal_dimensions
+
 _live: Live | None = None
 _lock = RLock()
 
@@ -61,13 +63,20 @@ def _console_hook(func: Callable) -> Callable:
     return wrapper
 
 
+def _live_console() -> Console:
+    width, height = resolve_terminal_dimensions()
+    if width is not None and height is not None:
+        return Console(width=width, height=height)
+    return Console()
+
+
 def get_live() -> Live:
     global _live
     if _live is not None:
         return _live
     with _lock:
         if _live is None:
-            _live = Live(transient=True)
+            _live = Live(transient=True, console=_live_console())
             live_render = _live._live_render
             old_console = live_render.__rich_console__
             live_render.__rich_console__ = _console_hook(old_console)

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/_internal/rich_progress.py

@@ -47,10 +47,16 @@ def log_task_done(
     error: BaseException | None = None,
     description_override: str | None = None,
     extra_parts: list[str] | None = None,
+    soft_failure: bool = False,
 ):
     exit_comji = "❌" if force_error or error is not None else "✅"
     description = description_override or task.description
-    log_call = logger.info if exit_comji == "✅" else logger.error
+    if exit_comji == "✅":
+        log_call = logger.info
+    elif soft_failure:
+        log_call = logger.warning
+    else:
+        log_call = logger.error
     message_parts = [f"{exit_comji} {description}"]
     if rich_task := task._rich_task:
         if finish_time := rich_task.finished_time:

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/_internal/rich_run_state.py

@@ -21,6 +21,7 @@ from ask_shell._internal.models import (
     ShellRunEventT,
 )
 from ask_shell._internal.rich_progress import ProgressManager, log_task_done, new_task
+from ask_shell.settings import ShellRunSummary
 
 
 def _deque_default() -> deque[str]:
@@ -144,6 +145,10 @@ class _RunState:
             task.update(stderr=run_info.stderr_str)
         task.__exit__(None, None, None)
         run = run_info.run
+        if run.config.mute_shell_summary:
+            return
+        if run.config.settings.shell_run_summary == ShellRunSummary.ERRORS_ONLY and run.clean_complete:
+            return
         log_task_done(
             task,
             force_error=not run.clean_complete,
@@ -151,4 +156,5 @@ class _RunState:
             extra_parts=[
                 "" if run.current_attempt == 1 else f"attempt {run.current_attempt}",
             ],
+            soft_failure=run.config.allow_non_zero_exit and not run.clean_complete,
         )

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/settings.py

@@ -1,6 +1,7 @@
 import logging
 import os
 from datetime import datetime, timedelta
+from enum import StrEnum
 from functools import cached_property, lru_cache
 from pathlib import Path
 from pydoc import locate
@@ -90,6 +91,11 @@ LogLevelIgnoredCase: TypeAlias = Annotated[
 ]
 
 
+class ShellRunSummary(StrEnum):
+    ALL = "all"
+    ERRORS_ONLY = "errors_only"
+
+
 class AskShellSettings(StaticSettings):
     model_config = ConfigDict(populate_by_name=True)  # type: ignore
     log_level: LogLevelIgnoredCase = "UNSET"
@@ -136,6 +142,15 @@ class AskShellSettings(StaticSettings):
         description="Runs once If `run_logs_dir` is not set. Can be 'yesterday' or a date string like '2023-01-01'. Will clean all logs up until the specified date but not that date itself.",
         alias=f"{ENV_PREFIX}RUN_LOGS_CLEAN",
     )
+    ENV_NAME_SHELL_RUN_SUMMARY: ClassVar[str] = f"{ENV_PREFIX}SHELL_RUN_SUMMARY"
+    shell_run_summary: ShellRunSummary = Field(
+        default=ShellRunSummary.ALL,
+        alias=ENV_NAME_SHELL_RUN_SUMMARY,
+    )
+    ENV_NAME_TERMINAL_WIDTH: ClassVar[str] = f"{ENV_PREFIX}TERMINAL_WIDTH"
+    terminal_width: int = Field(default=120, alias=ENV_NAME_TERMINAL_WIDTH)
+    ENV_NAME_TERMINAL_HEIGHT: ClassVar[str] = f"{ENV_PREFIX}TERMINAL_HEIGHT"
+    terminal_height: int = Field(default=40, alias=ENV_NAME_TERMINAL_HEIGHT)
 
     @model_validator(mode="after")
     def ensure_vars_set(self) -> Self:

{ask_shell-0.6.0 → ask_shell-0.8.0}/ask_shell/test_docs.py

@@ -3,12 +3,18 @@ from pathlib import Path
 import pytest
 from pytest_examples import CodeExample, EvalExample, find_examples
 
-EXAMPLES_DIR = Path(__file__).parent.parent / "docs" / "examples"
+PACKAGE_ROOT = Path(__file__).parent.parent
+EXAMPLES_DIR = PACKAGE_ROOT / "docs" / "examples"
+
+
+@pytest.fixture(autouse=True)
+def _examples_package_cwd(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.chdir(PACKAGE_ROOT)
 
 
 @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]
+    eval_example.set_config(line_length=120, target_version="py313", ruff_ignore=["T"])  # pyright: ignore[reportArgumentType]
     prefix = example.prefix_settings()
     if prefix.get("test", "").startswith("skip"):
         pytest.skip(prefix["test"])

ask_shell-0.8.0/examples/apply_live/cli.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import typer
+
+from apply_live.stream_handler import PlanStreamHandler, plan_stream_callback
+from ask_shell import console
+from ask_shell.shell import run_and_wait
+
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(
+    name="apply-live",
+    help="Demo terraform apply -json streaming with ask-shell live rendering.",
+)
+
+_DEFAULT_WORKSPACE = Path(__file__).resolve().parent / "workspace"
+
+
+def _run_terraform(command: str, *, workspace: Path) -> int:
+    run = run_and_wait(
+        command,
+        cwd=workspace,
+        allow_non_zero_exit=True,
+        skip_progress_output=True,
+    )
+    return run.exit_code or 0
+
+
+def _terraform_init(*, workspace: Path) -> None:
+    logger.info("running terraform init")
+    if (exit_code := _run_terraform("terraform init -input=false", workspace=workspace)) != 0:
+        raise typer.Exit(exit_code)
+    logger.info("terraform init complete")
+
+
+@app.command()
+def apply(
+    workspace: Path = typer.Option(
+        _DEFAULT_WORKSPACE,
+        "--workspace",
+        "-w",
+        help="Terraform workspace with chained time_sleep resources.",
+        exists=True,
+        file_okay=False,
+    ),
+) -> None:
+    _terraform_init(workspace=workspace)
+
+    handler = PlanStreamHandler()
+    callback = plan_stream_callback(handler)
+    run = run_and_wait(
+        "terraform apply -json -auto-approve",
+        cwd=workspace,
+        allow_non_zero_exit=True,
+        skip_progress_output=True,
+        message_callbacks=[callback],
+    )
+    handler.flush()
+    if (exit_code := run.exit_code or 0) != 0:
+        raise typer.Exit(exit_code)
+    logger.info("apply complete")
+
+
+def main() -> None:
+    console.configure_logging(app)
+    app()
+
+
+if __name__ == "__main__":
+    main()

ask_shell-0.8.0/examples/apply_live/stream_handler.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from enum import StrEnum
+
+from rich.console import Console, ConsoleOptions, RenderResult
+from rich.text import Text
+
+from ask_shell import console as ask_console
+from ask_shell.console import RemoveLivePart, interactive_shell
+from ask_shell.shell_events import ShellRunCallbackT, ShellRunStdOutput
+
+logger = logging.getLogger(__name__)
+
+REFRESH_HEARTBEAT_INTERVAL_S = 5.0
+
+
+class _Phase(StrEnum):
+    REFRESH = "refresh"
+    PLANNING = "planning"
+    DONE = "done"
+
+
+class _PlanStatusRenderable:
+    def __init__(self, handler: PlanStreamHandler) -> None:
+        self._handler = handler
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        status = self._handler._status_line()
+        if status:
+            yield status
+
+
+class PlanStreamHandler:
+    def __init__(self) -> None:
+        self._started = time.monotonic()
+        self._phase = _Phase.REFRESH
+        self._in_flight: set[str] = set()
+        self._done = 0
+        self._planning_emitted = False
+        self._diagnostic_emitted = False
+        self._last_heartbeat = self._started
+        self._carry = ""
+        self._status = _PlanStatusRenderable(self)
+        self._remove_panel: RemoveLivePart | None = ask_console.add_renderable(
+            self._status, order=10, name="plan-status"
+        )
+
+    def feed_line(self, chunk: str) -> None:
+        self._carry += chunk
+        while "\n" in self._carry:
+            line, self._carry = self._carry.split("\n", 1)
+            stripped = line.strip()
+            if stripped:
+                self._handle_line(stripped)
+
+    def flush(self) -> None:
+        if self._carry.strip():
+            self._handle_line(self._carry.strip())
+        self._carry = ""
+        self._remove_status_panel()
+
+    def _handle_line(self, line: str) -> None:
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            logger.debug(f"skipping non-json plan stream line: {line[:120]!r}")
+            return
+        msg_type = data.get("type")
+        match msg_type:
+            case "diagnostic":
+                self._emit_diagnostic(data)
+            case "refresh_start" | "apply_start":
+                self._on_refresh_start(data)
+            case "refresh_complete" | "apply_complete":
+                self._on_refresh_complete(data)
+            case "change_summary":
+                if (data.get("changes") or {}).get("operation") == "apply":
+                    self._phase = _Phase.DONE
+            case "resource_drift" | "outputs" | "log":
+                self._leave_refresh_phase()
+            case _:
+                pass
+        self._maybe_heartbeat()
+
+    def _emit_diagnostic(self, data: dict) -> None:
+        diagnostic = data.get("diagnostic") or {}
+        summary = diagnostic.get("summary")
+        if not summary:
+            return
+        if not self._diagnostic_emitted:
+            self._diagnostic_emitted = True
+            ask_console.print_to_live("")
+        severity = (diagnostic.get("severity") or "error").capitalize()
+        ask_console.print_to_live(f"{severity}: {summary}")
+        if detail := diagnostic.get("detail"):
+            ask_console.print_to_live(detail)
+
+    def _on_refresh_start(self, data: dict) -> None:
+        if addr := _resource_addr(data):
+            self._in_flight.add(addr)
+
+    def _on_refresh_complete(self, data: dict) -> None:
+        if addr := _resource_addr(data):
+            self._in_flight.discard(addr)
+        self._done += 1
+
+    def _leave_refresh_phase(self) -> None:
+        if self._phase != _Phase.REFRESH:
+            return
+        self._phase = _Phase.PLANNING
+        self._emit_planning_once()
+
+    def _emit_planning_once(self) -> None:
+        if self._planning_emitted:
+            return
+        self._planning_emitted = True
+        ask_console.print_to_live("plan: computing changes…")
+
+    def _status_line(self) -> Text | None:
+        if self._phase == _Phase.DONE:
+            return None
+        if self._phase == _Phase.PLANNING:
+            return Text("planning…", style="cyan")
+        return self._refresh_status(time.monotonic() - self._started)
+
+    def _refresh_status(self, elapsed_s: float) -> Text:
+        mins, secs = divmod(int(elapsed_s), 60)
+        elapsed = f"{mins}m {secs:02d}s" if mins else f"{secs}s"
+        return Text.assemble(
+            ("refresh", "cyan"),
+            " · ",
+            (str(self._done), "bold"),
+            " done · ",
+            (str(len(self._in_flight)), "bold"),
+            " running · ",
+            (elapsed, "dim"),
+        )
+
+    def _maybe_heartbeat(self) -> None:
+        if interactive_shell() or self._phase != _Phase.REFRESH:
+            return
+        now = time.monotonic()
+        if now - self._last_heartbeat < REFRESH_HEARTBEAT_INTERVAL_S:
+            return
+        self._last_heartbeat = now
+        logger.info(self._heartbeat_message(now - self._started))
+
+    def _heartbeat_message(self, elapsed_s: float) -> str:
+        mins, secs = divmod(int(elapsed_s), 60)
+        elapsed = f"{mins}m {secs:02d}s" if mins else f"{secs}s"
+        return f"refresh: {self._done} complete, {len(self._in_flight)} in progress ({elapsed})"
+
+    def _remove_status_panel(self) -> None:
+        if self._remove_panel is None:
+            return
+        self._remove_panel()
+        self._remove_panel = None
+
+
+def _resource_addr(data: dict) -> str | None:
+    hook = data.get("hook") or {}
+    resource = hook.get("resource") or {}
+    match resource.get("addr"):
+        case str(addr):
+            return addr
+        case _:
+            return None
+
+
+def plan_stream_callback(handler: PlanStreamHandler) -> ShellRunCallbackT:
+    def callback(message: object) -> bool:
+        match message:
+            case ShellRunStdOutput(is_stdout=True, content=content):
+                handler.feed_line(content)
+        return False
+
+    return callback

{ask_shell-0.6.0 → ask_shell-0.8.0}/pyproject.toml

@@ -2,7 +2,7 @@
 
 [project]
 name = "ask-shell"
-version = "0.6.0"
+version = "0.8.0"
 description = "CLIs with prompts, shell runs, and testable flows"
 requires-python = ">=3.13"
 license = "MIT"
@@ -41,6 +41,11 @@ examples_include = [
   "AbortRetryError",
 ]
 
+[tool.pkg-ext.groups.console]
+examples_include = [
+  "add_renderable",
+]
+
 
 # === DO_NOT_EDIT: path-sync ruff ===
 [tool.ruff]
@@ -59,6 +64,9 @@ extend-ignore = ["E501", "UP006", "UP007", "UP035", "UP040", "UP046", "UP047"]
 extend-select = ["Q", "RUF100", "C90", "UP", "I", "T", "FURB"]
 # === OK_EDIT: path-sync ruff ===
 
+[tool.ruff.lint.isort]
+known-first-party = ["ask_shell"]
+
 # === DO_NOT_EDIT: path-sync pytest ===
 [tool.pytest.ini_options]
 addopts = "-s -vv --log-cli-level=INFO -m 'not manual'"
@@ -107,3 +115,12 @@ docs = [
   "mkdocs-material>=9.5",
 ]
 # === OK_EDIT: path-sync docs ===
+# === DO_NOT_EDIT: path-sync wheel ===
+[tool.hatch.build.targets.wheel]
+exclude = [
+  "*_examples.py",
+  "*_test.py",
+  "conftest.py",
+  "*_test/",
+]
+# === OK_EDIT: path-sync wheel ===