kash-shell 0.3.0__py3-none-any.whl

kash/shell/ui/shell_syntax.py

@@ -0,0 +1,26 @@
+import re
+
+from kash.utils.common.parse_shell_args import shell_quote
+
+
+def is_assist_request_str(line: str) -> str | None:
+    """
+    Is this a query to the assistant?
+    Checks for phrases ending in a ? or starting with a ?.
+    """
+    line = line.strip()
+    if re.search(r"\b\w+\?$", line) or line.startswith("?"):
+        return line.lstrip("?").strip()
+    return None
+
+
+def assist_request_str(nl_req: str) -> str:
+    """
+    Command string to call the assistant with a natural language request.
+    """
+    nl_req = nl_req.lstrip("? ").rstrip()
+    # Quoting isn't necessary unless we have quote marks.
+    if "'" in nl_req or '"' in nl_req:
+        return f"? {shell_quote(nl_req, idempotent=True)}"
+    else:
+        return f"? {nl_req}"

kash/shell/utils/exception_printing.py

@@ -0,0 +1,50 @@
+from collections.abc import Callable
+from functools import wraps
+from typing import TypeVar
+
+from kash.config.logger import get_logger
+from kash.config.text_styles import COLOR_ERROR
+from kash.errors import NONFATAL_EXCEPTIONS
+from kash.shell.output.shell_output import PrintHooks
+
+log = get_logger(__name__)
+
+
+def summarize_traceback(exception: Exception) -> str:
+    exception_str = str(exception)
+    lines = exception_str.splitlines()
+    exc_type = type(exception).__name__
+    return f"{exc_type}: " + "\n".join(
+        [
+            line
+            for line in lines
+            if line.strip()
+            and not line.lstrip().startswith("Traceback")
+            # and not line.lstrip().startswith("File ")
+            and not line.lstrip().startswith("The above exception")
+            and not line.startswith("    ")
+        ]
+        + ["\nRun `logs` for details."]
+    )
+
+
+R = TypeVar("R")
+
+
+def wrap_with_exception_printing(func: Callable[..., R]) -> Callable[[list[str]], R | None]:
+    @wraps(func)
+    def command(*args) -> R | None:
+        try:
+            log.info(
+                "Command function call: %s(%s)",
+                func.__name__,
+                (", ".join(str(arg) for arg in args)),
+            )
+            return func(*args)
+        except NONFATAL_EXCEPTIONS as e:
+            PrintHooks.nonfatal_exception()
+            log.error(f"[{COLOR_ERROR}]Command error:[/{COLOR_ERROR}] %s", summarize_traceback(e))
+            log.info("Command error details: %s", e, exc_info=True)
+            return None
+
+    return command

kash/shell/utils/native_utils.py

@@ -0,0 +1,240 @@
+"""
+Platform-specific tools and utilities.
+"""
+
+import os
+import shlex
+import subprocess
+import urllib.parse
+import webbrowser
+from enum import Enum
+from pathlib import Path
+
+from flowmark import Wrap
+from funlog import log_calls
+
+from kash.config.logger import get_logger
+from kash.config.text_styles import BAT_STYLE, BAT_THEME, COLOR_ERROR
+from kash.errors import FileNotFound, SetupError
+from kash.shell.output.shell_output import cprint
+from kash.shell.utils.sys_tool_deps import PLATFORM, Platform, SysTool, sys_tool_check
+from kash.shell.utils.terminal_images import terminal_show_image
+from kash.utils.common.format_utils import fmt_loc
+from kash.utils.common.url import as_file_url, is_file_url, is_url
+from kash.utils.file_utils.file_formats import is_full_html_page, read_partial_text
+from kash.utils.file_utils.file_formats_model import file_format_info
+
+log = get_logger(__name__)
+
+
+def file_size_check(
+    filename: str | Path, max_lines: int = 100, max_bytes: int = 50 * 1024
+) -> tuple[int, int]:
+    """
+    Get the size and scan to get initial line count (up to max_lines) of a file.
+    """
+    filename = str(filename)
+    file_size = os.path.getsize(filename)
+    line_min = 0
+    with open(filename, "rb") as f:
+        for i, _line in enumerate(f):
+            if i >= max_lines or f.tell() > max_bytes:
+                break
+            line_min += 1
+    return file_size, line_min
+
+
+def native_open(filename: str | Path):
+    filename = str(filename)
+    log.message("Opening file: %s", filename)
+    if PLATFORM == Platform.Darwin:
+        subprocess.run(["open", filename])
+    elif PLATFORM == Platform.Linux:
+        subprocess.run(["xdg-open", filename])
+    elif PLATFORM == Platform.Windows:
+        subprocess.run(["start", shlex.quote(filename)], shell=True)
+    else:
+        raise NotImplementedError("Unsupported platform")
+
+
+def native_open_url(url_or_query: str):
+    """
+    Open a URL or query in the system's default browser.
+    """
+    log.message("Opening in browser: %s", url_or_query)
+    if is_url(url_or_query):
+        webbrowser.open(url_or_query)
+    else:
+        webbrowser.open(f"https://www.google.com/search?q={urllib.parse.quote(url_or_query)}")
+
+
+class ViewMode(Enum):
+    auto = "auto"
+    console = "console"
+    browser = "browser"
+    native = "native"
+    terminal_image = "terminal_image"
+
+
+@log_calls(level="info")
+def _detect_view_mode(file_or_url: str) -> ViewMode:
+    # As a heuristic, we use the browser for URLs and for local files that are
+    # clearly full HTML pages (since HTML fragments are fine on console).
+    if is_url(file_or_url) and not is_file_url(file_or_url):
+        return ViewMode.browser
+
+    path = Path(file_or_url)
+    if path.is_file():  # File or symlink.
+        content = read_partial_text(path)
+        if content and is_full_html_page(content):
+            return ViewMode.browser
+
+        info = file_format_info(path)
+        log.info("File format detected: %s", info)
+
+        if info.is_text:
+            return ViewMode.console
+        if info.is_image:
+            log.info("Detected image file, will display in terminal")
+            return ViewMode.terminal_image
+        else:
+            return ViewMode.native
+    elif path.is_dir():
+        return ViewMode.native
+    else:
+        raise FileNotFound(fmt_loc(file_or_url))
+
+
+def view_file_native(
+    file_or_url: str | Path,
+    view_mode: ViewMode = ViewMode.auto,
+):
+    """
+    Open a file or URL in the console or a native app. If `view_mode` is auto,
+    automatically determine whether to use console, web browser, or the user's
+    preferred native application. For images, also tries terminal-based image
+    display.
+    """
+    file_or_url = str(file_or_url)
+    path = None
+    if not is_url(file_or_url):
+        path = Path(file_or_url)
+        if not path.exists():
+            raise FileNotFound(fmt_loc(path))
+
+    if view_mode == ViewMode.auto:
+        view_mode = _detect_view_mode(file_or_url)
+
+    if view_mode == ViewMode.browser:
+        url = file_or_url if is_url(file_or_url) else as_file_url(file_or_url)
+        log.message("Opening URL in browser: %s", url)
+        webbrowser.open(url)
+    elif view_mode == ViewMode.console and path:
+        file_size, min_lines = file_size_check(path)
+        view_file_console(path, use_pager=min_lines > 40 or file_size > 20 * 1024)
+    elif view_mode == ViewMode.terminal_image and path:
+        try:
+            terminal_show_image(path)
+        except SetupError as e:
+            log.info("%s: %s", e, path)
+            native_open(path)
+    elif view_mode == ViewMode.native:
+        native_open(file_or_url)
+    else:
+        raise ValueError(f"Don't know how to view: {view_mode}: {file_or_url}")
+
+
+def tail_file(
+    filename: str | Path,
+    follow: bool = False,
+    max_lines: int = 10000,
+    follow_max_lines: int = 200,
+):
+    """
+    Tail a log file. With colorization using bat if available, otherwise using less.
+    If follow is True, follows the file as it grows.
+
+    Uses bat if available. Note bat doesn't have efficient seek functionality like
+    `less +G` so we prefer to use bat with less. Use Ctrl-C to quit less (this is
+    enabled with `less -K`).
+    """
+    filename = str(filename)
+    quoted_filename = shlex.quote(filename)
+
+    if follow:
+        max_lines = follow_max_lines
+
+    sys_tool_check().require(SysTool.less)
+    sys_tool_check().warn_if_missing(SysTool.bat, SysTool.tail)
+
+    if follow:
+        if sys_tool_check().has(SysTool.bat, SysTool.tail, SysTool.less):
+            # Follow the file in real-time.
+            command = (
+                f"tail -{max_lines} -f {quoted_filename} | "
+                f"bat --paging=never --color=always --style=plain --theme={BAT_THEME} -l log | "
+                "less -K -R +F"
+            )
+        else:
+            command = f"tail -f {quoted_filename} | less -R +F"
+        cprint("Following file: `%s`", command, text_wrap=Wrap.NONE)
+    else:
+        if sys_tool_check().has(SysTool.bat, SysTool.tail, SysTool.less):
+            command = (
+                f"tail -{max_lines} {quoted_filename} | "
+                f"bat --paging=never --color=always --style=plain --theme={BAT_THEME} -l log | "
+                "less -K -R +G"
+            )
+        else:
+            command = f"less +G {quoted_filename}"
+        cprint("Tailing file: `%s`", command, text_wrap=Wrap.NONE)
+
+    subprocess.run(command, shell=True, check=True)
+
+
+def view_file_console(filename: str | Path, use_pager: bool = True):
+    """
+    Displays a file in the console with pagination and syntax highlighting.
+    """
+    filename = str(filename)
+    quoted_filename = shlex.quote(filename)
+
+    # TODO: Visualize YAML frontmatter with different syntax/style than Markdown content.
+
+    is_text = file_format_info(filename).is_text
+    if is_text:
+        sys_tool_check().require(SysTool.less)
+        if sys_tool_check().has(SysTool.bat):
+            pager_str = "--pager=always --pager=less " if use_pager else ""
+            command = f"bat {pager_str}--color=always --style={BAT_STYLE} --theme={BAT_THEME} {quoted_filename}"
+        else:
+            sys_tool_check().require(SysTool.pygmentize)
+            command = f"pygmentize -g {quoted_filename}"
+            if use_pager:
+                command = f"{command} | less -R"
+    else:
+        sys_tool_check().require(SysTool.hexyl)
+        command = f"hexyl {quoted_filename}"
+        if use_pager:
+            command = f"{command} | less -R"
+
+    try:
+        subprocess.run(command, shell=True, check=True)
+    except subprocess.CalledProcessError as e:
+        cprint(f"Error displaying file: {e}", style=COLOR_ERROR, text_wrap=Wrap.NONE)
+
+
+def edit_files(*filenames: str | Path):
+    """
+    Edit a file using the user's preferred editor.
+    """
+    from kash.config.settings import global_settings
+
+    editor = os.getenv("EDITOR", global_settings().default_editor)
+    subprocess.run([editor] + list(filenames))
+
+
+def native_trash(*paths: str | Path):
+    from send2trash import send2trash
+
+    send2trash(list(Path(p) for p in paths))

kash/shell/utils/osc_utils.py

@@ -0,0 +1,95 @@
+import os
+from functools import cache
+
+from rich.style import Style
+from rich.text import Text
+
+
+@cache
+def terminal_supports_osc8() -> bool:
+    """
+    Attempt to detect if the terminal supports OSC 8 hyperlinks.
+    """
+    term_program = os.environ.get("TERM_PROGRAM", "")
+    term = os.environ.get("TERM", "")
+
+    if term_program in ["iTerm.app", "WezTerm", "Hyper"]:
+        return True
+    if "konsole" in term_program.lower():
+        return True
+    if "kitty" in term or "xterm" in term:
+        return True
+    if "vscode" in term_program.lower():
+        return True
+
+    return False
+
+
+# Constants for OSC control sequences
+OSC_START = "\x1b]"
+ST_CODE = "\x1b\\"  # String Terminator
+BEL_CODE = "\x07"  # Bell character
+
+OSC_HYPERLINK = "8"
+
+
+class OscStr(str):
+    """
+    Marker class for strings that contain OSC codes.
+    """
+
+    pass
+
+
+def osc_code(code: int | str, data: str) -> OscStr:
+    """
+    Return an extended OSC code.
+    """
+    return OscStr(f"{OSC_START}{code};{data}{ST_CODE}")
+
+
+def osc8_link_codes(uri: str, metadata_str: str = "") -> tuple[str, str]:
+    safe_uri = uri.replace(";", "%3B")  # Escape semicolons in the URL.
+    safe_metadata = metadata_str.replace(";", "%3B")
+    escape_start = f"{OSC_START}{OSC_HYPERLINK};{safe_metadata};{safe_uri}{ST_CODE}"
+    escape_end = f"{OSC_START}{OSC_HYPERLINK};;{ST_CODE}"
+    return escape_start, escape_end
+
+
+def osc8_link(uri: str, text: str, metadata_str: str = "") -> OscStr:
+    r"""
+    Return a string with the OSC 8 hyperlink escape sequence.
+
+    Format: ESC ] 8 ; params ; URI ST text ESC ] 8 ; ; ST
+
+    ST (String Terminator) is either ESC \ or BEL but the former is more common.
+
+    Spec: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+
+    :param uri: The URI or URL for the hyperlink.
+    :param text: The clickable text to display.
+    :param metadata_str: Optional metadata between the semicolons.
+    """
+    escape_start, escape_end = osc8_link_codes(uri, metadata_str)
+
+    return OscStr(f"{escape_start}{text}{escape_end}")
+
+
+def osc8_link_graceful(uri: str, text: str, id: str = "") -> OscStr | str:
+    """
+    Generate clickable text for terminal emulators supporting OSC 8 with a fallback
+    for non-supporting terminals to make the link visible.
+    """
+    if terminal_supports_osc8():
+        metadata_str = f"id={id}" if id else ""
+        return osc8_link(uri, text, metadata_str)
+    else:
+        # Fallback for non-supporting terminals.
+        return f"{text} ({uri})"
+
+
+def osc8_link_rich(uri: str, text: str, metadata_str: str = "", style: str | Style = "") -> Text:
+    """
+    Must use Text.from_ansi() for Rich to handle links correctly!
+    """
+    return Text.from_ansi(osc8_link(uri, text, metadata_str), style=style)

kash/shell/utils/shell_function_wrapper.py

@@ -0,0 +1,204 @@
+import types
+from collections.abc import Callable, Mapping
+from enum import Enum
+from functools import wraps
+from typing import Any, TypeVar, cast, get_args
+
+from kash.config.logger import get_logger
+from kash.errors import InvalidCommand
+from kash.exec.command_registry import CommandFunction
+from kash.help.help_printing import print_command_function_help
+from kash.utils.common.function_inspect import FuncParam, inspect_function_params
+from kash.utils.common.parse_shell_args import parse_shell_args
+
+log = get_logger(__name__)
+
+
+def _map_positional(
+    pos_args: list[str], pos_params: list[FuncParam], kw_params: list[FuncParam]
+) -> tuple[list[Any], int]:
+    """
+    Map parsed positional arguments to function parameters, ensuring the number of
+    arguments matches and converting types.
+    """
+    pos_values = []
+    i = 0
+    keywords_consumed = 0
+
+    for param in pos_params:
+        param_type = param.type or str
+        if param.is_varargs:
+            pos_values.extend([param_type(arg) for arg in pos_args[i:]])
+            return pos_values, 0  # All remaining args are consumed, so we can return early.
+        elif i < len(pos_args):
+            pos_values.append(param_type(pos_args[i]))
+            i += 1
+        else:
+            raise InvalidCommand(f"Missing positional argument: {param.name}")
+
+    # If there are remaining positional arguments, they will go toward keyword arguments.
+    for param in kw_params:
+        param_type = param.type or str
+        if not param.is_varargs and i < len(pos_args):
+            pos_values.append(param_type(pos_args[i]))
+            i += 1
+            keywords_consumed += 1
+
+    if i < len(pos_args):
+        raise InvalidCommand(
+            f"Too many arguments provided (expected {len(pos_params)}, got {len(pos_args)}): {pos_args}"
+        )
+
+    return pos_values, keywords_consumed
+
+
+def _map_keyword(kw_args: Mapping[str, str | bool], kw_params: list[FuncParam]) -> dict[str, Any]:
+    """
+    Map parsed keyword arguments to function parameters, converting types and handling var
+    keyword arguments.
+    """
+
+    kw_values = {param.name: param.default for param in kw_params if not param.is_varargs}
+    var_kw_values = {}
+    var_kw_param = None
+
+    # Find the var keyword argument (**kwargs), if any.
+    var_kw_param = next((param for param in kw_params if param.is_varargs), None)
+
+    # Map the keyword arguments to the function parameters.
+    for key, value in kw_args.items():
+        matching_param = next((param for param in kw_params if param.name == key), None)
+        if matching_param:
+            matching_param_type = matching_param.type or str
+
+            # Handle UnionType (str | None) specially
+            if hasattr(types, "UnionType") and isinstance(matching_param_type, types.UnionType):
+                args = get_args(matching_param_type)
+                non_none_args = [arg for arg in args if arg is not type(None)]
+                if len(non_none_args) == 1 and isinstance(non_none_args[0], type):
+                    matching_param_type = non_none_args[0]
+
+            if isinstance(value, bool) and not issubclass(matching_param_type, bool):
+                raise InvalidCommand(f"Option `--{key}` expects a value")
+            if not isinstance(value, bool) and issubclass(matching_param_type, bool):
+                raise InvalidCommand(f"Option `--{key}` is boolean and does not take a value")
+
+            try:
+                kw_values[key] = matching_param_type(value)  # Convert value to type.
+            except Exception as e:
+                valid_values = ""
+                if isinstance(matching_param.type, type) and issubclass(matching_param.type, Enum):
+                    valid_values = f" (valid values are: {', '.join('`' + v.name + '`' for v in matching_param.type)})"
+                raise InvalidCommand(
+                    f"Invalid value for option `{key}`: {value}{valid_values}"
+                ) from e
+        elif var_kw_param:
+            var_kw_values[key] = value
+        else:
+            raise InvalidCommand(f"Unknown option `--{key}`")
+
+    if var_kw_param:
+        kw_values.update(var_kw_values)
+
+    return kw_values
+
+
+R = TypeVar("R")
+
+
+def wrap_for_shell_args(func: Callable[..., R]) -> Callable[[list[str]], R | None]:
+    """
+    Wrap a function to accept a list of string shell-style arguments, parse them, and
+    call the original function.
+    """
+    from kash.commands.help import help_commands
+
+    params = inspect_function_params(func)
+    pos_params = [p for p in params if p.is_positional]
+    kw_params = [p for p in params if p not in pos_params]
+
+    @wraps(func)
+    def wrapped(args: list[str]) -> R | None:
+        shell_args = parse_shell_args(args)
+
+        if shell_args.show_help:
+            print_command_function_help(cast(CommandFunction, func), verbose=True)
+            return None
+        elif shell_args.options.get("show_source", False):
+            help_commands.source_code(func.__name__)
+            return None
+
+        pos_values, kw_consumed = _map_positional(shell_args.args, pos_params, kw_params)
+
+        # If some positional arguments were used as keyword arguments, we need to remove
+        # them from the kw_params so they don't get passed twice.
+        remaining_kw_params = kw_params[kw_consumed:]
+
+        kw_values = _map_keyword(shell_args.options, remaining_kw_params)
+
+        if args:
+            log.info(
+                "Mapping shell args to function params: %s -> %s -> %s(*%s, **%s)",
+                args,
+                shell_args,
+                func.__name__,
+                pos_values,
+                kw_values,
+            )
+
+        return func(*pos_values, **kw_values)
+
+    return wrapped
+
+
+## Tests
+
+
+def test_wrap_function():
+    def func1(
+        arg1: str, arg2: str, arg3: int, option_one: bool = False, option_two: str | None = None
+    ) -> list:
+        return [arg1, arg2, arg3, option_one, option_two]
+
+    def func2(*paths: str, summary: bool | None = False, iso_time: bool | None = False) -> list:
+        return [paths, summary, iso_time]
+
+    def func3(arg1: str, **keywords) -> list:
+        return [arg1, keywords]
+
+    def func4() -> list:
+        return []
+
+    wrapped_func1 = wrap_for_shell_args(func1)
+    wrapped_func2 = wrap_for_shell_args(func2)
+    wrapped_func3 = wrap_for_shell_args(func3)
+    wrapped_func4 = wrap_for_shell_args(func4)
+
+    print("\nwrapped:")
+    print(
+        wrapped_func1(["arg1_value", "arg2_value", "99", "--option_one", "--option_two=some_value"])
+    )
+    print(wrapped_func2(["--summary", "--iso_time", "path1", "path2", "path3"]))
+    print(wrapped_func3(["arg1_value", "--extra_param=some_value"]))
+
+    print(wrapped_func4([]))
+
+    assert wrapped_func1(
+        ["arg1_value", "arg2_value", "99", "--option_one", "--option_two=some_value"]
+    ) == [
+        "arg1_value",
+        "arg2_value",
+        99,
+        True,
+        "some_value",
+    ]
+    assert wrapped_func2(["--summary", "--iso_time", "path1", "path2", "path3"]) == [
+        ("path1", "path2", "path3"),
+        True,
+        True,
+    ]
+    assert wrapped_func3(["arg1_value", "--extra_param=some_value"]) == [
+        "arg1_value",
+        {"extra_param": "some_value"},
+    ]
+    assert wrapped_func4([]) == []