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

kash/exec/action_decorators.py

@@ -174,7 +174,7 @@ def _merge_param_declarations(
             merged_params[fp.name] = Param(
                 name=fp.name,
                 description=None,
-                type=fp.type or str,
+                type=fp.effective_type or str,
                 default_value=fp.default if fp.has_default else None,
                 is_explicit=not fp.has_default,
             )
@@ -210,7 +210,12 @@ def kash_action(
     title_template: TitleTemplate = TitleTemplate("{title}"),
     llm_options: LLMOptions = LLMOptions(),
     override_state: State | None = None,
+    # Including these for completeness but usually don't want to set them globally
+    # in the decorator:
     rerun: bool = False,
+    refetch: bool = False,
+    tmp_output: bool = False,
+    no_format: bool = False,
 ) -> Callable[[AF], AF]:
     """
     A function decorator to create and register an action. The annotated function must
@@ -243,13 +248,13 @@ def kash_action(
 
         # Inspect and sanity check the formal params.
         func_params = inspect_function_params(orig_func)
-        if len(func_params) == 0 or func_params[0].type not in (ActionInput, Item):
+        if len(func_params) == 0 or func_params[0].effective_type not in (ActionInput, Item):
             raise InvalidDefinition(
                 f"Decorator `@kash_action` requires exactly one positional parameter, "
                 f"`input` of type `ActionInput` or `Item` on function `{orig_func.__name__}` but "
                 f"got params: {func_params}"
             )
-        if any(fp.is_positional for fp in func_params[1:]):
+        if any(fp.is_pure_positional for fp in func_params[1:]):
             raise InvalidDefinition(
                 "Decorator `@kash_action` requires all parameters after the first positional "
                 f"parameter to be keyword parameters on function `{orig_func.__name__}` but "
@@ -260,7 +265,7 @@ def kash_action(
         context_param = next((fp for fp in func_params if fp.name == "context"), None)
         if context_param:
             func_params.remove(context_param)
-        if context_param and context_param.is_positional:
+        if context_param and context_param.is_pure_positional:
             raise InvalidDefinition(
                 "Decorator `@kash_action` requires the `context` parameter to be a keyword "
                 "parameter, not positional, on function `{func.__name__}`"
@@ -268,7 +273,7 @@ def kash_action(
 
         # If the original function is a simple action function (processes a single item),
         # wrap it to convert to an ActionFunction.
-        is_simple_func = func_params[0].type == Item
+        is_simple_func = func_params[0].effective_type == Item
         action_func: ActionFunction
         if is_simple_func:
             simple_func = cast(SimpleActionFunction, orig_func)
@@ -328,13 +333,16 @@ def kash_action(
                 if context_param:
                     kw_args["context"] = context
                 for fp in func_params[1:]:
-                    if fp.is_positional:
+                    if fp.is_pure_positional:
                         pos_args.append(self.get_param(fp.name))
                     else:
                         kw_args[fp.name] = self.get_param(fp.name)
 
-                log.info("Action function param declarations:\n%s", fmt_lines(self.params))
-                log.info("Action function param values:\n%s", self.param_value_summary_str())
+                if self.params:
+                    log.info("Action function param declarations:\n%s", fmt_lines(self.params))
+                    log.info("Action function param values:\n%s", self.param_value_summary_str())
+                else:
+                    log.info("Action function has no declared params")
 
                 log.message(
                     "Action function call:\n%s",
@@ -379,11 +387,17 @@ def kash_action(
                 context = provided_context
             else:
                 context = ExecContext(
-                    action, current_ws().base_dir, rerun=rerun, override_state=override_state
+                    action,
+                    current_ws().base_dir,
+                    rerun=rerun,
+                    refetch=refetch,
+                    override_state=override_state,
+                    tmp_output=tmp_output,
+                    no_format=no_format,
                 )
 
             # Run the action.
-            result, _, _ = run_action_with_caching(context, action_input, rerun=rerun)
+            result, _, _ = run_action_with_caching(context, action_input)
 
             return result
 

kash/exec/action_exec.py

@@ -32,7 +32,7 @@ from kash.workspaces.workspace_importing import import_and_load
 log = get_logger(__name__)
 
 
-def prepare_action_input(*input_args: CommandArg) -> ActionInput:
+def prepare_action_input(*input_args: CommandArg, refetch: bool = False) -> ActionInput:
     """
     Prepare input args, which may be URLs or paths, into items that correspond to
     URL or file resources, either finding them in the workspace or importing them.
@@ -50,13 +50,16 @@ def prepare_action_input(*input_args: CommandArg) -> ActionInput:
     if input_items:
         log.message("Assembling metadata for input items:\n%s", fmt_lines(input_items))
         input_items = [
-            fetch_url_item_metadata(item) if is_url_item(item) else item for item in input_items
+            fetch_url_item_metadata(item, refetch=refetch) if is_url_item(item) else item
+            for item in input_items
         ]
 
     return ActionInput(input_items)
 
 
-def validate_action_input(ws: FileStore, action: Action, action_input: ActionInput) -> Operation:
+def validate_action_input(
+    context: ExecContext, ws: FileStore, action: Action, action_input: ActionInput
+) -> Operation:
     """
     Validate an action input, ensuring the right number of args, all explicit params are filled,
     and the precondition holds and return an `Operation` that describes what will happen.
@@ -74,7 +77,9 @@ def validate_action_input(ws: FileStore, action: Action, action_input: ActionInp
     # If the inputs are paths, record the input paths, including hashes.
     store_paths = [StorePath(not_none(item.store_path)) for item in input_items if item.store_path]
     inputs = [Input(store_path, ws.hash(store_path)) for store_path in store_paths]
-    operation = Operation(action.name, inputs, action.param_value_summary())
+    # Add any non-default runtime options into the options summary.
+    options = {**action.param_value_summary(), **context.runtime_options}
+    operation = Operation(action.name, inputs, options)
 
     return operation
 
@@ -93,10 +98,7 @@ def log_action(action: Action, action_input: ActionInput, operation: Operation):
 
 
 def check_for_existing_result(
-    context: ExecContext,
-    action_input: ActionInput,
-    operation: Operation,
-    rerun: bool = False,
+    context: ExecContext, action_input: ActionInput, operation: Operation
 ) -> ActionResult | None:
     """
     Check if we already have the results for this operation (same action and inputs)
@@ -105,7 +107,7 @@ def check_for_existing_result(
     """
     action = context.action
     ws = context.workspace
-    rerun = context.rerun or rerun
+    rerun = context.rerun
 
     existing_result = None
 
@@ -261,7 +263,12 @@ def _run_for_each_item(context: ExecContext, input: ActionInput) -> ActionResult
 
 
 def save_action_result(
-    ws: FileStore, result: ActionResult, action_input: ActionInput
+    ws: FileStore,
+    result: ActionResult,
+    action_input: ActionInput,
+    *,
+    as_tmp: bool = False,
+    no_format: bool = False,
 ) -> tuple[list[StorePath], list[StorePath]]:
     """
     Save the result of an action to the workspace. Handles skipping duplicates and
@@ -277,7 +284,7 @@ def save_action_result(
                 skipped_paths.append(store_path)
                 continue
 
-        ws.save(item)
+        ws.save(item, as_tmp=as_tmp, no_format=no_format)
 
     if skipped_paths:
         log.message(
@@ -308,9 +315,7 @@ def save_action_result(
 
 
 def run_action_with_caching(
-    context: ExecContext,
-    action_input: ActionInput,
-    rerun: bool = False,
+    context: ExecContext, action_input: ActionInput
 ) -> tuple[ActionResult, list[StorePath], list[StorePath]]:
     """
     Run an action, including validation, only rerunning if `rerun` requested or
@@ -328,15 +333,15 @@ def run_action_with_caching(
         item.context = context
 
     # Assemble the operation and validate the action input.
-    operation = validate_action_input(ws, action, action_input)
+    operation = validate_action_input(context, ws, action, action_input)
 
     # Log what we're about to run.
     log_action(action, action_input, operation)
 
     # Check if a previous run already produced the result.
-    existing_result = check_for_existing_result(context, action_input, operation, rerun=rerun)
+    existing_result = check_for_existing_result(context, action_input, operation)
 
-    if existing_result and not rerun:
+    if existing_result and not context.rerun:
         # Use the cached result.
         result = existing_result
         result_store_paths = [StorePath(not_none(item.store_path)) for item in result.items]
@@ -353,7 +358,9 @@ def run_action_with_caching(
     else:
         # Run it!
         result = run_action_operation(context, action_input, operation)
-        result_store_paths, archived_store_paths = save_action_result(ws, result, action_input)
+        result_store_paths, archived_store_paths = save_action_result(
+            ws, result, action_input, as_tmp=context.tmp_output, no_format=context.no_format
+        )
 
         PrintHooks.before_done_message()
         log.message(
@@ -371,9 +378,12 @@ def run_action_with_shell_context(
     action_spec: str | type[Action],
     explicit_param_values: RawParamValues,
     *provided_args: str,
-    rerun=False,
+    rerun: bool = False,
+    refetch: bool = False,
     override_state: State | None = None,
-    internal_call=False,
+    tmp_output: bool = False,
+    no_format: bool = False,
+    internal_call: bool = False,
 ) -> ActionResult:
     """
     Main function to run an action from the shell. Wraps `run_action_if_needed` to
@@ -404,8 +414,16 @@ def run_action_with_shell_context(
     action = action_cls.create(explicit_parsed, ws_parsed)
     action_name = action.name
 
-    # Execution context.
-    context = ExecContext(action, ws.base_dir, rerun, override_state)
+    # Execution context. This is fixed for the duration of the action.
+    context = ExecContext(
+        action=action,
+        workspace_dir=ws.base_dir,
+        rerun=rerun,
+        refetch=refetch,
+        override_state=override_state,
+        tmp_output=tmp_output,
+        no_format=no_format,
+    )
 
     # Collect args from the provided args or otherwise the current selection.
     args, from_selection = assemble_action_args(*provided_args, use_selection=action.uses_selection)
@@ -422,7 +440,7 @@ def run_action_with_shell_context(
         )
 
     # Get items for each input arg.
-    input = prepare_action_input(*args)
+    input = prepare_action_input(*args, refetch=refetch)
 
     # Finally, run the action.
     result, result_store_paths, archived_store_paths = run_action_with_caching(context, input)

kash/exec/action_registry.py

@@ -1,18 +1,14 @@
-from pathlib import Path
-
 from cachetools import Cache, cached
-from prettyfmt import fmt_lines, fmt_path
+from strif import AtomicVar
 
 from kash.config.logger import get_logger
 from kash.model.actions_model import Action
-from kash.utils.common.atomic_var import AtomicVar
-from kash.utils.common.import_utils import Tallies, import_subdirs
 from kash.utils.errors import InvalidInput
 
 log = get_logger(__name__)
 
 # Global registry of action classes.
-_action_classes: AtomicVar[dict[str, type[Action]]] = AtomicVar({})
+action_classes: AtomicVar[dict[str, type[Action]]] = AtomicVar({})
 
 
 # Want it fast to get the full list of actions (important for tab completions
@@ -30,64 +26,29 @@ def register_action_class(cls: type[Action]):
     """
     Register an action class.
     """
-    with _action_classes.updates() as action_classes:
-        if cls.name in action_classes:
+    with action_classes.updates() as ac:
+        if cls.name in ac:
             log.warning(
                 "Duplicate action name (defined twice by accident?): %s (%s)",
                 cls.name,
                 cls,
             )
-        action_classes[cls.name] = cls
+        ac[cls.name] = cls
 
         clear_action_cache()
 
 
-def import_action_subdirs(
-    subdirs: list[str],
-    package_name: str | None,
-    parent_dir: Path,
-    tallies: Tallies | None = None,
-):
-    """
-    Hook to call from `__init__.py` in a directory containing actions,
-    so that they are auto-registered on import.
-
-    Usage:
-    ```
-    import_action_subdirs(["subdir_name"], __package__, Path(__file__).parent)
-    ```
-    """
-    if tallies is None:
-        tallies = {}
-    with _action_classes.updates() as action_classes:
-        prev_count = len(action_classes)
-
-        if not package_name:
-            raise ValueError(f"Package name missing importing actions: {fmt_path(parent_dir)}")
-
-        import_subdirs(package_name, parent_dir, subdirs, tallies)
-        reload_all_action_classes()
-
-        log.info(
-            "Loaded actions: %s new actions in %s directories below %s:\n%s",
-            len(action_classes) - prev_count,
-            len(tallies),
-            fmt_path(parent_dir),
-            fmt_lines(f"{k}: {v} files" for k, v in tallies.items()),
-        )
-
-
 @cached(_action_classes_cache)
 def get_all_action_classes() -> dict[str, type[Action]]:
     # Be sure actions are imported.
     import kash.actions  # noqa: F401
 
     # Returns a copy for safety.
-    action_classes = _action_classes.copy()
-    if len(action_classes) == 0:
+    ac = action_classes.copy()
+    if len(ac) == 0:
         log.error("No actions found! Was there an import error?")
 
-    return dict(action_classes)
+    return dict(ac)
 
 
 def look_up_action_class(action_name: str) -> type[Action]:
@@ -97,7 +58,11 @@ def look_up_action_class(action_name: str) -> type[Action]:
     return actions[action_name]
 
 
-def reload_all_action_classes() -> dict[str, type[Action]]:
+def refresh_action_classes() -> dict[str, type[Action]]:
+    """
+    Reload all action classes, refreshing the cache. Call after registering
+    new action classes.
+    """
     clear_action_cache()
     return get_all_action_classes()
 

kash/exec/command_registry.py

@@ -1,9 +1,10 @@
 from collections.abc import Callable
 from typing import overload
 
+from strif import AtomicVar
+
 from kash.config.logger import get_logger
 from kash.exec_model.shell_model import ShellResult
-from kash.utils.common.atomic_var import AtomicVar
 from kash.utils.errors import InvalidInput
 
 log = get_logger(__name__)

kash/exec/fetch_url_metadata.py

@@ -13,9 +13,7 @@ from kash.workspaces import current_ws
 log = get_logger(__name__)
 
 
-def fetch_url_metadata(
-    locator: Url | StorePath, use_cache: bool = True, refetch: bool = False
-) -> Item:
+def fetch_url_metadata(locator: Url | StorePath, refetch: bool = False) -> Item:
     ws = current_ws()
     if is_url(locator):
         # Import or find URL as a resource in the current workspace.
@@ -28,10 +26,10 @@ def fetch_url_metadata(
     else:
         raise InvalidInput(f"Not a URL or URL resource: {fmt_loc(locator)}")
 
-    return fetch_url_item_metadata(item, use_cache=use_cache, refetch=refetch)
+    return fetch_url_item_metadata(item, refetch=refetch)
 
 
-def fetch_url_item_metadata(item: Item, use_cache: bool = True, refetch: bool = False) -> Item:
+def fetch_url_item_metadata(item: Item, refetch: bool = False) -> Item:
     """
     Fetch metadata for a URL using a media service if we recognize the URL,
     and otherwise fetching and extracting it from the web page HTML.
@@ -56,7 +54,7 @@ def fetch_url_item_metadata(item: Item, use_cache: bool = True, refetch: bool =
         fetched_item = Item.from_media_metadata(media_metadata)
         fetched_item = item.merged_copy(fetched_item)
     else:
-        page_data = fetch_extract(url, use_cache=use_cache)
+        page_data = fetch_extract(url, refetch=refetch)
         fetched_item = item.new_copy_with(
             title=page_data.title or item.title,
             description=page_data.description or item.description,

kash/exec/importing.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+
+from prettyfmt import fmt_lines, fmt_path
+
+from kash.config.logger import get_logger
+from kash.exec.action_registry import action_classes, refresh_action_classes
+from kash.exec.command_registry import get_all_commands
+from kash.utils.common.import_utils import Tallies, import_subdirs
+
+log = get_logger(__name__)
+
+
+def import_and_register(
+    package_name: str | None,
+    parent_dir: Path,
+    subdir_names: list[str] | None = None,
+    tallies: Tallies | None = None,
+):
+    """
+    This hook can be used for auto-registering commands and actions from any
+    subdirectory of a given package.
+
+    Useful to call from `__init__.py` files to import a directory of code,
+    auto-registering annotated commands and actions and also handles refreshing the
+    action cache if new actions are registered.
+
+    Usage:
+    ```
+    import_and_register(["subdir1", "subdir2"], __package__, Path(__file__).parent)
+    ```
+    """
+    if not package_name:
+        raise ValueError(f"Package name missing importing actions: {fmt_path(parent_dir)}")
+    if tallies is None:
+        tallies = {}
+
+    with action_classes.updates() as ac:
+        prev_command_count = len(get_all_commands())
+        prev_action_count = len(ac)
+
+        import_subdirs(package_name, parent_dir, subdir_names, tallies)
+
+        new_command_count = len(get_all_commands()) - prev_command_count
+        new_action_count = len(ac) - prev_action_count
+
+        if new_action_count > 0:
+            refresh_action_classes()
+
+        log.info(
+            "Loaded %s new commands and %s new actions in %s directories below %s:\n%s",
+            new_command_count,
+            new_action_count,
+            len(tallies),
+            fmt_path(parent_dir),
+            fmt_lines(f"{k}: {v} files" for k, v in tallies.items()),
+        )

kash/exec/llm_transforms.py

@@ -1,18 +1,19 @@
 from dataclasses import replace
 
 from chopdiff.docs import DiffFilter, TextDoc
-from chopdiff.transforms import WindowSettings, accept_all, filtered_transform
+from chopdiff.transforms import WindowSettings, filtered_transform
+from clideps.env_vars.dotenv_utils import load_dotenv_paths
 from flowmark import fill_markdown
 
 from kash.config.logger import get_logger
-from kash.config.settings import get_system_config_dir
+from kash.config.settings import global_settings
 from kash.llm_utils import LLMName
 from kash.llm_utils.fuzzy_parsing import strip_markdown_fence
 from kash.llm_utils.llm_completion import llm_template_completion
 from kash.llm_utils.llm_messages import Message, MessageTemplate
 from kash.model.actions_model import LLMOptions
-from kash.model.items_model import Item, ItemType
-from kash.shell.clideps.dotenv_utils import load_dotenv_paths
+from kash.model.items_model import Item
+from kash.text_handling.doc_normalization import normalize_formatting_ansi
 from kash.utils.errors import InvalidInput
 from kash.utils.file_utils.file_formats_model import Format
 
@@ -25,7 +26,7 @@ def windowed_llm_transform(
     template: MessageTemplate,
     input: str,
     windowing: WindowSettings | None,
-    diff_filter: DiffFilter,
+    diff_filter: DiffFilter | None = None,
     check_no_results: bool = True,
 ) -> TextDoc:
     def doc_transform(input_doc: TextDoc) -> TextDoc:
@@ -48,7 +49,7 @@ def windowed_llm_transform(
 
 
 def llm_transform_str(options: LLMOptions, input_str: str, check_no_results: bool = True) -> str:
-    load_dotenv_paths(True, True, get_system_config_dir())
+    load_dotenv_paths(True, True, global_settings().system_config_dir)
 
     if options.windowing and options.windowing.size:
         log.message(
@@ -57,7 +58,6 @@ def llm_transform_str(options: LLMOptions, input_str: str, check_no_results: boo
             options.op_name,
             options.windowing,
         )
-        diff_filter = options.diff_filter or accept_all
 
         result_str = windowed_llm_transform(
             options.model,
@@ -65,7 +65,7 @@ def llm_transform_str(options: LLMOptions, input_str: str, check_no_results: boo
             options.body_template,
             input_str,
             options.windowing,
-            diff_filter,
+            diff_filter=options.diff_filter,
         ).reassemble()
     else:
         log.message(
@@ -91,6 +91,7 @@ def llm_transform_item(
     normalize: bool = True,
     strip_fence: bool = True,
     check_no_results: bool = True,
+    format: Format | None = None,
 ) -> Item:
     """
     Main function for running an LLM action on an item.
@@ -111,12 +112,13 @@ def llm_transform_item(
     log.message("LLM transform from action `%s` on item: %s", action.name, item)
     log.message("LLM options: %s", action.llm_options)
 
-    result_item = item.derived_copy(type=ItemType.doc, body=None, format=Format.markdown)
+    format = format or item.format or Format.markdown
+    result_item = item.derived_copy(body=None, format=format)
     result_str = llm_transform_str(llm_options, item.body, check_no_results=check_no_results)
     if strip_fence:
         result_str = strip_markdown_fence(result_str)
     if normalize:
-        result_str = fill_markdown(result_str)
+        result_str = normalize_formatting_ansi(result_str, format=format)
 
     result_item.body = result_str
     return result_item

kash/exec/precondition_registry.py

@@ -1,9 +1,10 @@
 from collections.abc import Callable
 
+from strif import AtomicVar
+
 from kash.config.logger import get_logger
 from kash.model.items_model import Item
 from kash.model.preconditions_model import Precondition
-from kash.utils.common.atomic_var import AtomicVar
 
 log = get_logger(__name__)
 

kash/exec/preconditions.py

@@ -7,7 +7,8 @@ from chopdiff.html import has_timestamp
 
 from kash.exec.precondition_registry import kash_precondition
 from kash.model.items_model import Item, ItemType
-from kash.text_handling.markdown_util import extract_bullet_points
+from kash.text_handling.markdown_utils import extract_bullet_points
+from kash.utils.file_utils.file_formats import is_full_html_page
 from kash.utils.file_utils.file_formats_model import Format
 
 
@@ -16,6 +17,21 @@ def is_resource(item: Item) -> bool:
     return item.type == ItemType.resource
 
 
+@kash_precondition
+def is_doc_resource(item: Item) -> bool:
+    return bool(is_resource(item) and item.format and item.format.is_doc)
+
+
+@kash_precondition
+def is_html_resource(item: Item) -> bool:
+    return bool(is_resource(item) and item.format and item.format == Format.html)
+
+
+@kash_precondition
+def is_docx_resource(item: Item) -> bool:
+    return bool(is_resource(item) and item.format and item.format == Format.docx)
+
+
 @kash_precondition
 def is_concept(item: Item) -> bool:
     return item.type == ItemType.concept
@@ -78,6 +94,11 @@ def has_html_body(item: Item) -> bool:
     return has_body(item) and item.format in (Format.html, Format.md_html)
 
 
+@kash_precondition
+def has_full_html_page_body(item: Item) -> bool:
+    return bool(has_html_body(item) and item.body and is_full_html_page(item.body))
+
+
 @kash_precondition
 def is_plaintext(item: Item) -> bool:
     return has_body(item) and item.format == Format.plaintext

kash/exec/resolve_args.py

@@ -105,6 +105,10 @@ def assemble_action_args(
 
 
 def resolvable_paths(paths: Sequence[StorePath | Path]) -> list[StorePath]:
+    """
+    Return which of the given StorePaths are resolvable (exist) in the
+    current workspace.
+    """
     ws = current_ws()
     resolvable = list(filter(None, (ws.resolve_path(p) for p in paths)))
     return resolvable