kash-shell 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

kash/shell/utils/native_utils.py

@@ -11,15 +11,15 @@ import webbrowser
 from enum import Enum
 from pathlib import Path
 
+from clideps.pkgs.pkg_check import pkg_check
+from clideps.pkgs.platform_checks import Platform, get_platform
+from clideps.terminal.terminal_images import terminal_show_image
 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.shell.clideps.pkg_deps import Pkg, pkg_check
-from kash.shell.clideps.platforms import PLATFORM, Platform
+from kash.config.text_styles import BAT_STYLE, BAT_STYLE_PLAIN, BAT_THEME, COLOR_ERROR
 from kash.shell.output.shell_output import cprint
-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.errors import FileNotFound, SetupError
@@ -49,11 +49,11 @@ def file_size_check(
 def native_open(filename: str | Path):
     filename = str(filename)
     log.message("Opening file: %s", filename)
-    if PLATFORM == Platform.Darwin:
+    if get_platform() == Platform.Darwin:
         subprocess.run(["open", filename])
-    elif PLATFORM == Platform.Linux:
+    elif get_platform() == Platform.Linux:
         subprocess.run(["xdg-open", filename])
-    elif PLATFORM == Platform.Windows:
+    elif get_platform() == Platform.Windows:
         subprocess.run(["start", shlex.quote(filename)], shell=True)
     else:
         raise NotImplementedError("Unsupported platform")
@@ -110,12 +110,14 @@ def _detect_view_mode(file_or_url: str) -> ViewMode:
 def view_file_native(
     file_or_url: str | Path,
     view_mode: ViewMode = ViewMode.auto,
+    plain: bool = False,
 ):
     """
     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.
+    display. The `--plain` flag will disable line numbers, grid, etc. in `bat`
+    and force `ViewMode.console`.
     """
     file_or_url = str(file_or_url)
     path = None
@@ -124,6 +126,9 @@ def view_file_native(
         if not path.exists():
             raise FileNotFound(fmt_loc(path))
 
+    if plain:
+        view_mode = ViewMode.console
+
     if view_mode == ViewMode.auto:
         view_mode = _detect_view_mode(file_or_url)
 
@@ -133,7 +138,7 @@ def view_file_native(
         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)
+        view_file_console(path, use_pager=min_lines > 40 or file_size > 20 * 1024, plain=plain)
     elif view_mode == ViewMode.terminal_image and path:
         try:
             terminal_show_image(path)
@@ -187,11 +192,11 @@ def tail_file(
     if follow:
         max_lines = follow_max_lines
 
-    pkg_check().require(Pkg.tail)
-    pkg_check().warn_if_missing(Pkg.bat)
+    pkg_check().require("tail")
+    pkg_check().warn_if_missing("bat")
 
     if follow:
-        if pkg_check().has(Pkg.bat):
+        if pkg_check().is_found("bat"):
             # Follow the file in real-time.
             command = (
                 f"tail -{max_lines} -f {all_paths_str} | "
@@ -202,8 +207,8 @@ def tail_file(
             command = f"tail -f {all_paths_str}"
         cprint("Following file: `%s`", command, text_wrap=Wrap.NONE)
     else:
-        pkg_check().require(Pkg.less)
-        if pkg_check().has(Pkg.bat, Pkg.less):
+        pkg_check().require("less")
+        if pkg_check().is_found("bat"):
             command = (
                 f"tail -{max_lines} {all_paths_str} | "
                 f"bat --paging=never --color=always --style=plain --theme={BAT_THEME} -l log | "
@@ -216,7 +221,7 @@ def tail_file(
     subprocess.run(command, shell=True, check=True)
 
 
-def view_file_console(filename: str | Path, use_pager: bool = True):
+def view_file_console(filename: str | Path, use_pager: bool = True, plain: bool = False):
     """
     Displays a file in the console with pagination and syntax highlighting.
     """
@@ -226,18 +231,19 @@ def view_file_console(filename: str | Path, use_pager: bool = True):
     # TODO: Visualize YAML frontmatter with different syntax/style than Markdown content.
 
     is_text = file_format_info(filename).is_text
+    bat_style = BAT_STYLE_PLAIN if plain else BAT_STYLE
     if is_text:
-        pkg_check().require(Pkg.less)
-        if pkg_check().has(Pkg.bat):
+        pkg_check().require("less")
+        if pkg_check().is_found("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}"
+            command = f"bat {pager_str}--color=always --style={bat_style} --theme={BAT_THEME} {quoted_filename}"
         else:
-            pkg_check().require(Pkg.pygmentize)
+            pkg_check().require("pygmentize")
             command = f"pygmentize -g {quoted_filename}"
             if use_pager:
                 command = f"{command} | less -R"
     else:
-        pkg_check().require(Pkg.hexyl)
+        pkg_check().require("hexyl")
         command = f"hexyl {quoted_filename}"
         if use_pager:
             command = f"{command} | less -R"

kash/shell/utils/shell_function_wrapper.py

@@ -27,7 +27,7 @@ def _map_positional(
     keywords_consumed = 0
 
     for param in pos_params:
-        param_type = param.type or str
+        param_type = param.effective_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.
@@ -39,7 +39,7 @@ def _map_positional(
 
     # If there are remaining positional arguments, they will go toward keyword arguments.
     for param in kw_params:
-        param_type = param.type or str
+        param_type = param.effective_type or str
         if not param.is_varargs and i < len(pos_args):
             pos_values.append(param_type(pos_args[i]))
             i += 1
@@ -70,30 +70,30 @@ def _map_keyword(kw_args: Mapping[str, str | bool], kw_params: list[FuncParam])
     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
+            param_type = matching_param.effective_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)
+            if hasattr(types, "UnionType") and isinstance(param_type, types.UnionType):
+                args = get_args(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]
+                    param_type = non_none_args[0]
 
-            if isinstance(value, bool) and not issubclass(matching_param_type, bool):
+            if isinstance(value, bool) and not issubclass(param_type, bool):
                 raise InvalidCommand(f"Option `--{key}` expects a value")
-            if not isinstance(value, bool) and issubclass(matching_param_type, bool):
+            if not isinstance(value, bool) and issubclass(param_type, bool):
                 raise InvalidCommand(f"Option `--{key}` is boolean and does not take a value")
 
             try:
-                kw_values[key] = instantiate_as_type(
-                    value, matching_param_type, accept_enum_names=True
-                )
+                kw_values[key] = instantiate_as_type(value, param_type, accept_enum_names=True)
             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)})"
+                if isinstance(param_type, type) and issubclass(param_type, Enum):
+                    valid_values = (
+                        f" (valid values are: {', '.join('`' + v.name + '`' for v in param_type)})"
+                    )
                 raise InvalidCommand(
-                    f"Invalid value for parameter `{key}` of type {matching_param.type}: {value!r}{valid_values}"
+                    f"Invalid value for parameter `{key}` of type {param_type}: {value!r}{valid_values}"
                 ) from e
         elif var_kw_param:
             var_kw_values[key] = value
@@ -117,7 +117,7 @@ def wrap_for_shell_args(func: Callable[..., R]) -> Callable[[list[str]], R | Non
     from kash.commands.help import help_commands
 
     params = inspect_function_params(func)
-    pos_params = [p for p in params if p.is_positional]
+    pos_params = [p for p in params if p.is_pure_positional]
     kw_params = [p for p in params if p not in pos_params]
 
     @wraps(func)

kash/text_handling/custom_sliding_transforms.py

@@ -1,10 +1,17 @@
 from collections.abc import Callable
 from math import ceil
 
-from chopdiff.docs import DiffFilter, Paragraph, TextDoc, TextUnit, diff_docs, join_wordtoks
+from chopdiff.docs import (
+    DIFF_FILTER_NONE,
+    DiffFilter,
+    Paragraph,
+    TextDoc,
+    TextUnit,
+    diff_docs,
+    join_wordtoks,
+)
 from chopdiff.transforms import (
     WindowSettings,
-    accept_all,
     remove_window_br,
     sliding_para_window,
     sliding_window_transform,
@@ -31,7 +38,7 @@ def filtered_transform(
     doc: TextDoc,
     transform_func: TextDocTransform,
     windowing: WindowSettings | None,
-    diff_filter: DiffFilter = accept_all,
+    diff_filter: DiffFilter | None = None,
 ) -> TextDoc:
     """
     Apply a transform with sliding window across the input doc, enforcing the changes it's
@@ -39,7 +46,7 @@ def filtered_transform(
 
     If windowing is None, apply the transform to the entire document at once.
     """
-    has_filter = diff_filter != accept_all
+    has_filter = bool(diff_filter and diff_filter != DIFF_FILTER_NONE)
 
     if not windowing or not windowing.size:
         transformed_doc = transform_func(doc)
@@ -52,6 +59,7 @@ def filtered_transform(
             transformed_doc = transform_func(input_doc)
 
             if has_filter:
+                assert diff_filter
                 # Check the transform did what it should have.
                 diff = diff_docs(input_doc, transformed_doc)
                 accepted_diff, rejected_diff = diff.filter(diff_filter)

kash/text_handling/doc_normalization.py

@@ -21,7 +21,11 @@ def normalize_formatting_ansi(text: str, format: Format | None, width=DEFAULT_WR
             text, width=width, word_splitter=simple_word_splitter, len_fn=ansi_cell_len
         )
     elif format == Format.markdown or format == Format.md_html:
-        return fill_markdown(text, line_wrapper=line_wrap_by_sentence(len_fn=ansi_cell_len))
+        return fill_markdown(
+            text,
+            line_wrapper=line_wrap_by_sentence(len_fn=ansi_cell_len, is_markdown=True),
+            cleanups=True,  # Safe cleanups like unbolding section headers.
+        )
     elif format == Format.html:
         # We don't currently auto-format HTML as we sometimes use HTML with specifically chosen line breaks.
         return text
@@ -52,7 +56,7 @@ def normalize_text_file(
 
 
 def test_osc8_link():
-    from kash.shell.utils.osc_utils import osc8_link
+    from clideps.terminal.osc_utils import osc8_link
 
     link = osc8_link("https://example.com/" + "x" * 50, "Example")
     assert ansi_cell_len(link) == 7

kash/text_handling/markdown_render.py

@@ -0,0 +1,118 @@
+from textwrap import dedent
+
+import marko
+import regex
+from marko.block import HTMLBlock
+from marko.ext.gfm import GFM
+from marko.helpers import MarkoExtension
+
+
+# When we use divs in Markdown we usually want them to be standalone paragraphs,
+# so it doesn't break other wrapping with flowmark etc. This handles that.
+class CustomHTMLBlockMixin:
+    div_pattern = regex.compile(r"^\s*<div\b", regex.IGNORECASE)
+
+    def render_html_block(self, element: HTMLBlock) -> str:
+        # Apply GFM filtering first via the next renderer in the MRO.
+        filtered_body = super().render_html_block(element)  # pyright: ignore
+
+        # Check if the original block was a div.
+        if self.div_pattern.match(element.body.strip()):
+            # If it was a div, wrap the *filtered* result in newlines.
+            return f"\n{filtered_body.strip()}\n"
+        else:
+            # Otherwise, return the GFM-filtered body directly.
+            return filtered_body
+
+
+# GFM first, adding our custom override as an extension to handle divs our way.
+# Extensions later in this list are earlier in MRO.
+MARKO_GFM = marko.Markdown(
+    extensions=["footnote", GFM, MarkoExtension(renderer_mixins=[CustomHTMLBlockMixin])]
+)
+
+
+FOOTNOTE_UP_ARROW = "&nbsp;↑&nbsp;"
+
+
+def html_postprocess(html: str) -> str:
+    """
+    Final tweaks to the HTML.
+    """
+    # TODO: Improve rendering of footnote defs to put the up arrow next to the number instead?
+    html = html.replace(
+        """class="footnote">&#8617;</a>""", f"""class="footnote">{FOOTNOTE_UP_ARROW}</a>"""
+    )
+    return html
+
+
+def markdown_to_html(markdown: str, converter: marko.Markdown = MARKO_GFM) -> str:
+    """
+    Convert Markdown to HTML.
+
+    Wraps div blocks with newlines for better Markdown compatibility.
+
+    Output passes through raw HTML! Note per GFM, unsafe script tags etc
+    are [allowed in some cases](https://github.github.com/gfm/#example-140) so
+    additional sanitization is needed if input isn't trusted.
+    """
+    html = converter.convert(markdown)
+    return html_postprocess(html)
+    return html
+
+
+## Tests
+
+
+def test_markdown_to_html():
+    markdown = dedent(
+        """
+        # Heading
+
+        This is a paragraph and a [link](https://example.com).
+
+        - Item 1
+        - Item 2
+
+        ## Subheading
+
+        This is a paragraph with a <span>span</span> tag.
+        This is a paragraph with a <div>div</div> tag.
+        This is a paragraph with an <a href='https://example.com'>example link</a>.
+
+        <div class="div1">This is a div.</div>
+
+        <div class="div2">This is a second div.
+        <iframe src="https://example.com">Inline iframe, note this is sanitized</iframe>
+        </div>
+
+        <!-- Script tag in a block, note this isn't sanitized -->
+        <script>console.log("Javascript block!");</script>
+        """
+    )
+    print(markdown_to_html(markdown))
+
+    expected_html = dedent(
+        """
+        <h1>Heading</h1>
+        <p>This is a paragraph and a <a href="https://example.com">link</a>.</p>
+        <ul>
+        <li>Item 1</li>
+        <li>Item 2</li>
+        </ul>
+        <h2>Subheading</h2>
+        <p>This is a paragraph with a <span>span</span> tag.
+        This is a paragraph with a <div>div</div> tag.
+        This is a paragraph with an <a href='https://example.com'>example link</a>.</p>
+
+        <div class="div1">This is a div.</div>
+
+        <div class="div2">This is a second div.
+        &lt;iframe src="https://example.com">Inline iframe, note this is sanitized</iframe>
+        </div>
+        <!-- Script tag in a block, note this isn't sanitized -->
+        <script>console.log("Javascript block!");</script>
+        """
+    )
+
+    assert markdown_to_html(markdown).strip() == expected_html.strip()

kash/text_handling/markdown_utils.py

@@ -0,0 +1,226 @@
+import re
+from typing import Any
+
+import marko
+import regex
+from marko.block import Heading, ListItem
+from marko.inline import Link
+
+from kash.config.logger import get_logger
+from kash.utils.common.url import Url
+
+log = get_logger(__name__)
+
+# Characters that commonly need escaping in Markdown inline text.
+MARKDOWN_ESCAPE_CHARS = r"([\\`*_{}\[\]()#+.!-])"
+MARKDOWN_ESCAPE_RE = re.compile(MARKDOWN_ESCAPE_CHARS)
+
+
+def escape_markdown(text: str) -> str:
+    """
+    Escape characters with special meaning in Markdown.
+    """
+    return MARKDOWN_ESCAPE_RE.sub(r"\\\1", text)
+
+
+def as_bullet_points(values: list[Any]) -> str:
+    """
+    Convert a list of values to a Markdown bullet-point list. If a value is a string,
+    it is treated like Markdown. If it's something else it's converted to a string
+    and also escaped for Markdown.
+    """
+    points: list[str] = []
+    for value in values:
+        value = value.replace("\n", " ").strip()
+        if isinstance(value, str):
+            points.append(value)
+        else:
+            points.append(escape_markdown(str(value)))
+
+    return "\n\n".join(f"- {point}" for point in points)
+
+
+def markdown_link(text: str, url: str | Url) -> str:
+    """
+    Create a Markdown link.
+    """
+    text = text.replace("[", "\\[").replace("]", "\\]")
+    return f"[{text}]({url})"
+
+
+def is_markdown_header(markdown: str) -> bool:
+    """
+    Is the start of this content a Markdown header?
+    """
+    return regex.match(r"^#+ ", markdown) is not None
+
+
+def _tree_links(element, include_internal=False):
+    links = []
+
+    def _find_links(element):
+        match element:
+            case Link():
+                if include_internal or not element.dest.startswith("#"):
+                    links.append(element.dest)
+            case _:
+                if hasattr(element, "children"):
+                    for child in element.children:
+                        _find_links(child)
+
+    _find_links(element)
+    return links
+
+
+def extract_links(file_path: str, include_internal=False) -> list[str]:
+    """
+    Extract all links from a Markdown file. Future: Include textual and section context.
+    """
+
+    with open(file_path) as file:
+        content = file.read()
+        document = marko.parse(content)
+        return _tree_links(document, include_internal)
+
+
+def extract_first_header(content: str) -> str | None:
+    """
+    Extract the first header from markdown content if present.
+    Also drops any formatting, so the result can be used as a document title.
+    """
+    document = marko.parse(content)
+
+    if document.children and isinstance(document.children[0], Heading):
+        return _extract_text(document.children[0]).strip()
+
+    return None
+
+
+def _extract_text(element: Any) -> str:
+    if isinstance(element, str):
+        return element
+    elif hasattr(element, "children"):
+        return "".join(_extract_text(child) for child in element.children)
+    else:
+        return ""
+
+
+def _tree_bullet_points(element: marko.block.Document) -> list[str]:
+    bullet_points: list[str] = []
+
+    def _find_bullet_points(element):
+        if isinstance(element, ListItem):
+            bullet_points.append(_extract_text(element).strip())
+        elif hasattr(element, "children"):
+            for child in element.children:
+                _find_bullet_points(child)
+
+    _find_bullet_points(element)
+    return bullet_points
+
+
+def extract_bullet_points(content: str) -> list[str]:
+    """
+    Extract list item values from a Markdown file.
+    """
+
+    document = marko.parse(content)
+    return _tree_bullet_points(document)
+
+
+def _type_from_heading(heading: Heading) -> str:
+    if heading.level in [1, 2, 3, 4, 5, 6]:
+        return f"h{heading.level}"
+    else:
+        raise ValueError(f"Unsupported heading: {heading}: level {heading.level}")
+
+
+def _last_unescaped_bracket(text: str, index: int) -> str | None:
+    escaped = False
+    for i in range(index - 1, -1, -1):
+        ch = text[i]
+        if ch == "\\":
+            escaped = not escaped  # Toggle escaping chain
+            continue
+        if ch in "[]":
+            if not escaped:
+                return ch
+        # Reset escape status after any non‑backslash char
+        escaped = False
+    return None
+
+
+def find_markdown_text(
+    pattern: re.Pattern[str], text: str, *, start_pos: int = 0
+) -> re.Match[str] | None:
+    """
+    Return first regex `pattern` match in `text` not inside an existing link.
+
+    A match is considered inside a link when the most recent unescaped square
+    bracket preceding the match start is an opening bracket "[".
+    """
+
+    pos = start_pos
+    while True:
+        match = pattern.search(text, pos)
+        if match is None:
+            return None
+
+        last_bracket = _last_unescaped_bracket(text, match.start())
+        if last_bracket != "[":
+            return match
+
+        # Skip this match and continue searching
+        pos = match.end()
+
+
+## Tests
+
+
+def test_escape_markdown() -> None:
+    assert escape_markdown("") == ""
+    assert escape_markdown("Hello world") == "Hello world"
+    assert escape_markdown("`code`") == "\\`code\\`"
+    assert escape_markdown("*italic*") == "\\*italic\\*"
+    assert escape_markdown("_bold_") == "\\_bold\\_"
+    assert escape_markdown("{braces}") == "\\{braces\\}"
+    assert escape_markdown("# header") == "\\# header"
+    assert escape_markdown("1. item") == "1\\. item"
+    assert escape_markdown("line+break") == "line\\+break"
+    assert escape_markdown("dash-") == "dash\\-"
+    assert escape_markdown("!bang") == "\\!bang"
+    assert escape_markdown("backslash\\") == "backslash\\\\"
+    assert escape_markdown("Multiple *special* chars [here](#anchor).") == (
+        "Multiple \\*special\\* chars \\[here\\]\\(\\#anchor\\)\\."
+    )
+
+
+def test_extract_first_header() -> None:
+    assert extract_first_header("# Header 1") == "Header 1"
+    assert extract_first_header("Not a header\n# Header later") is None
+    assert extract_first_header("") is None
+    assert (
+        extract_first_header("## *Formatted* _Header_ [link](#anchor)") == "Formatted Header link"
+    )
+
+
+def test_find_markdown_text() -> None:  # pragma: no cover
+    # Match is returned when the term is not inside a link.
+    text = "Foo bar baz"
+    pattern = re.compile("Foo Bar", re.IGNORECASE)
+    match = find_markdown_text(pattern, text)
+    assert match is not None and match.group(0) == "Foo bar"
+
+    # Skips occurrence inside link and returns the first one outside.
+    text = "[Foo](http://example.com) something Foo"
+    pattern = re.compile("Foo", re.IGNORECASE)
+    match = find_markdown_text(pattern, text)
+    assert match is not None
+    assert match.start() > text.index(") ")
+    assert text[match.start() : match.end()] == "Foo"
+
+    # Returns None when the only occurrences are inside links.
+    text = "prefix [bar](http://example.com) suffix"
+    pattern = re.compile("bar", re.IGNORECASE)
+    match = find_markdown_text(pattern, text)
+    assert match is None