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

kash/config/setup.py

@@ -3,34 +3,50 @@ from functools import cache
 from pathlib import Path
 from typing import Any
 
+from clideps.env_vars.dotenv_utils import load_dotenv_paths
+
+from kash.config.logger import reset_rich_logging
 from kash.config.logger_basic import basic_logging_setup
-from kash.config.settings import LogLevel, get_system_config_dir
+from kash.config.settings import LogLevel, configure_ws_and_settings, global_settings
 
 
 @cache
-def setup(rich_logging: bool, file_log_path: Path | None = None, level: LogLevel = LogLevel.info):
+def kash_setup(
+    *,
+    rich_logging: bool,
+    kash_ws_root: Path | None = None,
+    log_path: Path | None = None,
+    level: LogLevel = LogLevel.info,
+):
     """
     One-time top-level setup of essential logging, keys, directories, and configs.
     Idempotent.
 
-    If rich_logging is True, then rich logging with warnings only for console use.
-    If rich_logging is False, then use basic logging to a file and stderr.
+    Can call this if embedding kash in another app.
+    Can be used to set the global default workspace and logs directory
+    and/or the default log file.
+    If `rich_logging` is True, then rich logging with warnings only for console use.
+    If `rich_logging` is False, then use basic logging to a file and stderr.
     """
-    from kash.config.logger import reload_rich_logging_setup
-    from kash.shell.clideps.dotenv_utils import load_dotenv_paths
     from kash.utils.common.stack_traces import add_stacktrace_handler
 
+    add_stacktrace_handler()
+
+    # Settings may depend on environment variables, so load them first.
+    load_dotenv_paths(True, True, global_settings().system_config_dir)
+
+    # Then configure the workspace and settings before finalizing logging.
+    if kash_ws_root:
+        configure_ws_and_settings(kash_ws_root)
+
+    # Now set up logging, as it might depend on workspace root.
     if rich_logging:
-        reload_rich_logging_setup()
+        reset_rich_logging(log_path=log_path)
     else:
-        basic_logging_setup(file_log_path=file_log_path, level=level)
+        basic_logging_setup(log_path=log_path, level=level)
 
     _lib_setup()
 
-    add_stacktrace_handler()
-
-    load_dotenv_paths(True, True, get_system_config_dir())
-
 
 def _lib_setup():
     from frontmatter_format.yaml_util import add_default_yaml_customizer

kash/config/text_styles.py

@@ -46,7 +46,9 @@ SPINNER = "dots12"
 
 BAT_THEME = "Coldark-Dark"
 
-BAT_STYLE = "header-filename,header-filesize,grid,changes"
+BAT_STYLE = "header-filename,header-filesize,grid,numbers,changes"
+
+BAT_STYLE_PLAIN = "plain"
 
 
 ## Colors
@@ -296,18 +298,6 @@ EMOJI_MSG_INDENT = "⋮"
 
 EMOJI_BREADCRUMB_SEP = "›"
 
-EMOJI_TRUE = "✔︎"
-
-EMOJI_FALSE = "✘"
-
-
-def success_emoji(value: bool, success_only: bool = False) -> str:
-    return EMOJI_TRUE if value else " " if success_only else EMOJI_FALSE
-
-
-def format_success_emoji(value: bool, success_only: bool = False) -> Text:
-    return Text(success_emoji(value, success_only), style=COLOR_SUCCESS if value else COLOR_FAILURE)
-
 
 ## Special headings
 

kash/docs/load_api_docs.py

@@ -1,7 +1,8 @@
+from strif import StringTemplate
+
 from kash.config.logger import get_logger
 from kash.docs.load_help_topics import load_help_src
 from kash.docs.load_source_code import load_source_code
-from kash.utils.common.string_template import StringTemplate
 
 log = get_logger(__name__)
 

kash/docs/markdown/topics/a3_getting_started.md

@@ -243,8 +243,9 @@ A few of the most important commands for managing files and work are these:
   browser to view it.
 
 - `workspace` shows or selects or creates a new workspace.
-  Initially you work in the `global` workspace but for more real work you'll want to
-  create a workspace, which is a directory to hold the files you are working with.
+  Initially you work in the default global workspace (typically at `~/Kash/workspace`)
+  but for more real work you'll want to create a workspace, which is a directory to hold
+  the files you are working with.
 
 - `select` shows or sets selections, which are the set of files the next command will
   run on, within the current workspace.

kash/{concepts → embeddings}/text_similarity.py

@@ -5,9 +5,9 @@ from funlog import log_calls
 from litellm import embedding
 from litellm.types.utils import EmbeddingResponse
 
-from kash.concepts.cosine import ArrayLike, cosine
-from kash.concepts.embeddings import Embeddings
 from kash.config.logger import get_logger
+from kash.embeddings.cosine import ArrayLike, cosine
+from kash.embeddings.embeddings import Embeddings
 from kash.llm_utils.llms import DEFAULT_EMBEDDING_MODEL, EmbeddingModel
 from kash.utils.errors import ApiResultError
 

kash/exec/__init__.py

@@ -1,9 +1,7 @@
-# flake8: noqa: F401
-
 from kash.exec.action_decorators import kash_action, kash_action_class
 from kash.exec.action_exec import SkipItem, prepare_action_input, run_action_with_shell_context
-from kash.exec.action_registry import import_action_subdirs
 from kash.exec.command_registry import kash_command
+from kash.exec.importing import import_and_register
 from kash.exec.llm_transforms import llm_transform_item, llm_transform_str
 from kash.exec.precondition_registry import kash_precondition
 from kash.exec.resolve_args import (
@@ -14,3 +12,22 @@ from kash.exec.resolve_args import (
     resolve_locator_arg,
     resolve_path_arg,
 )
+
+__all__ = [
+    "kash_action",
+    "kash_action_class",
+    "SkipItem",
+    "prepare_action_input",
+    "run_action_with_shell_context",
+    "kash_command",
+    "import_and_register",
+    "llm_transform_item",
+    "llm_transform_str",
+    "kash_precondition",
+    "assemble_path_args",
+    "assemble_store_path_args",
+    "import_locator_args",
+    "resolvable_paths",
+    "resolve_locator_arg",
+    "resolve_path_arg",
+]

kash/exec/action_decorators.py

@@ -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
@@ -333,8 +338,11 @@ def kash_action(
                     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,18 @@
 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.utils.errors import InvalidInput
 from kash.utils.file_utils.file_formats_model import Format
 
@@ -25,7 +25,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 +48,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 +57,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 +64,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(

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__)