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

kash/model/items_model.py

@@ -6,7 +6,7 @@ from dataclasses import asdict, field, is_dataclass
 from datetime import UTC, datetime
 from enum import Enum
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, NotRequired, TypedDict, TypeVar, Unpack
 
 from frontmatter_format import from_yaml_string, new_yaml
 from prettyfmt import (
@@ -120,6 +120,28 @@ class IdType(Enum):
     source = "source"
 
 
+class ItemUpdateOptions(TypedDict, total=False):
+    """
+    Keyword arguments that can be passed to update an Item.
+    """
+
+    type: NotRequired[ItemType]
+    state: NotRequired[State]
+    title: NotRequired[str | None]
+    url: NotRequired[Url | None]
+    description: NotRequired[str | None]
+    format: NotRequired[Format | None]
+    file_ext: NotRequired[FileExt | None]
+    body: NotRequired[str | None]
+    external_path: NotRequired[str | None]
+    original_filename: NotRequired[str | None]
+    relations: NotRequired[ItemRelations]
+    source: NotRequired[Source | None]
+    history: NotRequired[list[OperationSummary] | None]
+    thumbnail_url: NotRequired[Url | None]
+    extra: NotRequired[dict | None]
+
+
 @dataclass(frozen=True)
 class ItemId:
     """
@@ -156,7 +178,9 @@ 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.
@@ -258,7 +282,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 ""
+            f"{fmt_store_path(item_dict['store_path'])}: "
+            if "store_path" in item_dict
+            else ""
         )
 
         # Metadata formats might change over time so it's important to gracefully handle issues.
@@ -288,7 +314,9 @@ 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")
 
@@ -306,7 +334,9 @@ 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
         }
@@ -355,7 +385,9 @@ 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,
@@ -406,7 +438,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
         """
@@ -459,7 +493,9 @@ 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.
@@ -507,17 +543,16 @@ class Item:
             return abbrev_str(self.url, max_len)
 
         # Special case for filenames with no title.
-        path_stem = (
-            (self.store_path and Path(self.store_path).stem)
-            or (self.external_path and Path(self.external_path).stem)
-            or (self.original_filename and Path(self.original_filename).stem)
+        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)
         )
-        if not self.title and path_stem:
-            return abbrev_str(path_stem, max_len)
 
-        # Otherwise, use the title, description, or body text.
+        # Use the title or the path if possible, falling back to description or even body text.
         title_raw_text = (
             self.title
+            or path_name
             or self.description
             or (not self.is_binary and self.abbrev_body(max_len))
             or UNTITLED
@@ -582,7 +617,9 @@ 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:
         """
@@ -613,7 +650,6 @@ class Item:
         """
         Get the full file extension suffix (e.g. "note.md") for this item.
         """
-
         if self.type == ItemType.extension:
             # Python files cannot have more than one . in them.
             return f"{FileExt.py.value}"
@@ -647,7 +683,10 @@ class Item:
         raise ValueError(f"Cannot convert item of type {self.format} to HTML: {self}")
 
     def _copy_and_update(
-        self, other: Item | None = None, update_timestamp: bool = False, **other_updates
+        self,
+        other: Item | None = None,
+        update_timestamp: bool = False,
+        **other_updates: Unpack[ItemUpdateOptions],
     ) -> dict[str, Any]:
         overrides: dict[str, Any] = {"store_path": None, "modified_at": None}
         if update_timestamp:
@@ -665,12 +704,16 @@ class Item:
 
         return fields
 
-    def new_copy_with(self, update_timestamp: bool = True, **other_updates) -> Item:
+    def new_copy_with(
+        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.
         """
-        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:
@@ -681,7 +724,7 @@ class Item:
         merged_fields = self._copy_and_update(other, update_timestamp=False)
         return Item(**merged_fields)
 
-    def derived_copy(self, type: ItemType, **other_updates) -> Item:
+    def derived_copy(self, **updates: Unpack[ItemUpdateOptions]) -> Item:
         """
         Same as `new_copy_with()`, but also makes any other updates and updates the
         `derived_from` relation. If we also have an action context, then use the
@@ -706,12 +749,12 @@ class Item:
         else:
             derived_from = [StorePath(self.store_path)]
 
-        updates = other_updates.copy()
-        updates["type"] = type
+        updates = updates.copy()
 
         # If format was specified and user didn't specify file_ext, then infer it.
-        if "file_ext" not in other_updates and "format" in other_updates:
-            updates["file_ext"] = other_updates["format"].file_ext
+        if "file_ext" not in updates and "format" in updates:
+            assert updates["format"] is not None
+            updates["file_ext"] = updates["format"].file_ext
 
         # External resource paths only make sense for resources, so clear them out if new item
         # is not a resource.
@@ -724,8 +767,10 @@ class Item:
             new_item.update_relations(derived_from=derived_from)
 
         # Fall back to action title template if we have it and title wasn't explicitly set.
-        if "title" not in other_updates:
-            prev_title = self.title or (Path(self.store_path).stem if self.store_path else UNTITLED)
+        if "title" not in updates:
+            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(
@@ -764,7 +809,8 @@ class Item:
 
     def content_equals(self, other: Item) -> bool:
         """
-        Check if two items have identical content, ignoring timestamps and store path.
+        Check if two items have identical content, ignoring timestamps, store path,
+        and any trailing newlines or whitespace.
         """
         # Check relevant metadata fields.
         self_fields = self.__dict__.copy()

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/doc_normalization.py

@@ -23,7 +23,7 @@ def normalize_formatting_ansi(text: str, format: Format | None, width=DEFAULT_WR
     elif format == Format.markdown or format == Format.md_html:
         return fill_markdown(
             text,
-            line_wrapper=line_wrap_by_sentence(len_fn=ansi_cell_len),
+            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:

kash/text_handling/markdown_render.py

@@ -39,6 +39,7 @@ 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>"""
     )

kash/text_handling/markdown_utils.py

@@ -83,6 +83,19 @@ def extract_links(file_path: str, include_internal=False) -> list[str]:
         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
@@ -182,6 +195,15 @@ def test_escape_markdown() -> None:
     )
 
 
+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"