bear-utils 0.0.1__py3-none-any.whl

bear_utils/cli/prompt_helpers.py

@@ -0,0 +1,186 @@
+"""Prompt Helpers Module for user input handling."""
+
+from typing import Any, overload
+
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.validation import ValidationError, Validator
+
+from bear_utils.constants._exceptions import UserCancelledError
+from bear_utils.constants._lazy_typing import OptBool, OptFloat, OptInt, OptStr
+from bear_utils.logger_manager import get_console
+
+
+def _parse_exit(value: str) -> bool:
+    """Parse a string into a boolean indicating if the user wants to exit."""
+    lower_value: str = value.lower().strip()
+    return lower_value in ("exit", "quit", "q")
+
+
+def _parse_bool(value: str) -> bool:
+    """Parse a string into a boolean value."""
+    lower_value: str = value.lower().strip()
+    if lower_value in ("true", "t", "yes", "y", "1"):
+        return True
+    if lower_value in ("false", "f", "no", "n", "0"):
+        return False
+    raise ValueError(f"Cannot convert '{value}' to boolean")
+
+
+def _convert_value(value: str, target_type: type) -> str | int | float | bool:
+    """Convert a string value to the target type."""
+    if target_type is str:
+        return value
+    if target_type is int:
+        return int(value)
+    if target_type is float:
+        return float(value)
+    if target_type is bool:
+        return _parse_bool(value)
+    raise ValueError(f"Unsupported type: {target_type}")
+
+
+@overload
+def ask_question(question: str, expected_type: type[bool], default: OptBool = None) -> bool: ...
+
+
+@overload
+def ask_question(question: str, expected_type: type[int], default: OptInt = None) -> int: ...
+
+
+@overload
+def ask_question(question: str, expected_type: type[float], default: OptFloat = None) -> float: ...
+
+
+@overload
+def ask_question(question: str, expected_type: type[str], default: OptStr = None) -> str: ...
+
+
+def ask_question(question: str, expected_type: type, default: Any = None) -> Any:
+    """Ask a question and return the answer, ensuring the entered type is correct.
+
+    This function will keep asking until it gets a valid response or the user cancels with Ctrl+C.
+    If the user cancels, a UserCancelledError is raised.
+
+    Args:
+        question: The prompt question to display
+        expected_type: The expected type class (int, float, str, bool)
+        default: Default value if no input is provided
+
+    Returns:
+        The user's response in the expected type
+
+    Raises:
+        UserCancelledError: If the user cancels input with Ctrl+C
+        ValueError: If an unsupported type is specified
+    """
+    console, _ = get_console("prompt_helpers.py")
+
+    try:
+        while True:
+            console.print(question)
+            response = prompt("> ").strip()
+
+            if not response:
+                if default is not None:
+                    return default
+                console.error("Input required. Please enter a value.")
+                continue
+            try:
+                result: str | int | float | bool = _convert_value(response, expected_type)
+                console.verbose(f"{expected_type.__name__} detected")
+                return result
+            except ValueError as e:
+                console.error(f"Invalid input: {e}. Please enter a valid {expected_type.__name__}.")
+
+    except KeyboardInterrupt:
+        raise UserCancelledError("User cancelled input") from None
+
+
+def ask_yes_no(question: str, default: bool | None = None) -> bool | None:
+    """Ask a yes or no question and return the answer.
+
+    Args:
+        question: The prompt question to display
+        default: Default value if no input is provided
+
+    Returns:
+        True for yes, False for no, or None if user exits
+    """
+    console, _ = get_console("prompt_helpers.py")
+
+    while True:
+        try:
+            response: str = prompt(f"{question}\n> ").strip().lower()
+            if not response:
+                if default is not None:
+                    return default
+                console.print("Please enter 'yes', 'no', or 'exit'.")
+                continue
+            if _parse_exit(response):
+                return None
+            try:
+                return _parse_bool(response)
+            except ValueError:
+                console.print("Invalid input. Please enter 'yes', 'no', or 'exit'.", style="red")
+        except KeyboardInterrupt:
+            console.print("KeyboardInterrupt: Exiting the prompt.", style="yellow")
+            return None
+
+
+def restricted_prompt(
+    question: str,
+    valid_options: list[str],
+    exit_command: str = "exit",
+    case_sensitive: bool = False,
+) -> str | None:
+    """Continuously prompt the user until they provide a valid response or exit.
+
+    Args:
+        question: The prompt question to display
+        valid_options: List of valid responses
+        exit_command: Command to exit the prompt (default: "exit")
+        case_sensitive: Whether options are case-sensitive (default: False)
+
+    Returns:
+        The user's response or None if they chose to exit
+    """
+    console, _ = get_console("prompt_helpers.py")
+    completer_options: list[str] = [*valid_options, exit_command]
+    completer = WordCompleter(completer_options)
+
+    comparison_options: list[str] = valid_options if case_sensitive else [opt.lower() for opt in valid_options]
+    comparison_exit: str = exit_command if case_sensitive else exit_command.lower()
+
+    class OptionValidator(Validator):
+        def validate(self, document: Any) -> None:
+            """Validate the user's input against the valid options."""
+            text: Any = document.text if case_sensitive else document.text.lower()
+            if text and text != comparison_exit and text not in comparison_options:
+                raise ValidationError(
+                    message=f"Invalid option. Choose from: {', '.join(valid_options)} or '{exit_command}'",
+                    cursor_position=len(document.text),
+                )
+
+    try:
+        while True:
+            response: str = prompt(
+                f"{question}\n> ",
+                completer=completer,
+                validator=OptionValidator(),
+                complete_while_typing=True,
+            ).strip()
+            comparison_response: str = response if case_sensitive else response.lower()
+            if not response:
+                console.print("Please enter a valid option or 'exit'.", style="red")
+                continue
+            if comparison_response == comparison_exit:
+                return None
+            if comparison_response in comparison_options:
+                if not case_sensitive:
+                    idx: int = comparison_options.index(comparison_response)
+                    return valid_options[idx]
+                return response
+    except KeyboardInterrupt:
+        console.print("KeyboardInterrupt: Exiting the prompt.", style="yellow")
+        return None

bear_utils/cli/shell/__init__.py

@@ -0,0 +1 @@
+"""Shell utilities for bear_utils CLI."""

bear_utils/cli/shell/_base_command.py

@@ -0,0 +1,81 @@
+from subprocess import CompletedProcess
+from typing import Any, ClassVar, Self
+
+
+class BaseShellCommand[T: str]:
+    """Base class for typed shell commands compatible with session systems"""
+
+    command_name: ClassVar[str] = ""
+
+    def __init__(self, *args, **kwargs) -> None:
+        self.sub_command: str = kwargs.get("sub_command", "")
+        self.args = args
+        self.kwargs: dict[str, Any] = kwargs
+        self.suffix = kwargs.get("suffix", "")
+        self.result: CompletedProcess[str] | None = None
+
+    def __str__(self) -> str:
+        """String representation of the command"""
+        return self.cmd
+
+    def value(self, v: str) -> Self:
+        """Add value to the export command"""
+        self.suffix: str = v
+        return self
+
+    @classmethod
+    def adhoc(cls, name: T, *args, **kwargs) -> "BaseShellCommand[T]":
+        """Create an ad-hoc command class for a specific command
+
+        Args:
+            name (str): The name of the command to create
+
+        Returns:
+            BaseShellCommand: An instance of the ad-hoc command class.
+        """
+        return type(
+            f"AdHoc{name.title()}Command",
+            (cls,),
+            {"command_name": name},
+        )(*args, **kwargs)
+
+    @classmethod
+    def sub(cls, s: str, *args, **kwargs) -> Self:
+        """Set a sub-command for the shell command"""
+        return cls(s, *args, **kwargs)
+
+    @property
+    def cmd(self) -> str:
+        """Return the full command as a string"""
+        cmd_parts: list[str] = [self.command_name, self.sub_command, *self.args]
+        cmd_parts: list[str] = [part for part in cmd_parts if part]
+        joined: str = " ".join(cmd_parts).strip()
+        if self.suffix:
+            return f"{joined} {self.suffix}"
+        return joined
+
+    def do(self, **kwargs) -> Self:
+        """Run the command using subprocess"""
+        from ._base_shell import shell_session  # noqa: PLC0415
+
+        with shell_session(**kwargs) as session:
+            result: CompletedProcess[str] = session.add(self.cmd).run()
+        if result is not None:
+            self.result = result
+        return self
+
+    def get_result(self) -> CompletedProcess[str]:
+        """Get the result of the command execution"""
+        if self.result is None:
+            self.do()
+        if self.result is None:
+            raise RuntimeError("Command execution failed for some reason.")
+        return self.result
+
+    def get(self) -> str:
+        """Get the result of the command execution"""
+        if self.result is None:
+            self.do()
+        if self.result is None:
+            raise RuntimeError("Command execution failed for some reason.")
+        return str(self.result.stdout).strip()

bear_utils/cli/shell/_base_shell.py

@@ -0,0 +1,430 @@
+import asyncio
+from asyncio.streams import StreamReader
+from asyncio.subprocess import Process
+from collections import deque
+from collections.abc import AsyncGenerator, Callable, Generator
+from contextlib import asynccontextmanager, contextmanager
+from io import StringIO
+from logging import INFO
+import os
+from pathlib import Path
+import shlex
+import subprocess
+from subprocess import CompletedProcess
+from typing import Self, override
+
+from bear_utils.constants import ExitCode
+from bear_utils.logger_manager import VERBOSE, BaseLogger, SubConsoleLogger
+from bear_utils.logger_manager.logger_protocol import LoggerProtocol
+
+from ._base_command import BaseShellCommand
+from ._common import DEFAULT_SHELL
+
+
+class FancyCompletedProcess(CompletedProcess[str]):
+    def __init__(self, args: list[str], returncode: int, stdout: str | None = None, stderr: str | None = None) -> None:
+        """Initialize with custom attributes for better readability"""
+        super().__init__(args=args, returncode=returncode, stdout=stdout, stderr=stderr)
+
+    def __repr__(self) -> str:
+        """Custom representation for better readability"""
+        args: list[str] = [
+            f"args={self.args!r}",
+            f"returncode={self.returncode!r}",
+            f"exit_message={self.exit_message!r}",
+            f"stdout={self.stdout!r}" if self.stdout is not None else "",
+            f"stderr={self.stderr!r}" if self.stderr is not None else "",
+        ]
+        return f"{type(self).__name__}({', '.join(filter(None, args))})"
+
+    @property
+    def exit_message(self) -> str:
+        """Get a human-readable message for the exit code"""
+        return ExitCode.from_int(self.returncode).text
+
+
+class CommandList(deque[CompletedProcess[str]]):
+    """A list to hold previous commands with their timestamps and results"""
+
+    def __init__(self, maxlen: int = 10, *args, **kwargs) -> None:
+        super().__init__(maxlen=maxlen, *args, **kwargs)  # noqa:  B026
+
+    def add(self, command: CompletedProcess[str]) -> None:
+        """Add a command to the list"""
+        self.append(command)
+
+    def get(self, index: int) -> CompletedProcess[str] | None:
+        """Get a command by index"""
+        return self[index] if 0 <= index < len(self) else None
+
+    def get_most_recent(self) -> CompletedProcess[str] | None:
+        """Get the most recent command"""
+        return self[-1] if self else None
+
+
+class SimpleShellSession:
+    """Simple shell session using subprocess with command chaining"""
+
+    def __init__(
+        self,
+        env: dict | None = None,
+        cwd: Path | str | None = None,
+        shell: str = DEFAULT_SHELL,
+        logger: LoggerProtocol | BaseLogger | None = None,
+        verbose: bool = False,
+        use_shell: bool = True,
+    ) -> None:
+        self.shell: str = shell
+        self.cwd: Path = Path.cwd() if cwd is None else Path(cwd)
+        self.env: dict[str, str] = os.environ.copy() if env is None else env
+        self.cmd_buffer: StringIO = StringIO()
+        self.previous_commands: CommandList = CommandList()
+        self.result: CompletedProcess[str] | None = None
+        self.verbose: bool = verbose
+        self.use_shell: bool = use_shell
+        self.logger: LoggerProtocol | BaseLogger | SubConsoleLogger[BaseLogger] = self.set_logger(logger)
+
+    def set_logger(
+        self, passed_logger: LoggerProtocol | BaseLogger | None = None
+    ) -> LoggerProtocol | BaseLogger | SubConsoleLogger[BaseLogger]:
+        """Set the logger for the session, defaulting to a base logger if none is provided"""
+        if passed_logger is not None:
+            return passed_logger
+
+        if BaseLogger.has_instance():
+            logger = BaseLogger.get_instance().get_sub_logger(namespace="shell_session")
+        else:
+            temp: BaseLogger = BaseLogger.get_instance(init=True)
+            logger: SubConsoleLogger[BaseLogger] = temp.get_sub_logger(namespace="shell_session")
+        if self.verbose:
+            logger.set_sub_level(VERBOSE)
+        else:
+            logger.set_sub_level(INFO)
+        return logger
+
+    def add_to_env(self, env: dict[str, str], key: str | None = None, value: str | None = None) -> Self:
+        """Populate the environment for the session"""
+        _env = {}
+        if isinstance(env, str) and key is not None and value is not None:
+            _env[key] = value
+        elif isinstance(env, dict):
+            for k, v in env.items():
+                _env[k] = v
+        self.env.update(_env)
+        return self
+
+    def add(self, c: str | BaseShellCommand) -> Self:
+        """Add a command to the current session, return self for chaining"""
+        self.cmd_buffer.write(str(c))
+        return self
+
+    def amp(self, c: str | BaseShellCommand) -> Self:
+        """Combine a command with the current session: &&, return self for chaining"""
+        if self.empty_history:
+            raise ValueError("No command to combine with")
+        self.cmd_buffer.write(" && ")
+        self.cmd_buffer.write(str(c))
+        return self
+
+    def piped(self, c: str | BaseShellCommand) -> Self:
+        """Combine a command with the current session: |, return self for chaining"""
+        if self.empty_history:
+            raise ValueError("No command to pipe from")
+        self.cmd_buffer.write(" | ")
+        self.cmd_buffer.write(str(c))
+        return self
+
+    def _run(self, command: str) -> CompletedProcess[str]:
+        """Internal method to run the accumulated command"""
+        self.logger.debug(f"Executing: {command}")
+        self.next_cmd()
+
+        if self.use_shell:
+            self.result = subprocess.run(
+                check=False,
+                args=command,
+                shell=True,
+                cwd=self.cwd,
+                env=self.env,
+                capture_output=True,
+                text=True,
+            )
+        else:
+            command_args: list[str] = shlex.split(command)
+            self.result = subprocess.run(
+                check=False,
+                args=command_args,
+                shell=False,
+                cwd=self.cwd,
+                env=self.env,
+                capture_output=True,
+                text=True,
+            )
+
+        if self.result.returncode != 0:
+            self.logger.error(f"Command failed with return code {self.result.returncode} {self.result.stderr.strip()}")
+
+        self.reset_buffer()
+        return self.result
+
+    def run(self, cmd: str | BaseShellCommand | None = None, *args) -> CompletedProcess[str]:
+        """Run the accumulated command history"""
+        if self.empty_history and cmd is None:
+            raise ValueError("No commands to run")
+
+        if self.has_history and cmd is not None:
+            raise ValueError(
+                "If you want to add a command to a chain, use `amp` instead of `run`, `run` is for executing the full command history"
+            )
+
+        if self.has_history and cmd is None:
+            result: CompletedProcess[str] = self._run(self.cmd)
+        elif self.empty_history and cmd is not None:
+            self.cmd_buffer.write(f"{cmd} ")
+            if args:
+                self.cmd_buffer.write(" ".join(map(str, args)))
+            result: CompletedProcess[str] = self._run(self.cmd)
+        else:
+            raise ValueError("Unexpected state")
+        self.reset_buffer()
+        return result
+
+    @property
+    def empty_history(self) -> bool:
+        """Check if the command history is empty"""
+        return not self.cmd_buffer.getvalue()
+
+    @property
+    def has_history(self) -> bool:
+        """Check if there is any command in the history"""
+        return not self.empty_history
+
+    @property
+    def cmd(self) -> str:
+        """Return the combined command as a string"""
+        if not self.cmd_buffer:
+            raise ValueError("No commands have been run yet")
+
+        if self.use_shell:
+            # Original behavior: wrap in shell command
+            full_command: str = f"{self.shell} -c {shlex.quote(self.cmd_buffer.getvalue())}"
+        else:
+            # New behavior: return raw command for argument parsing
+            full_command: str = self.cmd_buffer.getvalue().strip()
+
+        return full_command
+
+    @property
+    def returncode(self) -> bool:
+        """Return the last command's return code"""
+        if self.result is None:
+            raise ValueError("No command has been run yet")
+        return self.result.returncode == 0
+
+    @property
+    def stdout(self) -> str:
+        """Return the standard output of the last command"""
+        if self.result is None:
+            raise ValueError("No command has been run yet")
+        return self.result.stdout.strip() if self.result.stdout is not None else "None"
+
+    @property
+    def stderr(self) -> str:
+        """Return the standard error of the last command"""
+        if self.result is None:
+            raise ValueError("No command has been run yet")
+        return self.result.stderr.strip() if self.result.stderr is not None else "None"
+
+    @property
+    def pretty_result(self) -> str:
+        """Return a formatted string of the command result"""
+        if self.result is None:
+            raise ValueError("No command has been run yet")
+        return (
+            f"Command: {self.result.args}\n"
+            f"Return Code: {self.result.returncode}\n"
+            f"Standard Output: {self.result.stdout.strip()}\n"
+            f"Standard Error: {self.result.stderr.strip()}\n"
+        )
+
+    def reset_buffer(self) -> None:
+        """Reset the command buffer"""
+        self.cmd_buffer.seek(0)
+        self.cmd_buffer.truncate(0)
+
+    def reset(self) -> None:
+        """Reset the session state"""
+        self.previous_commands.clear()
+        self.result = None
+
+    def next_cmd(self) -> None:
+        """Store the current command in the history before running a new one"""
+        if self.result is not None:
+            self.previous_commands.add(command=self.result)
+            self.result = None
+
+    def get_cmd(self, index: int | None = None) -> CompletedProcess[str] | None:
+        """Get a previous command by index or the most recent one if index is None"""
+        if index is None:
+            return self.previous_commands.get_most_recent()
+        return self.previous_commands.get(index)
+
+    def __enter__(self) -> Self:
+        """Enter the context manager"""
+        return self
+
+    def __exit__(self, exc_type: object, exc_value: object, traceback: object) -> None:
+        """Exit the context manager"""
+        self.reset()
+        self.reset_buffer()
+
+
+class AsyncShellSession(SimpleShellSession):
+    """Shell session using Popen for more control over the subprocess"""
+
+    def __init__(
+        self,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+        shell: str = DEFAULT_SHELL,
+        logger: LoggerProtocol | BaseLogger | None = None,
+        verbose: bool = False,
+        use_shell: bool = True,
+    ) -> None:
+        super().__init__(env=env, cwd=cwd, shell=shell, logger=logger, verbose=verbose, use_shell=use_shell)
+        self.process: Process | None = None
+        self._callbacks: list[Callable[[CompletedProcess], None]] = []
+
+    @override
+    async def _run(self, command: str, **kwargs) -> Process:  # type: ignore[override]
+        """Run the command using Popen for better control"""
+        self.logger.debug(f"Executing: {command}")
+        self.next_cmd()
+
+        if self.use_shell:
+            self.process = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=self.cwd,
+                env=self.env,
+                **kwargs,
+            )
+        else:
+            command_args: list[str] = shlex.split(command)
+            self.process = await asyncio.create_subprocess_exec(
+                *command_args,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=self.cwd,
+                env=self.env,
+                **kwargs,
+            )
+        return self.process
+
+    @override
+    async def run(self, cmd: str | BaseShellCommand | None = None, *args, **kwargs) -> Process:  # type: ignore[override]
+        """Async version of run that returns Process for streaming"""
+        if self.empty_history and cmd is None:
+            raise ValueError("No commands to run")
+
+        if self.has_history and cmd is not None:
+            raise ValueError("Use `amp` to chain commands, not `run`")
+        if self.has_history and cmd is None:
+            command: str = self.cmd
+        elif self.empty_history and cmd is not None:
+            self.cmd_buffer.write(f"{cmd}")
+            if args:
+                self.cmd_buffer.write(" ".join(map(str, args)))
+            command: str = self.cmd
+        else:
+            raise ValueError("Unexpected state")
+        process: Process = await self._run(command, **kwargs)
+        return process
+
+    async def communicate(self, stdin: str = "") -> CompletedProcess[str]:
+        """Communicate with the process, sending input and waiting for completion"""
+        if self.process is None:
+            raise ValueError("No process has been started yet")
+        bytes_stdin: bytes = stdin.encode("utf-8") if isinstance(stdin, str) else stdin
+
+        stdout, stderr = await self.process.communicate(input=bytes_stdin)
+        return_code: int = await self.process.wait()
+
+        self.result = FancyCompletedProcess(
+            args=self.cmd,  # type: ignore  FIXME: should be a list[str] not str?
+            returncode=return_code,
+            stdout=stdout.decode() if stdout else "",
+            stderr=stderr.decode() if stderr else "",
+        )
+        if return_code != 0:
+            self.logger.error(f"Command failed with return code {return_code} {stderr.strip()}")
+        for callback in self._callbacks:
+            callback(self.result)
+        await self.after_process()
+        return self.result
+
+    @staticmethod
+    async def read_stream(stream: StreamReader) -> AsyncGenerator[str]:
+        while True:
+            try:
+                line: bytes = await stream.readline()
+                if not line:  # EOF
+                    break
+                yield line.decode("utf-8").rstrip("\n")
+            except Exception:
+                break
+
+    async def stream_stdout(self) -> AsyncGenerator[str]:
+        """Stream output line by line as it comes"""
+        if self.process is None:
+            raise ValueError("No process has been started yet")
+        if not self.process.stdout:
+            raise ValueError("Process has no stdout")
+
+        async for line in self.read_stream(self.process.stdout):
+            yield line
+
+    async def stream_stderr(self) -> AsyncGenerator[str]:
+        """Stream error output line by line as it comes"""
+        if self.process is None:
+            raise ValueError("No process has been started yet")
+        if not self.process.stderr:
+            raise ValueError("Process has no stderr")
+        async for line in self.read_stream(self.process.stderr):
+            yield line
+
+    async def after_process(self) -> None:
+        """Run after process completion, can be overridden for custom behavior"""
+        self.process = None
+        self._callbacks.clear()
+        self.reset_buffer()
+
+    def on_completion(self, callback: Callable[[CompletedProcess[str]], None]) -> None:
+        """Add callback for when process completes"""
+        self._callbacks.append(callback)
+
+    @property
+    def is_running(self) -> bool:
+        """Check if process is still running"""
+        return self.process is not None and self.process.returncode is None
+
+
+@contextmanager
+def shell_session(shell: str = DEFAULT_SHELL, **kwargs) -> Generator[SimpleShellSession]:
+    """Context manager for simple shell sessions"""
+    session = SimpleShellSession(shell=shell, **kwargs)
+    try:
+        yield session
+    finally:
+        pass
+
+
+@asynccontextmanager
+async def async_shell_session(shell: str = DEFAULT_SHELL, **kwargs) -> AsyncGenerator[AsyncShellSession]:
+    """Asynchronous context manager for shell sessions"""
+    session = AsyncShellSession(shell=shell, **kwargs)
+    try:
+        yield session
+    finally:
+        pass