kash-shell 0.3.28__py3-none-any.whl → 0.3.33__py3-none-any.whl

kash/actions/core/chat.py

@@ -28,6 +28,7 @@ log = get_logger(__name__)
 @kash_action(
     expected_args=ONE_OR_NO_ARGS,
     precondition=is_chat,
+    output_format=Format.yaml,
     uses_selection=False,
     interactive_input=True,
     cacheable=False,

kash/actions/core/markdownify_html.py

@@ -5,7 +5,6 @@ from kash.exec import kash_action
 from kash.exec.preconditions import has_html_body, is_url_resource
 from kash.exec.runtime_settings import current_runtime_settings
 from kash.model import Format, Item
-from kash.model.items_model import ItemType
 from kash.utils.text_handling.markdown_utils import first_heading
 from kash.utils.text_handling.markdownify_utils import markdownify_custom
 from kash.web_content.file_cache_utils import get_url_html
@@ -14,7 +13,9 @@ from kash.web_content.web_extract_readabilipy import extract_text_readabilipy
 log = get_logger(__name__)
 
 
-@kash_action(precondition=is_url_resource | has_html_body, mcp_tool=True)
+@kash_action(
+    precondition=is_url_resource | has_html_body, output_format=Format.markdown, mcp_tool=True
+)
 def markdownify_html(item: Item) -> Item:
     """
     Converts raw HTML or the URL of an HTML page to Markdown, fetching with the content
@@ -36,7 +37,5 @@ def markdownify_html(item: Item) -> Item:
         # Insert a h1 at the top of the document
         markdown_content = f"# {title}\n\n{markdown_content}"
 
-    output_item = item.derived_copy(
-        type=ItemType.doc, format=Format.markdown, body=markdown_content
-    )
+    output_item = item.derived_copy(format=Format.markdown, body=markdown_content)
     return output_item

kash/actions/core/minify_html.py

@@ -14,13 +14,12 @@ from kash.workspaces.workspaces import current_ws
 )
 def minify_html(item: Item) -> Item:
     """
-    Minify an HTML item's content using [html-minifier-terser](https://github.com/terser/html-minifier-terser).
-
+    Minify an HTML item's content using [tminify](https://github.com/jlevy/tminify).
     Also supports Tailwind CSS v4 compilation and inlining, if any Tailwind
     CSS v4 CDN script tags are found.
 
-    The terser minification seems a bit slower but more robust than
-    [minify-html](https://github.com/wilsonzlin/minify-html).
+    Tminify uses [html-minifier-terser](https://github.com/terser/html-minifier-terser).
+    This is a bit slower but more robust than [minify-html](https://github.com/wilsonzlin/minify-html).
     """
     from tminify.main import tminify
 
@@ -31,7 +30,7 @@ def minify_html(item: Item) -> Item:
     input_path = ws.base_dir / item.store_path
 
     output_item = item.derived_copy(format=Format.html, body=None)
-    output_path = ws.target_path_for(output_item)
+    output_path = ws.assign_store_path(output_item)
 
     tminify(input_path, output_path)
 

kash/actions/core/readability.py

@@ -9,10 +9,7 @@ from kash.web_content.web_extract_readabilipy import extract_text_readabilipy
 log = get_logger(__name__)
 
 
-@kash_action(
-    precondition=is_url_resource | has_html_body,
-    mcp_tool=True,
-)
+@kash_action(precondition=is_url_resource | has_html_body, output_format=Format.html)
 def readability(item: Item) -> Item:
     """
     Extracts clean HTML from a raw HTML item.

kash/actions/core/render_as_html.py

@@ -1,17 +1,21 @@
 from kash.actions.core.tabbed_webpage_config import tabbed_webpage_config
 from kash.actions.core.tabbed_webpage_generate import tabbed_webpage_generate
+from kash.config.logger import get_logger
 from kash.exec import kash_action
 from kash.exec.preconditions import has_fullpage_html_body, has_html_body, has_simple_text_body
 from kash.exec_model.args_model import ONE_OR_MORE_ARGS
 from kash.model import ActionInput, ActionResult, Param
 from kash.model.items_model import ItemType
 from kash.utils.file_utils.file_formats_model import Format
-from kash.web_gen.simple_webpage import simple_webpage_render
+from kash.web_gen.webpage_render import render_item_as_html
+
+log = get_logger(__name__)
 
 
 @kash_action(
     expected_args=ONE_OR_MORE_ARGS,
     precondition=(has_html_body | has_simple_text_body) & ~has_fullpage_html_body,
+    output_format=Format.html,
     params=(Param("no_title", "Don't add a title to the page body.", type=bool),),
 )
 def render_as_html(input: ActionInput, no_title: bool = False) -> ActionResult:
@@ -27,12 +31,11 @@ def render_as_html(input: ActionInput, no_title: bool = False) -> ActionResult:
     """
     if len(input.items) == 1:
         input_item = input.items[0]
-        html_body = simple_webpage_render(
-            input_item, add_title_h1=not no_title, show_theme_toggle=True
-        )
-        result_item = input_item.derived_copy(
-            type=ItemType.export, format=Format.html, body=html_body
-        )
+
+        result_item = input_item.derived_copy(type=ItemType.export, format=Format.html)
+
+        result_item = render_item_as_html(input_item, result_item, add_title_h1=not no_title)
+
         return ActionResult([result_item])
     else:
         config_result = tabbed_webpage_config(input)

kash/actions/core/save_sidematter_meta.py

@@ -0,0 +1,47 @@
+from prettyfmt import fmt_lines
+from sidematter_format import Sidematter
+
+from kash.config.logger import get_logger
+from kash.exec import kash_action
+from kash.exec_model.args_model import ONE_OR_MORE_ARGS
+from kash.model.actions_model import ActionInput, ActionResult
+from kash.workspaces.workspaces import current_ws
+
+log = get_logger(__name__)
+
+
+@kash_action(expected_args=ONE_OR_MORE_ARGS)
+def save_sidematter_meta(input: ActionInput) -> ActionResult:
+    """
+    Write the item's metadata as a [sidematter format](https://github.com/jlevy/sidematter-format)
+    as `.meta.yml` and `.meta.json` files.
+
+    If additional data items are provided, their data is merged into the primary item's metadata.
+    This is useful for link data etc.
+    """
+    items = input.items
+    assert items
+
+    primary = items[0]
+    assert primary.store_path
+
+    ws = current_ws()
+    sm = Sidematter(ws.base_dir / primary.store_path)
+
+    metadata_dict = primary.metadata()
+
+    for item in items[1:]:
+        assert item.store_path
+        metadata_dict = metadata_dict | item.read_as_data()
+
+    # Write both JSON and YAML sidematter metadata
+    sm.write_meta(metadata_dict, formats="all", make_parents=True)
+
+    log.message(
+        "Wrote sidematter metadata:\n%s",
+        fmt_lines(
+            [sm.meta_json_path.relative_to(ws.base_dir), sm.meta_yaml_path.relative_to(ws.base_dir)]
+        ),
+    )
+
+    return ActionResult(items=[primary])

kash/actions/core/show_webpage.py

@@ -6,11 +6,13 @@ from kash.exec_model.args_model import ONE_OR_MORE_ARGS
 from kash.exec_model.commands_model import Command
 from kash.exec_model.shell_model import ShellResult
 from kash.model import ActionInput, ActionResult
+from kash.utils.file_utils.file_formats_model import Format
 
 
 @kash_action(
     expected_args=ONE_OR_MORE_ARGS,
     precondition=(has_html_body | has_simple_text_body) & ~has_fullpage_html_body,
+    output_format=Format.html,
 )
 def show_webpage(input: ActionInput) -> ActionResult:
     """

kash/actions/core/zip_sidematter.py

@@ -0,0 +1,47 @@
+import zipfile
+
+from sidematter_format import Sidematter
+
+from kash.config.logger import get_logger
+from kash.exec import kash_action
+from kash.model.items_model import Item, ItemType
+from kash.utils.file_utils.file_formats_model import Format
+from kash.workspaces.workspaces import current_ws
+
+log = get_logger(__name__)
+
+
+@kash_action()
+def zip_sidematter(item: Item) -> Item:
+    """
+    Zip all contents of the item, its sidematter metadata and items.
+    """
+    assert item.store_path
+    ws = current_ws()
+    sm = Sidematter(ws.base_dir / item.store_path)
+
+    base_dir = sm.primary.parent
+
+    # Collect all files to include; store paths relative to the primary's directory
+    files_to_zip: list[tuple] = []
+
+    files_to_zip.append((sm.primary, sm.primary.relative_to(base_dir)))
+    if sm.meta_json_path.exists():
+        files_to_zip.append((sm.meta_json_path, sm.meta_json_path.relative_to(base_dir)))
+    if sm.meta_yaml_path.exists():
+        files_to_zip.append((sm.meta_yaml_path, sm.meta_yaml_path.relative_to(base_dir)))
+    if sm.assets_dir.exists():
+        for p in sm.assets_dir.rglob("*"):
+            if p.is_file():
+                files_to_zip.append((p, p.relative_to(base_dir)))
+
+    output_item = item.derived_copy(type=ItemType.export, format=Format.zip)
+    target = ws.assign_store_path(output_item)
+
+    with zipfile.ZipFile(
+        target, mode="w", compression=zipfile.ZIP_DEFLATED, compresslevel=9
+    ) as zipf:
+        for path, arcname in files_to_zip:
+            zipf.write(path, arcname)
+
+    return output_item

kash/commands/base/basic_file_commands.py

@@ -33,7 +33,8 @@ def clipboard_copy(path: str | None = None, raw: bool = False) -> None:
     Copy the contents of a file (or the first file in the selection) to the OS-native
     clipboard. Similar to `pbcopy` on macOS.
 
-    :param raw: Copy the full exact contents of the file. Otherwise frontmatter is omitted.
+    Args:
+        raw: Copy the full exact contents of the file. Otherwise frontmatter is omitted.
     """
     # TODO: Get this to work for images!
     import pyperclip
@@ -95,7 +96,8 @@ def edit(path: str | None = None, all: bool = False) -> None:
     """
     Edit the contents of a file using the user's default editor (or defaulting to nano).
 
-    :param all: Normally edits only the first file given. This passes all files to the editor.
+    Args:
+        all: Normally edits only the first file given. This passes all files to the editor.
     """
     input_paths = assemble_path_args(path)
     if not all:
@@ -111,8 +113,9 @@ def file_info(*paths: str, size_summary: bool = False, format: bool = False) ->
     structure of the items at the given paths (for text documents) and the detected
     mime type.
 
-    :param size_summary: Only show size summary (words, sentences, paragraphs for a text document).
-    :param format: Only show detected file format.
+    Args:
+        size_summary: Only show size summary (words, sentences, paragraphs for a text document).
+        format: Only show detected file format.
     """
     if not size_summary and not format:
         size_summary = format = True

kash/commands/base/diff_commands.py

@@ -57,8 +57,9 @@ def diff_items(*paths: str, force: bool = False) -> ShellResult:
     as items themselves, so this works on items. Items are imported as usual into the
     global workspace if they are not already in the store.
 
-    :param stat: Only show the diffstat summary.
-    :param force: If true, will run the diff even if the items are of different formats.
+    Args:
+        stat: Only show the diffstat summary.
+        force: If true, will run the diff even if the items are of different formats.
     """
     ws = current_ws()
     if len(paths) == 2:
@@ -90,8 +91,9 @@ def diff_files(*paths: str, diffstat: bool = False, save: bool = False) -> Shell
     Show the unified diff between the given files. This works on any files, not
     just items, so helpful for quick analysis without importing the files.
 
-    :param diffstat: Only show the diffstat summary.
-    :param save: Save the diff as an item in the store.
+    Args:
+        diffstat: Only show the diffstat summary.
+        save: Save the diff as an item in the store.
     """
     if len(paths) == 2:
         [path1, path2] = paths

kash/commands/base/files_command.py

@@ -111,36 +111,37 @@ def files(
     with limited depth and breadth, and more control over recursion, sorting,
     and grouping.
 
-    :param overview: Recurse a couple levels and show files, but not too many.
-        Same as `--groupby=parent --depth=2 --max_per_group=100 --omit_dirs`
-        except also scales down `max_per_group` to 25 or 50 if there are many files.
-    :param recent: Only shows the most recently modified files in each directory.
-        Same as `--sort=modified --reverse --groupby=parent --max_per_group=100`
-        except also scales down `max_per_group` to 25 or 50 if there are many files.
-    :param recursive: List all files recursively. Same as `--depth=-1`.
-    :param flat: Show files in a flat list, rather than grouped by parent directory.
-        Same as `--groupby=flat`.
-    :param omit_dirs: Normally directories are included. This option omits them,
-        which is useful when recursing into subdirectories.
-    :param depth: Maximum depth to recurse into directories. -1 means no limit.
-    :param max_files: Maximum number of files to yield per input path.
-        -1 means no limit.
-    :param max_per_subdir: Maximum number of files to yield per subdirectory
-        (not including the top level). -1 means no limit.
-    :param max_per_group: Limit the first number of items displayed per group
-        (if groupby is used) or in total. 0 means show all.
-    :param no_max: Disable limits on depth and number of files. Same as
-        `--depth=-1 --max_files=-1 --max_per_subdir=-1 --max_per_group=-1`.
-    :param no_ignore: Disable ignoring hidden files.
-    :param all: Same as `--no_ignore --no_max`. Does not change `--depth`.
-    :param save: Save the listing as a CSV file item.
-    :param sort: Sort by `filename`, `size`, `accessed`, `created`, or `modified`.
-    :param reverse: Reverse the sorting order.
-    :param since: Filter files modified since a given time (e.g., '1 day', '2 hours').
-    :param groupby: Group results. Can be `flat` (no grouping, and by default implies
-        recursive), `parent`, or `suffix`. Defaults to 'parent'.
-    :param iso_time: Show time in ISO format (default is human-readable age).
-    :param pager: Use the pager when displaying the output.
+    Args:
+        overview: Recurse a couple levels and show files, but not too many.
+            Same as `--groupby=parent --depth=2 --max_per_group=100 --omit_dirs`
+            except also scales down `max_per_group` to 25 or 50 if there are many files.
+        recent: Only shows the most recently modified files in each directory.
+            Same as `--sort=modified --reverse --groupby=parent --max_per_group=100`
+            except also scales down `max_per_group` to 25 or 50 if there are many files.
+        recursive: List all files recursively. Same as `--depth=-1`.
+        flat: Show files in a flat list, rather than grouped by parent directory.
+            Same as `--groupby=flat`.
+        omit_dirs: Normally directories are included. This option omits them,
+            which is useful when recursing into subdirectories.
+        depth: Maximum depth to recurse into directories. -1 means no limit.
+        max_files: Maximum number of files to yield per input path.
+            -1 means no limit.
+        max_per_subdir: Maximum number of files to yield per subdirectory
+            (not including the top level). -1 means no limit.
+        max_per_group: Limit the first number of items displayed per group
+            (if groupby is used) or in total. 0 means show all.
+        no_max: Disable limits on depth and number of files. Same as
+            `--depth=-1 --max_files=-1 --max_per_subdir=-1 --max_per_group=-1`.
+        no_ignore: Disable ignoring hidden files.
+        all: Same as `--no_ignore --no_max`. Does not change `--depth`.
+        save: Save the listing as a CSV file item.
+        sort: Sort by `filename`, `size`, `accessed`, `created`, or `modified`.
+        reverse: Reverse the sorting order.
+        since: Filter files modified since a given time (e.g., '1 day', '2 hours').
+        groupby: Group results. Can be `flat` (no grouping, and by default implies
+            recursive), `parent`, or `suffix`. Defaults to 'parent'.
+        iso_time: Show time in ISO format (default is human-readable age).
+        pager: Use the pager when displaying the output.
     """
     if global_settings().use_nerd_icons:
         from kash.shell.file_icons.nerd_icons import icon_for_file

kash/commands/base/general_commands.py

@@ -160,8 +160,9 @@ def check_system_tools(warn_only: bool = False, brief: bool = False) -> None:
     """
     Check that all tools are installed.
 
-    :param warn_only: Only warn if tools are missing.
-    :param brief: Print summary as a single line.
+    Args:
+        warn_only: Only warn if tools are missing.
+        brief: Print summary as a single line.
     """
     if warn_only:
         pkg_check().warn_if_missing()

kash/commands/base/logs_commands.py

@@ -23,7 +23,8 @@ def logs(follow: bool = False) -> None:
     """
     Page through the logs for the current workspace.
 
-    :param follow: Follow the file as it grows.
+    Args:
+        follow: Follow the file as it grows.
     """
     tail_file(get_log_settings().log_file_path, follow=follow)
 
@@ -51,9 +52,10 @@ def log_level(level: str | None = None, console: bool = False, file: bool = Fals
     """
     Set or show the log level. Applies to both console and file log levels unless specified.
 
-    :param level: The log level to set. If not specified, will show current level.
-    :param console: Set console log level only.
-    :param file: Set file log level only.
+    Args:
+        level: The log level to set. If not specified, will show current level.
+        console: Set console log level only.
+        file: Set file log level only.
     """
     if not console and not file:
         console = True

kash/commands/base/reformat_command.py

@@ -22,8 +22,9 @@ def reformat(*paths: str, inplace: bool = False) -> ShellResult:
 
     TODO: Also handle JSON and YAML.
 
-    :param inplace: Overwrite the original file. Otherwise save to a new
-    file with `_formatted` appended to the original name.
+    Args:
+        inplace: Overwrite the original file. Otherwise save to a new
+            file with `_formatted` appended to the original name.
     """
     resolved_paths = assemble_path_args(*paths)
     final_paths = []

kash/commands/base/search_command.py

@@ -30,9 +30,10 @@ def search(
 
     search "youtube.com" resources/ --sort=modified
 
-    :param sort: How to sort results. Can be `path` or `modified` or `created` (as with `rg`).
-    :param ignore_case: Ignore case when searching.
-    :param verbose: Also print the ripgrep command line.
+    Args:
+        sort: How to sort results. Can be `path` or `modified` or `created` (as with `rg`).
+        ignore_case: Ignore case when searching.
+        verbose: Also print the ripgrep command line.
     """
     pkg_check().require("ripgrep")
     from ripgrepy import RipGrepNotFound, Ripgrepy

kash/commands/base/show_command.py

@@ -30,12 +30,13 @@ def show(
     Will use `bat` if available to show files in the console, including syntax
     highlighting and git diffs.
 
-    :param console: Force display to console (not browser or native apps).
-    :param native: Force display with a native app (depending on your system configuration).
-    :param thumbnail: If there is a thumbnail image, show it too.
-    :param browser: Force display with your default web browser.
-    :param plain: Use plain view in the console (this is `bat`'s `plain` style).
-    :param noselect: Disable default behavior where `show` also will `select` the file.
+    Args:
+        console: Force display to console (not browser or native apps).
+        native: Force display with a native app (depending on your system configuration).
+        thumbnail: If there is a thumbnail image, show it too.
+        browser: Force display with your default web browser.
+        plain: Use plain view in the console (this is `bat`'s `plain` style).
+        noselect: Disable default behavior where `show` also will `select` the file.
     """
     view_mode = (
         ViewMode.console
@@ -69,7 +70,8 @@ def show(
         if not noselect:
             from kash.commands.workspace.selection_commands import select
 
-            select(input_path)
+            if isinstance(input_path, StorePath):
+                select(input_path)
             return ShellResult(show_selection=True)
     except (InvalidInput, InvalidState):
         if path:

kash/commands/help/assistant_commands.py

@@ -31,9 +31,10 @@ def assist(
     Invoke the kash assistant. You don't normally need this command as it is the same as just
     asking a question (a question ending with ?) on the kash console.
 
-    :param type: The type of assistance to use.
-    :param model: The model to use for the assistant. If not provided, the default model
-        for the assistant type is used.
+    Args:
+        type: The type of assistance to use.
+        model: The model to use for the assistant. If not provided, the default model
+            for the assistant type is used.
     """
     if not input:
         input = input_simple_string(
@@ -81,7 +82,8 @@ def assistant_history(follow: bool = False) -> None:
     """
     Show the assistant history for the current workspace.
 
-    :param follow: Follow the file as it grows.
+    Args:
+        follow: Follow the file as it grows.
     """
     ws = current_ws()
     tail_file(ws.base_dir / ws.dirs.assistant_history_yml, follow=follow)

kash/commands/help/help_commands.py

@@ -37,8 +37,9 @@ def help(query: str | None = None, search: bool = False) -> None:
     Note that if you want Python `help()` and not kash help, use the
     alias `pyhelp`.
 
-    :param search: If true, does a simple search of help docs
-       (same as `search_help`).
+    Args:
+        search: If true, does a simple search of help docs
+            (same as `search_help`).
     """
     if not search and not query:
         manual()
@@ -53,7 +54,8 @@ def commands(no_pager: bool = False, full: bool = False) -> None:
     """
     Show help on all kash commands.
 
-    :param full: If true, show full help for each command.
+    Args:
+        full: If true, show full help for each command.
     """
     from kash.help.help_pages import print_builtin_commands_help
 
@@ -73,7 +75,8 @@ def actions(no_pager: bool = False, full: bool = False) -> None:
     """
     Show help on the full list of currently loaded actions.
 
-    :param full: If true, show full help for each action.
+    Args:
+        full: If true, show full help for each action.
     """
     from kash.help.help_pages import print_actions_help
 

kash/commands/workspace/selection_commands.py

@@ -43,17 +43,18 @@ def select(
     If any other flags are given, they show or modify the selection history.
     They must be used individually (and without paths).
 
-    :param history: Show the full selection history.
-    :param last: Show the last `last` selections in the history.
-    :param back: Move back in the selection history by `back` steps.
-    :param forward: Move forward in the selection history by `forward` steps.
-    :param previous: Move back in the selection history to the previous selection.
-    :param next: Move forward in the selection history to the next selection.
-    :param pop: Pop the current selection from the history.
-    :param clear_all: Clear the full selection history.
-    :param clear_future: Clear all selections from history after the current one.
-    :param refresh: Refresh the current selection to drop any paths that no longer exist.
-    :param no_check: Do not check if the paths exist.
+    Args:
+        history: Show the full selection history.
+        last: Show the last `last` selections in the history.
+        back: Move back in the selection history by `back` steps.
+        forward: Move forward in the selection history by `forward` steps.
+        previous: Move back in the selection history to the previous selection.
+        next: Move forward in the selection history to the next selection.
+        pop: Pop the current selection from the history.
+        clear_all: Clear the full selection history.
+        clear_future: Clear all selections from history after the current one.
+        refresh: Refresh the current selection to drop any paths that no longer exist.
+        no_check: Do not check if the paths exist.
     """
     ws = current_ws()
 
@@ -182,11 +183,12 @@ def save(parent: str | None = None, to: str | None = None, no_frontmatter: bool
     Save the current selection to the given directory, or to the current directory if no
     target given.
 
-    :param parent: The directory to save the files to. If not given, it will be the
-        current directory.
-    :param to: If only one file is selected, a name to save it as. If it exists, it will
-        overwrite (and make a backup).
-    :param no_frontmatter: If true, will not include YAML frontmatter in the output.
+    Args:
+        parent: The directory to save the files to. If not given, it will be the
+            current directory.
+        to: If only one file is selected, a name to save it as. If it exists, it will
+            overwrite (and make a backup).
+        no_frontmatter: If true, will not include YAML frontmatter in the output.
     """
     ws = current_ws()
     store_paths = ws.selections.current.paths