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

kash/exec/action_exec.py

@@ -1,11 +1,16 @@
 import time
 from dataclasses import replace
 
-from prettyfmt import fmt_lines
+from prettyfmt import fmt_lines, plural
 
 from kash.config.logger import get_logger
-from kash.config.text_styles import EMOJI_SKIP, EMOJI_SUCCESS, EMOJI_TIMING
-from kash.exec.preconditions import is_url_item
+from kash.config.text_styles import (
+    EMOJI_SKIP,
+    EMOJI_START,
+    EMOJI_SUCCESS,
+    EMOJI_TIMING,
+)
+from kash.exec.preconditions import is_url_resource
 from kash.exec.resolve_args import assemble_action_args
 from kash.exec_model.args_model import CommandArg
 from kash.file_storage.file_store import FileStore
@@ -17,15 +22,15 @@ from kash.model.actions_model import (
     ExecContext,
     PathOpType,
 )
+from kash.model.exec_model import RuntimeSettings
 from kash.model.items_model import Item, State
 from kash.model.operations_model import Input, Operation, Source
 from kash.model.params_model import ALL_COMMON_PARAMS, GLOBAL_PARAMS, RawParamValues
 from kash.model.paths_model import StorePath
-from kash.shell.output.shell_output import PrintHooks, print_h3
+from kash.shell.output.shell_output import PrintHooks
 from kash.utils.common.task_stack import task_stack
 from kash.utils.common.type_utils import not_none
-from kash.utils.errors import NONFATAL_EXCEPTIONS, ContentError, InvalidOutput
-from kash.utils.lang_utils.inflection import plural
+from kash.utils.errors import ContentError, InvalidOutput, get_nonfatal_exceptions
 from kash.workspaces import Selection, current_ws
 from kash.workspaces.workspace_importing import import_and_load
 
@@ -50,7 +55,7 @@ def prepare_action_input(*input_args: CommandArg, refetch: bool = False) -> Acti
     if input_items:
         log.message("Assembling metadata for input items:\n%s", fmt_lines(input_items))
         input_items = [
-            fetch_url_item_metadata(item, refetch=refetch) if is_url_item(item) else item
+            fetch_url_item_metadata(item, refetch=refetch) if is_url_resource(item) else item
             for item in input_items
         ]
 
@@ -63,6 +68,7 @@ def validate_action_input(
     """
     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.
+    For flexibility, we don't require the items to be saved (have a store path).
     """
     input_items = action_input.items
     # Validations:
@@ -75,10 +81,16 @@ def validate_action_input(
 
     # Now make a note of the the operation we will perform.
     # 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]
+    def input_for(item: Item) -> Input:
+        if item.store_path:
+            return Input(StorePath(item.store_path), ws.hash(StorePath(item.store_path)))
+        else:
+            return Input(path=None, source_info="unsaved")
+
+    inputs = [input_for(item) for item in input_items]
+
     # Add any non-default runtime options into the options summary.
-    options = {**action.param_value_summary(), **context.runtime_options}
+    options = {**action.param_value_summary(), **context.settings.non_default_options}
     operation = Operation(action.name, inputs, options)
 
     return operation
@@ -89,7 +101,7 @@ def log_action(action: Action, action_input: ActionInput, operation: Operation):
     Log the action and the operation we are about to run.
     """
     PrintHooks.before_log_action_run()
-    print_h3(f"Action `{action.name}`")
+    log.message("%s Action: `%s`", EMOJI_START, action.name)
     log.message("Running: `%s`", operation.command_line(with_options=True))
     if len(action.param_value_summary()) > 0:
         log.message("Parameters:\n%s", action.param_value_summary_str())
@@ -106,8 +118,9 @@ def check_for_existing_result(
     already exist.
     """
     action = context.action
-    ws = context.workspace
-    rerun = context.rerun
+    settings = context.settings
+    ws = settings.workspace
+    rerun = settings.rerun
 
     existing_result = None
 
@@ -154,6 +167,7 @@ def run_action_operation(
 
     # Run the action.
     action = context.action
+    settings = context.settings
     if action.run_per_item:
         result = _run_for_each_item(context, action_input)
     else:
@@ -172,9 +186,9 @@ def run_action_operation(
         item.update_history(Source(operation=this_op, output_num=i, cacheable=action.cacheable))
 
     # Override the state if appropriate (this handles marking items as transient).
-    if context.override_state:
+    if settings.override_state:
         for item in result.items:
-            item.state = context.override_state
+            item.state = settings.override_state
 
     log.info("Action `%s` result: %s", action.name, result)
 
@@ -233,7 +247,7 @@ def _run_for_each_item(context: ExecContext, input: ActionInput) -> ActionResult
                 log.info("Caught SkipItem exception, skipping run on this item")
                 result_items.append(item)
                 continue
-            except NONFATAL_EXCEPTIONS as e:
+            except get_nonfatal_exceptions() as e:
                 errors.append(e)
                 had_error = True
 
@@ -284,7 +298,7 @@ def save_action_result(
                 skipped_paths.append(store_path)
                 continue
 
-        ws.save(item, as_tmp=as_tmp, no_format=no_format)
+        ws.save(item, overwrite=result.overwrite, as_tmp=as_tmp, no_format=no_format)
 
     if skipped_paths:
         log.message(
@@ -293,14 +307,18 @@ def save_action_result(
             fmt_lines(skipped_paths),
         )
 
-    input_store_paths = [StorePath(not_none(item.store_path)) for item in input_items]
+    unsaved_items = [item for item in input_items if not item.store_path]
+    input_store_paths = [StorePath(item.store_path) for item in input_items if item.store_path]
     result_store_paths = [StorePath(item.store_path) for item in result.items if item.store_path]
     old_inputs = sorted(set(input_store_paths) - set(result_store_paths))
+    if unsaved_items:
+        log.info("unsaved_items:\n%s", fmt_lines(unsaved_items))
     log.info("result_store_paths:\n%s", fmt_lines(result_store_paths))
-    log.info("old_inputs:\n%s", fmt_lines(old_inputs))
+    if old_inputs:
+        log.info("old_inputs:\n%s", fmt_lines(old_inputs))
 
     # If there is a hint that the action replaces the input, archive any inputs that are not in the result.
-    archived_store_paths = []
+    archived_store_paths: list[StorePath] = []
     if result.replaces_input and input_items:
         for input_store_path in old_inputs:
             # Note some outputs may be missing if replace_input was used.
@@ -325,7 +343,8 @@ def run_action_with_caching(
     Note: Mutates the input but only to add `context` to each item.
     """
     action = context.action
-    ws = context.workspace
+    settings = context.settings
+    ws = settings.workspace
 
     # For convenience, we include the context to each item too (this helps so per-item
     # functions don't have to take context args everywhere).
@@ -341,7 +360,7 @@ def run_action_with_caching(
     # Check if a previous run already produced the result.
     existing_result = check_for_existing_result(context, action_input, operation)
 
-    if existing_result and not context.rerun:
+    if existing_result and not settings.rerun:
         # Use the cached result.
         result = existing_result
         result_store_paths = [StorePath(not_none(item.store_path)) for item in result.items]
@@ -349,7 +368,7 @@ def run_action_with_caching(
 
         PrintHooks.before_done_message()
         log.message(
-            "%s Action skipped: `%s` completed with %s %s",
+            "%s Skipped: `%s` completed with %s %s",
             EMOJI_SKIP,
             action.name,
             len(result.items),
@@ -359,12 +378,12 @@ def run_action_with_caching(
         # Run it!
         result = run_action_operation(context, action_input, operation)
         result_store_paths, archived_store_paths = save_action_result(
-            ws, result, action_input, as_tmp=context.tmp_output, no_format=context.no_format
+            ws, result, action_input, as_tmp=settings.tmp_output, no_format=settings.no_format
         )
 
         PrintHooks.before_done_message()
         log.message(
-            "%s Action done: `%s` completed with %s %s",
+            "%s Done: `%s` completed with %s %s",
             EMOJI_SUCCESS,
             action.name,
             len(result.items),
@@ -415,8 +434,7 @@ def run_action_with_shell_context(
     action_name = action.name
 
     # Execution context. This is fixed for the duration of the action.
-    context = ExecContext(
-        action=action,
+    settings = RuntimeSettings(
         workspace_dir=ws.base_dir,
         rerun=rerun,
         refetch=refetch,
@@ -424,6 +442,7 @@ def run_action_with_shell_context(
         tmp_output=tmp_output,
         no_format=no_format,
     )
+    context = ExecContext(action, settings)
 
     # Collect args from the provided args or otherwise the current selection.
     args, from_selection = assemble_action_args(*provided_args, use_selection=action.uses_selection)

kash/exec/fetch_url_metadata.py

@@ -1,19 +1,18 @@
 from kash.config.logger import get_logger
-from kash.exec.preconditions import is_url_item
+from kash.exec.preconditions import is_url_resource
 from kash.media_base.media_services import get_media_metadata
 from kash.model.items_model import Item, ItemType
 from kash.model.paths_model import StorePath
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.common.url import Url, is_url
 from kash.utils.errors import InvalidInput
-from kash.web_content.canon_url import canonicalize_url
-from kash.web_content.web_extract import fetch_extract
-from kash.workspaces import current_ws
 
 log = get_logger(__name__)
 
 
 def fetch_url_metadata(locator: Url | StorePath, refetch: bool = False) -> Item:
+    from kash.workspaces import current_ws
+
     ws = current_ws()
     if is_url(locator):
         # Import or find URL as a resource in the current workspace.
@@ -21,7 +20,7 @@ def fetch_url_metadata(locator: Url | StorePath, refetch: bool = False) -> Item:
         item = ws.load(store_path)
     elif isinstance(locator, StorePath):
         item = ws.load(locator)
-        if not is_url_item(item):
+        if not is_url_resource(item):
             raise InvalidInput(f"Not a URL resource: {fmt_loc(locator)}")
     else:
         raise InvalidInput(f"Not a URL or URL resource: {fmt_loc(locator)}")
@@ -34,6 +33,10 @@ 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.
     """
+    from kash.web_content.canon_url import canonicalize_url
+    from kash.web_content.web_extract import fetch_extract
+    from kash.workspaces import current_ws
+
     ws = current_ws()
     if not refetch and item.title and item.description:
         log.message(

kash/exec/importing.py

@@ -5,7 +5,7 @@ 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
+from kash.utils.common.import_utils import Tallies, import_recursive
 
 log = get_logger(__name__)
 
@@ -13,12 +13,12 @@ log = get_logger(__name__)
 def import_and_register(
     package_name: str | None,
     parent_dir: Path,
-    subdir_names: list[str] | None = None,
+    resource_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.
+    module or 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
@@ -38,7 +38,7 @@ def import_and_register(
         prev_command_count = len(get_all_commands())
         prev_action_count = len(ac)
 
-        import_subdirs(package_name, parent_dir, subdir_names, tallies)
+        import_recursive(package_name, parent_dir, resource_names, tallies)
 
         new_command_count = len(get_all_commands()) - prev_command_count
         new_action_count = len(ac) - prev_action_count

kash/exec/llm_transforms.py

@@ -13,9 +13,9 @@ 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
-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
+from kash.utils.text_handling.doc_normalization import normalize_formatting
 
 log = get_logger(__name__)
 
@@ -118,7 +118,7 @@ def llm_transform_item(
     if strip_fence:
         result_str = strip_markdown_fence(result_str)
     if normalize:
-        result_str = normalize_formatting_ansi(result_str, format=format)
+        result_str = normalize_formatting(result_str, format=format)
 
     result_item.body = result_str
     return result_item

kash/exec/preconditions.py

@@ -7,9 +7,9 @@ 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_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
+from kash.utils.text_handling.markdown_utils import extract_bullet_points
 
 
 @kash_precondition
@@ -32,6 +32,11 @@ def is_docx_resource(item: Item) -> bool:
     return bool(is_resource(item) and item.format and item.format == Format.docx)
 
 
+@kash_precondition
+def is_pdf_resource(item: Item) -> bool:
+    return bool(is_resource(item) and item.format and item.format == Format.pdf)
+
+
 @kash_precondition
 def is_concept(item: Item) -> bool:
     return item.type == ItemType.concept
@@ -53,7 +58,7 @@ def is_instructions(item: Item) -> bool:
 
 
 @kash_precondition
-def is_url_item(item: Item) -> bool:
+def is_url_resource(item: Item) -> bool:
     return bool(item.type == ItemType.resource and item.url)
 
 
@@ -85,13 +90,13 @@ def contains_curly_vars(item: Item) -> bool:
 
 
 @kash_precondition
-def has_text_body(item: Item) -> bool:
-    return has_body(item) and item.format in (Format.plaintext, Format.markdown, Format.md_html)
+def has_simple_text_body(item: Item) -> bool:
+    return bool(has_body(item) and item.format and item.format.is_simple_text)
 
 
 @kash_precondition
 def has_html_body(item: Item) -> bool:
-    return has_body(item) and item.format in (Format.html, Format.md_html)
+    return bool(has_body(item) and item.format and item.format.is_html)
 
 
 @kash_precondition
@@ -106,7 +111,7 @@ def is_plaintext(item: Item) -> bool:
 
 @kash_precondition
 def is_markdown(item: Item) -> bool:
-    return has_body(item) and item.format in (Format.markdown, Format.md_html)
+    return bool(has_body(item) and item.format and item.format.is_markdown)
 
 
 @kash_precondition
@@ -114,19 +119,6 @@ def is_markdown_template(item: Item) -> bool:
     return is_markdown(item) and contains_curly_vars(item)
 
 
-@kash_precondition
-def is_html(item: Item) -> bool:
-    return has_body(item) and item.format == Format.html
-
-
-@kash_precondition
-def is_text_doc(item: Item) -> bool:
-    """
-    A document that can be processed by LLMs and other plaintext tools.
-    """
-    return (is_plaintext(item) or is_markdown(item)) and has_body(item)
-
-
 @kash_precondition
 def is_markdown_list(item: Item) -> bool:
     try:

kash/exec/runtime_settings.py

@@ -0,0 +1,134 @@
+import contextvars
+from dataclasses import dataclass
+from pathlib import Path
+
+from kash.config.logger import get_logger
+from kash.model.exec_model import RuntimeSettings
+from kash.model.items_model import State
+from kash.workspaces.workspace_dirs import enclosing_ws_dir, global_ws_dir
+
+log = get_logger(__name__)
+
+_current_settings: contextvars.ContextVar[RuntimeSettings | None] = contextvars.ContextVar(
+    "current_runtime_settings", default=None
+)
+"""
+Context variable that tracks the current runtime settings. Only used if it is
+explicitly set with a `with runtime_settings(...):` block.
+"""
+
+
+def current_runtime_settings() -> RuntimeSettings:
+    """
+    Get the current runtime settings. Uses the ambient context var settings if
+    set and otherwise infers the workspace from the current working directory
+    with default runtime settings.
+    """
+
+    ambient_settings = _current_settings.get()
+    if ambient_settings:
+        return ambient_settings
+
+    default_ws_dir = enclosing_ws_dir() or global_ws_dir()
+    return RuntimeSettings(default_ws_dir)
+
+
+@dataclass(frozen=True)
+class WsContext:
+    global_ws_dir: Path
+    enclosing_ws_dir: Path | None
+    override_dir: Path | None
+
+    @property
+    def current_ws_dir(self) -> Path:
+        if self.override_dir:
+            return self.override_dir
+        elif self.enclosing_ws_dir:
+            return self.enclosing_ws_dir
+        else:
+            return self.global_ws_dir
+
+
+def current_ws_context() -> WsContext:
+    """
+    Context path info about the current workspace, including the global workspace
+    directory, any workspace directory that encloses the current working directory,
+    and override set via runtime settings.
+    """
+
+    override_dir = None
+    ambient_settings = _current_settings.get()
+    if ambient_settings:
+        override_dir = ambient_settings.workspace_dir
+
+    return WsContext(global_ws_dir(), enclosing_ws_dir(), override_dir)
+
+
+@dataclass
+class RuntimeSettingsManager:
+    """
+    Manage the context for executing actions, including `RuntimeSettings` and
+    `Workspace`.
+
+    This is a minimal base class for use as a context manager. Most functionality
+    is still in `FileStore`.
+
+    Workspaces may be detected based on the current working directory or explicitly
+    set using a `with` block:
+    ```
+    ws = get_ws("my_workspace")
+    with ws:
+        # code that calls current_ws() will use this workspace
+    ```
+    """
+
+    settings: RuntimeSettings
+
+    def __enter__(self):
+        self._token = _current_settings.set(self.settings)
+        log.info("New runtime context: %s", self.settings)
+        return self.settings
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        _current_settings.reset(self._token)
+        log.info("Exiting runtime context: %s", self.settings)
+
+
+def kash_runtime(
+    workspace_dir: Path | None,
+    *,
+    rerun: bool = False,
+    refetch: bool = False,
+    override_state: State | None = None,
+    tmp_output: bool = False,
+    no_format: bool = False,
+) -> RuntimeSettingsManager:
+    """
+    Set a specific kash execution context for a with block.
+    This allows defining a workspace and other execution settings as the ambient
+    context within the block.
+
+    If `workspace_dir` is not provided, the current workspace will be inferred
+    from the working directory or fall back to the global workspace.
+
+    Example usage:
+    ```
+    with kash_runtime(ws_path, rerun=args.rerun) as runtime:
+        runtime.workspace.log_workspace_info()
+        # Perform actions.
+    ```
+    """
+    from kash.workspaces.workspaces import current_ws
+
+    if workspace_dir is None:
+        workspace_dir = current_ws().base_dir
+
+    settings = RuntimeSettings(
+        workspace_dir=workspace_dir,
+        rerun=rerun,
+        refetch=refetch,
+        override_state=override_state,
+        tmp_output=tmp_output,
+        no_format=no_format,
+    )
+    return RuntimeSettingsManager(settings=settings)

kash/exec/shell_callable_action.py

@@ -13,7 +13,7 @@ from kash.model.params_model import RawParamValues
 from kash.shell.output.shell_output import PrintHooks
 from kash.shell.utils.exception_printing import summarize_traceback
 from kash.utils.common.parse_shell_args import parse_shell_args
-from kash.utils.errors import NONFATAL_EXCEPTIONS
+from kash.utils.errors import get_nonfatal_exceptions
 
 log = get_logger(__name__)
 
@@ -71,14 +71,16 @@ class ShellCallableAction:
                     action_cls, explicit_values, *shell_args.args, rerun=rerun, refetch=refetch
                 )
             # We don't return the result to keep the xonsh shell output clean.
-        except NONFATAL_EXCEPTIONS as e:
+        except get_nonfatal_exceptions() as e:
             PrintHooks.nonfatal_exception()
             log.error(f"[{COLOR_ERROR}]Action error:[/{COLOR_ERROR}] %s", summarize_traceback(e))
             log.info("Action error details: %s", e, exc_info=True)
             return ShellResult(exception=e)
         except Exception as e:
             # Log here while we are in the true call stack (not inside the xonsh call stack).
-            log.error("Action error: %s", e, exc_info=KashEnv.KASH_SHOW_TRACEBACK.read_bool(True))
+            log.error(
+                "Action error: %s", e, exc_info=KashEnv.KASH_SHOW_TRACEBACK.read_bool(default=True)
+            )
             raise
         finally:
             log_tallies(level="warning", if_slower_than=10.0)