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

kash/model/exec_model.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from prettyfmt import abbrev_obj
+from pydantic.dataclasses import dataclass
+
+from kash.config.logger import get_logger
+from kash.model.items_model import State
+
+if TYPE_CHECKING:
+    from kash.file_storage.file_store import FileStore
+    from kash.model.actions_model import Action
+
+
+log = get_logger(__name__)
+
+
+@dataclass(frozen=True)
+class RuntimeSettings:
+    """
+    Workspace and other runtime settings that may be set across runs of
+    one or more actions.
+    """
+
+    workspace_dir: Path
+    """The workspace directory in which the action is being executed."""
+
+    rerun: bool = False
+    """If True, always run actions, even cacheable ones that have results."""
+
+    refetch: bool = False
+    """If True, will refetch items even if they are already in the content caches."""
+
+    override_state: State | None = None
+    """If specified, override the state of result items. Useful to mark items as transient."""
+
+    tmp_output: bool = False
+    """If True, will save output items to a temporary file."""
+
+    no_format: bool = False
+    """If True, will not normalize the output item's body text formatting (for Markdown)."""
+
+    @property
+    def workspace(self) -> FileStore:
+        from kash.workspaces.workspaces import get_ws
+
+        return get_ws(self.workspace_dir)
+
+    @property
+    def non_default_options(self) -> dict[str, str]:
+        """
+        Summarize non-default runtime options as a dict.
+        """
+        opts: dict[str, str] = {}
+        # Only these two settings directly affect the output:
+        if self.no_format:
+            opts["no_format"] = "true"
+        if self.override_state:
+            opts["override_state"] = self.override_state.name
+        return opts
+
+    def __repr__(self):
+        return abbrev_obj(self, field_max_len=80)
+
+
+@dataclass(frozen=True)
+class ExecContext:
+    """
+    An action and its context for execution. This is a good place for settings
+    that apply to any action and are bothersome to pass as parameters.
+    """
+
+    action: Action
+    """The action being executed."""
+
+    settings: RuntimeSettings
+    """The workspace and other run-time settings for the action."""

kash/model/items_model.py

@@ -25,6 +25,7 @@ from kash.model.media_model import MediaMetadata
 from kash.model.operations_model import OperationSummary, Source
 from kash.model.paths_model import StorePath, fmt_store_path
 from kash.text_handling.markdown_render import markdown_to_html
+from kash.text_handling.markdown_utils import first_heading
 from kash.utils.common.format_utils import fmt_loc, html_to_plaintext, plaintext_to_html
 from kash.utils.common.url import Locator, Url
 from kash.utils.errors import FileFormatError
@@ -32,7 +33,7 @@ from kash.utils.file_formats.chat_format import ChatHistory
 from kash.utils.file_utils.file_formats_model import FileExt, Format
 
 if TYPE_CHECKING:
-    from kash.model.actions_model import ExecContext
+    from kash.model.exec_model import ExecContext
     from kash.workspaces import Workspace
 
 log = get_logger(__name__)
@@ -178,9 +179,7 @@ class ItemId:
         if item.type == ItemType.resource and item.format == Format.url and item.url:
             item_id = ItemId(item.type, IdType.url, canonicalize_url(item.url))
         elif item.type == ItemType.concept and item.title:
-            item_id = ItemId(
-                item.type, IdType.concept, canonicalize_concept(item.title)
-            )
+            item_id = ItemId(item.type, IdType.concept, canonicalize_concept(item.title))
         elif item.source and item.source.cacheable:
             # We know the source of this and if the action was cacheable, we can create
             # an identity based on the source.
@@ -281,11 +280,9 @@ class Item:
         """
         item_dict = {**item_dict, **kwargs}
 
-        info_prefix = (
-            f"{fmt_store_path(item_dict['store_path'])}: "
-            if "store_path" in item_dict
-            else ""
-        )
+        info_prefix = ""
+        if "store_path" in item_dict and item_dict["store_path"]:
+            info_prefix = f"{fmt_store_path(item_dict['store_path'])}: "
 
         # Metadata formats might change over time so it's important to gracefully handle issues.
         def set_field(key: str, default: Any, cls_: type[T]) -> T:
@@ -314,9 +311,7 @@ class Item:
         body = item_dict.get("body")
         history = [OperationSummary(**op) for op in item_dict.get("history", [])]
         relations = (
-            ItemRelations(**item_dict["relations"])
-            if "relations" in item_dict
-            else ItemRelations()
+            ItemRelations(**item_dict["relations"]) if "relations" in item_dict else ItemRelations()
         )
         store_path = item_dict.get("store_path")
 
@@ -334,9 +329,7 @@ class Item:
         ]
         all_fields = [f.name for f in cls.__dataclass_fields__.values()]
         allowed_fields = [f for f in all_fields if f not in excluded_fields]
-        other_metadata = {
-            key: value for key, value in item_dict.items() if key in allowed_fields
-        }
+        other_metadata = {key: value for key, value in item_dict.items() if key in allowed_fields}
         unexpected_metadata = {
             key: value for key, value in item_dict.items() if key not in all_fields
         }
@@ -385,9 +378,7 @@ class Item:
         if not item_type:
             # Default to doc for general text files and resource for everything else.
             item_type = (
-                ItemType.doc
-                if format and format.supports_frontmatter
-                else ItemType.resource
+                ItemType.doc if format and format.supports_frontmatter else ItemType.resource
             )
         item = cls(
             type=item_type,
@@ -438,11 +429,9 @@ class Item:
         if not self.format:
             raise ValueError(f"Item has no format: {self}")
         if self.type.expects_body and self.format.has_body and not self.body:
-            raise ValueError(
-                f"Item type `{self.type.value}` is text but has no body: {self}"
-            )
+            raise ValueError(f"Item type `{self.type.value}` is text but has no body: {self}")
 
-    def absolute_path(self, ws: "Workspace | None" = None) -> Path:  # noqa: UP037
+    def absolute_path(self, ws: Workspace | None = None) -> Path:
         """
         Get the absolute path to the item. Throws `ValueError` if the item has no
         store path. If no workspace is provided, uses the current workspace.
@@ -493,9 +482,7 @@ class Item:
                 return {k: serialize(v) for k, v in v.items()}
             elif isinstance(v, Enum):
                 return v.value
-            elif hasattr(
-                v, "as_dict"
-            ):  # Handle Operation or any object with as_dict method.
+            elif hasattr(v, "as_dict"):  # Handle Operation or any object with as_dict method.
                 return v.as_dict()
             elif is_dataclass(v) and not isinstance(v, type):
                 # Handle Python and Pydantic dataclasses.
@@ -532,22 +519,38 @@ class Item:
             display_title = self.abbrev_title()
         return display_title
 
-    def abbrev_title(self, max_len: int = 100, add_ops_suffix: bool = True) -> str:
+    def abbrev_title(
+        self,
+        *,
+        max_len: int = 100,
+        add_ops_suffix: bool = False,
+        pull_body_heading: bool = False,
+    ) -> str:
         """
         Get or infer a title for this item, falling back to the filename, URL,
         description, or finally body text.
         Optionally, include the last operation as a parenthetical at the end of the title.
         """
-        # Special case for URLs with no title..
+        from kash.file_storage.store_filenames import parse_item_filename
+
+        # First special case: if we are pulling the title from the body header, check
+        # that.
+        if not self.title and pull_body_heading:
+            heading = self.body_heading()
+            if heading:
+                return heading
+
+        # Next special case: URLs with no title use the url itself.
         if not self.title and self.url:
             return abbrev_str(self.url, max_len)
 
         # Special case for filenames with no title.
-        path_name = (
-            (self.store_path and Path(self.store_path).name)
-            or (self.external_path and Path(self.external_path).name)
-            or (self.original_filename and Path(self.original_filename).name)
-        )
+        # Use stem to drop suffix like .resource.docx etc in a title.
+        path = self.store_path or self.external_path or self.original_filename
+        if path:
+            path_name, _item_type, _format, _file_ext = parse_item_filename(Path(path).name)
+        else:
+            path_name = None
 
         # Use the title or the path if possible, falling back to description or even body text.
         title_raw_text = (
@@ -559,10 +562,14 @@ class Item:
         )
 
         suffix = ""
-        if add_ops_suffix and self.type not in [ItemType.concept, ItemType.resource]:
-            # For notes, exports, etc but not for concepts, add a parenthical note
-            # indicating the last operation, if there was one. This makes filename slugs
-            # more readable.
+        # For docs, etc but not for concepts/resources/exports, add a parenthical note
+        # indicating the last operation, if there was one. This makes filename slugs
+        # more readable.
+        if add_ops_suffix and self.type not in [
+            ItemType.concept,
+            ItemType.resource,
+            ItemType.export,
+        ]:
             last_op = self.history and self.history[-1].action_name
             if last_op:
                 step_num = len(self.history) + 1 if self.history else 1
@@ -579,9 +586,18 @@ class Item:
 
         return final_text
 
+    def body_heading(self) -> str | None:
+        """
+        Get the first h1 or h2 heading from the body text, if present.
+        """
+        if self.format in [Format.markdown, Format.md_html]:
+            return first_heading(self.body_text(), allowed_tags=("h1", "h2"))
+        # TODO: Support HTML <h1> and <h2> as well.
+        return None
+
     def abbrev_body(self, max_len: int) -> str:
         """
-        Get a cut off version of the body text. Must not be a binary Item.
+        Get an abbreviated version of the body text. Must not be a binary Item.
         Abbreviates YAML bodies like {"role": "user", "content": "Hello"} to "user Hello".
         """
         body_text = self.body_text()[:max_len]
@@ -609,7 +625,7 @@ class Item:
         Get a readable slugified version of the title or filename or content
         appropriate for this item. May not be unique.
         """
-        title = self.abbrev_title(max_len=max_len)
+        title = self.abbrev_title(max_len=max_len, add_ops_suffix=True)
         slug = slugify_snake(title)
         return slug
 
@@ -617,9 +633,7 @@ class Item:
         """
         Get or infer description.
         """
-        return abbrev_on_words(
-            html_to_plaintext(self.description or self.body or ""), max_len
-        )
+        return abbrev_on_words(html_to_plaintext(self.description or self.body or ""), max_len)
 
     def read_as_config(self) -> Any:
         """
@@ -656,6 +670,9 @@ class Item:
         elif self.type == ItemType.script:
             # Same for kash/xonsh scripts.
             return f"{self.type.value}.{FileExt.xsh.value}"
+        elif self.type == ItemType.export:
+            # For exports, skip the item type to keep it maximally compatible for external tools.
+            return f"{self.get_file_ext().value}"
         else:
             return f"{self.type.value}.{self.get_file_ext().value}"
 
@@ -668,11 +685,19 @@ class Item:
         return "\n\n".join(part for part in parts if part)
 
     def body_text(self) -> str:
+        """
+        Body text of the item, also validating that the item is not binary.
+        """
         if self.is_binary:
             raise ValueError("Cannot get text content of a binary Item")
         return self.body or ""
 
     def body_as_html(self) -> str:
+        """
+        Body of the item, converted to HTML format. Validates that the body format can be
+        converted and then converts plaintext or Markdown to HTML. Simply returns the body
+        if it is already HTML.
+        """
         if self.format == Format.html:
             return self.body_text()
         elif self.format == Format.plaintext:
@@ -708,12 +733,10 @@ class Item:
         self, update_timestamp: bool = True, **other_updates: Unpack[ItemUpdateOptions]
     ) -> Item:
         """
-        Copy item with the given field updates. Resets store_path to None. Updates
-        created time if requested.
+        Copy item with the given field updates. Resets `store_path` to None but preserves
+        other fields, including the body. Updates created time if requested.
         """
-        new_fields = self._copy_and_update(
-            update_timestamp=update_timestamp, **other_updates
-        )
+        new_fields = self._copy_and_update(update_timestamp=update_timestamp, **other_updates)
         return Item(**new_fields)
 
     def merged_copy(self, other: Item) -> Item:
@@ -734,7 +757,7 @@ class Item:
             if self.relations.derived_from:
                 log.message(
                     "Deriving from an item that has not been saved so using "
-                    "its derived_from relation: %s on %s",
+                    "upstream derived_from relation: %s on %s",
                     self.relations.derived_from,
                     self,
                 )
@@ -768,9 +791,7 @@ class Item:
 
         # Fall back to action title template if we have it and title wasn't explicitly set.
         if "title" not in updates:
-            prev_title = self.title or (
-                Path(self.store_path).stem if self.store_path else UNTITLED
-            )
+            prev_title = self.title or (Path(self.store_path).stem if self.store_path else UNTITLED)
             if self.context:
                 action = self.context.action
                 new_item.title = action.title_template.format(

kash/model/operations_model.py

@@ -25,27 +25,46 @@ class OperationSummary:
 class Input:
     """
     An input to an operation, which may include a hash fingerprint.
+    Typically an input is a StorePath, but it could be something else like an in-memory
+    item that hasn't been saved yet.
     """
 
-    # TODO: May want to support Locators or other inputs besides StorePaths.
-    path: StorePath
+    path: StorePath | None
     hash: str | None = None
+    source_info: str | None = None
 
     @classmethod
     def parse(cls, input_str: str) -> Input:
         """
-        Parse an Input string in the format `some/path/filename.ext@sha1:hash` or
-        `@some/path/filename.ext@sha1:hash`, with a store path and a hash.
+        Parse an Input string in the format printed by `Input.parseable_str()`.
         """
-        parts = input_str.rsplit("@", 1)
-        if len(parts) == 2:
-            path, hash = parts
-            return cls(path=StorePath(path), hash=hash)
+        if input_str.startswith("[") and input_str.endswith("]"):
+            return cls(path=None, hash=None, source_info=input_str[1:-1])
         else:
-            return cls(path=StorePath(input_str), hash=None)
-
-    def path_and_hash(self):
-        return f"{fmt_loc(self.path)}@{self.hash}"
+            parts = input_str.rsplit("@", 1)
+            if len(parts) == 2:
+                path, hash = parts
+                return cls(path=StorePath(path), hash=hash)
+            else:
+                return cls(path=StorePath(input_str), hash=None)
+
+    def parseable_str(self):
+        """
+        A readable and parseable string describing the input, typically a hash and a path but
+        could be a path without a hash or another info in brackets. Paths may have an `@` at the
+        front.
+
+        some/path.txt@sha1:1234567890
+        @some/path.txt@sha1:1234567890
+        some/path.txt
+        [unsaved]
+        """
+        if self.path and self.hash:
+            return f"{fmt_loc(self.path)}@{self.hash}"
+        elif self.source_info:
+            return f"[{self.source_info}]"
+        else:
+            return "[input info missing]"
 
     # Inputs are equal if the hashes match (even if the paths have changed).
 
@@ -53,6 +72,10 @@ class Input:
         return hash(self.hash) if self.hash else object.__hash__(self)
 
     def __eq__(self, other: Any) -> bool:
+        """
+        Inputs are equal if the hashes match (even if the paths have changed) or if the paths
+        are the same. They are *not* equal otherwise, even if the source_info is the same.
+        """
         if not isinstance(other, Input):
             return NotImplemented
         if self.hash and other.hash:
@@ -62,7 +85,7 @@ class Input:
         return False
 
     def __str__(self):
-        return self.path_and_hash()
+        return self.parseable_str()
 
 
 @dataclass(frozen=True)
@@ -88,7 +111,7 @@ class Operation:
         }
 
         if self.arguments:
-            d["arguments"] = [arg.path_and_hash() for arg in self.arguments]
+            d["arguments"] = [arg.parseable_str() for arg in self.arguments]
         if self.options:
             d["options"] = self.options
 
@@ -101,7 +124,7 @@ class Operation:
         return [shell_quote(str(arg.path)) for arg in self.arguments]
 
     def hashed_args(self):
-        return [arg.path_and_hash() for arg in self.arguments]
+        return [arg.parseable_str() for arg in self.arguments]
 
     def quoted_options(self):
         return [f"--{k}={shell_quote(str(v))}" for k, v in self.options.items()]

kash/model/paths_model.py

@@ -264,6 +264,8 @@ def fmt_store_path(store_path: str | Path | StorePath) -> str:
     """
     Format a store path as a string.
     """
+    if not store_path:
+        raise ValueError("Cannot format empty store path")
     return StorePath(store_path).display_str()
 
 

kash/shell/output/shell_output.py

@@ -16,7 +16,7 @@ from rich.rule import Rule
 from rich.style import Style
 from rich.text import Text
 
-from kash.config.logger import get_console
+from kash.config.logger import get_console, is_console_quiet
 from kash.config.text_styles import (
     COLOR_HINT_DIM,
     COLOR_RESPONSE,
@@ -31,9 +31,6 @@ from kash.shell.output.kmarkdown import KMarkdown
 from kash.utils.rich_custom.rich_indent import Indent
 from kash.utils.rich_custom.rich_markdown_fork import Markdown
 
-console = get_console()
-
-
 print_context_var: contextvars.ContextVar[str] = contextvars.ContextVar("print_prefix", default="")
 """
 Context variable override for print prefix.
@@ -99,7 +96,12 @@ def rich_print(
     Print to the Rich console, either the global console or a thread-local
     override, if one is active. With `raw` true, we bypass rich formatting
     entirely and simply write to the console stream.
+
+    Output is suppressed by the global `console_quiet` setting.
     """
+    if is_console_quiet():
+        return
+
     console = get_console()
     if raw:
         # TODO: Indent not supported in raw mode.
@@ -136,7 +138,7 @@ def cprint(
     raw: bool = False,
 ):
     """
-    Main way to print to the shell. Wraps `rprint` with our additional
+    Main way to print to the shell. Wraps `rich_print` with our additional
     formatting options for text fill and prefix.
     """
     empty_indent = extra_indent.strip()
@@ -323,8 +325,8 @@ class PrintHooks(Enum):
     after_command_run = "after_command_run"
     before_status = "before_status"
     after_status = "after_status"
-    before_shell_action_run = "before_action_run"
-    after_shell_action_run = "after_action_run"
+    before_shell_action_run = "before_shell_action_run"
+    after_shell_action_run = "after_shell_action_run"
     before_log_action_run = "before_log_action_run"
     before_assistance = "before_assistance"
     after_assistance = "after_assistance"
@@ -376,7 +378,7 @@ class PrintHooks(Enum):
         elif self == PrintHooks.nonfatal_exception:
             self.nl()
         elif self == PrintHooks.before_done_message:
-            self.nl()
+            pass
         elif self == PrintHooks.before_output:
             self.nl()
         elif self == PrintHooks.after_output:

kash/shell/shell_main.py

@@ -14,10 +14,10 @@ import argparse
 import threading
 
 import xonsh.main
+from clideps.utils.readable_argparse import ReadableColorFormatter
 from strif import quote_if_needed
 
 from kash.config.setup import kash_setup
-from kash.shell.utils.argparse_utils import WrappedColorFormatter
 from kash.shell.version import get_full_version_name, get_version
 from kash.xonsh_custom.custom_shell import install_to_xonshrc, start_shell
 
@@ -51,7 +51,7 @@ def run_shell(single_command: str | None = None):
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description=__doc__, formatter_class=WrappedColorFormatter)
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=ReadableColorFormatter)
 
     parser.add_argument("--version", action="version", version=get_full_version_name())
 

kash/shell/utils/exception_printing.py

@@ -5,7 +5,7 @@ from typing import TypeVar
 from kash.config.logger import get_logger
 from kash.config.text_styles import COLOR_ERROR
 from kash.shell.output.shell_output import PrintHooks
-from kash.utils.errors import NONFATAL_EXCEPTIONS
+from kash.utils.errors import get_nonfatal_exceptions
 
 log = get_logger(__name__)
 
@@ -41,7 +41,7 @@ def wrap_with_exception_printing(func: Callable[..., R]) -> Callable[[list[str]]
                 (", ".join(str(arg) for arg in args)),
             )
             return func(*args)
-        except NONFATAL_EXCEPTIONS as e:
+        except get_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)

kash/text_handling/doc_normalization.py

@@ -2,7 +2,7 @@ from pathlib import Path
 
 from flowmark import fill_markdown, fill_text, line_wrap_by_sentence
 from flowmark.text_filling import DEFAULT_WRAP_WIDTH
-from flowmark.text_wrapping import simple_word_splitter, wrap_paragraph
+from flowmark.text_wrapping import simple_word_splitter
 from frontmatter_format import fmf_read, fmf_write
 
 from kash.utils.common.format_utils import fmt_loc
@@ -11,20 +11,26 @@ from kash.utils.file_utils.file_formats_model import Format, detect_file_format
 from kash.utils.rich_custom.ansi_cell_len import ansi_cell_len
 
 
-def normalize_formatting_ansi(text: str, format: Format | None, width=DEFAULT_WRAP_WIDTH) -> str:
+def normalize_formatting(
+    text: str,
+    format: Format | None,
+    width=DEFAULT_WRAP_WIDTH,
+    support_ansi: bool = True,
+    cleanups: bool = True,
+) -> str:
     """
     Normalize text formatting by wrapping lines and normalizing Markdown.
+    This only does "safe" normalizations that cannot break the text.
     Enables ANSI support so ANSI codes and OSC-8 links are correctly handled.
     """
+    len_fn = ansi_cell_len if support_ansi else len
     if format == Format.plaintext:
-        return fill_text(
-            text, width=width, word_splitter=simple_word_splitter, len_fn=ansi_cell_len
-        )
+        return fill_text(text, width=width, word_splitter=simple_word_splitter, len_fn=len_fn)
     elif format == Format.markdown or format == Format.md_html:
         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.
+            line_wrapper=line_wrap_by_sentence(len_fn=len_fn, is_markdown=True),
+            cleanups=cleanups,
         )
     elif format == Format.html:
         # We don't currently auto-format HTML as we sometimes use HTML with specifically chosen line breaks.
@@ -37,6 +43,7 @@ def normalize_text_file(
     path: str | Path,
     target_path: Path,
     format: Format | None = None,
+    support_ansi: bool = True,
 ) -> None:
     """
     Normalize formatting on a text file, handling Markdown, HTML, or text, as well as
@@ -48,7 +55,7 @@ def normalize_text_file(
         raise ValueError(f"Cannot format non-text files: {fmt_loc(path)}")
 
     content, metadata = fmf_read(path)
-    norm_content = normalize_formatting_ansi(content, format=format)
+    norm_content = normalize_formatting(content, format=format, support_ansi=support_ansi)
     fmf_write(not_none(target_path), norm_content, metadata)
 
 
@@ -57,6 +64,7 @@ def normalize_text_file(
 
 def test_osc8_link():
     from clideps.terminal.osc_utils import osc8_link
+    from flowmark.text_wrapping import wrap_paragraph
 
     link = osc8_link("https://example.com/" + "x" * 50, "Example")
     assert ansi_cell_len(link) == 7