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

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,17 +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 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
 
@@ -24,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:
@@ -47,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()
+    load_dotenv_paths(True, True, global_settings().system_config_dir)
 
     if options.windowing and options.windowing.size:
         log.message(
@@ -56,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,
@@ -64,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__)
 

kash/exec/preconditions.py

@@ -7,7 +7,7 @@ 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_model import Format
 
 
@@ -16,6 +16,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

kash/exec/shell_callable_action.py

@@ -1,5 +1,6 @@
 from funlog import log_tallies
 
+from kash.config.env_settings import KashEnv
 from kash.config.logger import get_console, get_logger
 from kash.config.text_styles import COLOR_ERROR, SPINNER
 from kash.exec.action_exec import run_action_with_shell_context
@@ -31,34 +32,43 @@ class ShellCallableAction:
     def __call__(self, args: list[str]) -> ShellResult | None:
         from kash.commands.help import help_commands
 
-        action_cls = self.action_cls
-        PrintHooks.before_shell_action_run()
+        log.debug("ShellCallableAction: %s: %s", self.action_cls.name, args)
 
-        shell_args = parse_shell_args(args)
-
-        # We will instantiate the action later but we create an unconfigured
-        # instance for help/info.
-        action = action_cls.create(None)
-        if shell_args.show_help:
-            print_action_help(action, verbose=True)
-            return ShellResult()
-        elif shell_args.options.get("show_source", False):
-            return help_commands.source_code(action_cls.name)
-
-        # Handle --rerun option at action invocation time.
-        rerun = bool(shell_args.options.get("rerun", False))
-
-        log.info("Action shell args: %s", shell_args)
         try:
+            action_cls = self.action_cls
+            PrintHooks.before_shell_action_run()
+
+            shell_args = parse_shell_args(args)
+
+            # We will instantiate the action later but we create an unconfigured
+            # instance for help/info.
+            action = action_cls.create(None)
+            if shell_args.show_help:
+                print_action_help(action, verbose=True)
+                return ShellResult()
+            elif shell_args.options.get("show_source", False):
+                return help_commands.source_code(action_cls.name)
+
+            # Handle --rerun and --refetch options at action invocation time.
+            rerun = bool(shell_args.options.get("rerun", False))
+            refetch = bool(shell_args.options.get("refetch", False))
+            no_format = bool(shell_args.options.get("no_format", False))
+
+            log.info("Action shell args: %s", shell_args)
             explicit_values = RawParamValues(shell_args.options)
             if not action.interactive_input:
                 with get_console().status(f"Running action {action.name}…", spinner=SPINNER):
                     result = run_action_with_shell_context(
-                        action_cls, explicit_values, *shell_args.args, rerun=rerun
+                        action_cls,
+                        explicit_values,
+                        *shell_args.args,
+                        rerun=rerun,
+                        refetch=refetch,
+                        no_format=no_format,
                     )
             else:
                 result = run_action_with_shell_context(
-                    action_cls, explicit_values, *shell_args.args, rerun=rerun
+                    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:
@@ -66,6 +76,10 @@ class ShellCallableAction:
             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))
+            raise
         finally:
             log_tallies(level="warning", if_slower_than=10.0)
             # output_separator()

kash/file_storage/file_store.py

@@ -97,10 +97,6 @@ class FileStore(Workspace):
 
         add_to_ignore(self.base_dir / ".gitignore", [".kash/"])
 
-        self.vector_index = None
-        # FIXME: Add vector index support dynamically if available.
-        # self.vector_index = WsVectorIndex(self.base_dir / self.dirs.index_dir)
-
         # Initialize selection with history support.
         self.selections = SelectionHistory.init(self.base_dir / self.dirs.selection_yml)
 
@@ -274,10 +270,10 @@ class FileStore(Workspace):
             return self._tmp_path_for(item), False, None
         elif item.store_path:
             return StorePath(item.store_path), True, None
-        elif item_id in self.id_map:
+        elif item_id in self.id_map and self.exists(self.id_map[item_id]):
             # If this item has an identity and we've saved under that id before, use the same store path.
             store_path = self.id_map[item_id]
-            log.info(
+            log.warning(
                 "Found existing item with same id:\n%s",
                 fmt_lines([fmt_loc(store_path), item_id]),
             )
@@ -313,10 +309,16 @@ class FileStore(Workspace):
         )
 
     @log_calls()
-    def save(self, item: Item, as_tmp: bool = False, overwrite: bool = True) -> StorePath:
+    def save(
+        self, item: Item, *, overwrite: bool = True, as_tmp: bool = False, no_format: bool = False
+    ) -> StorePath:
         """
-        Save the item. Uses the store_path if it's already set or generates a new one.
-        Updates item.store_path.
+        Save the item. Uses the `store_path` if it's already set or generates a new one.
+        Updates `item.store_path`.
+
+        If `as_tmp` is true, will save the item to a temporary file.
+        If `overwrite` is false, will skip saving if the item already exists.
+        If `no_format` is true, will not normalize body text formatting (for Markdown).
         """
         # If external file already exists within the workspace, the file is already saved (without metadata).
         external_path = item.external_path and Path(item.external_path).resolve()
@@ -352,7 +354,7 @@ class FileStore(Workspace):
                 if item.external_path:
                     copyfile_atomic(item.external_path, full_path)
                 else:
-                    write_item(item, full_path)
+                    write_item(item, full_path, normalize=not no_format)
             except OSError as e:
                 log.error("Error saving item: %s", e)
                 try:
@@ -402,6 +404,7 @@ class FileStore(Workspace):
     def import_item(
         self,
         locator: Locator,
+        *,
         as_type: ItemType | None = None,
         reimport: bool = False,
     ) -> StorePath:
@@ -500,7 +503,9 @@ class FileStore(Workspace):
         as_type: ItemType | None = None,
         reimport: bool = False,
     ) -> list[StorePath]:
-        return [self.import_item(locator, as_type, reimport) for locator in locators]
+        return [
+            self.import_item(locator, as_type=as_type, reimport=reimport) for locator in locators
+        ]
 
     def _filter_selection_paths(self):
         """
@@ -541,7 +546,7 @@ class FileStore(Workspace):
         # TODO: Update metadata of all relations that point to this path too.
 
     def archive(
-        self, store_path: StorePath, missing_ok: bool = False, quiet: bool = False
+        self, store_path: StorePath, *, missing_ok: bool = False, quiet: bool = False
     ) -> StorePath:
         """
         Archive the item by moving it into the archive directory.
@@ -557,6 +562,9 @@ class FileStore(Workspace):
         if missing_ok and not orig_path.exists():
             log.message("Item to archive not found so moving on: %s", fmt_loc(orig_path))
             return store_path
+        if not orig_path.exists():
+            log.warning("Item to archive not found: %s", fmt_loc(orig_path))
+            return store_path
         move_file(orig_path, archive_path)
         self._remove_references([store_path])
 
@@ -576,7 +584,7 @@ class FileStore(Workspace):
         move_file(full_input_path, original_path)
         return StorePath(store_path)
 
-    def log_workspace_info(self, once: bool = False):
+    def log_workspace_info(self, *, once: bool = False):
         """
         Log helpful information about the workspace.
         """
@@ -607,7 +615,7 @@ class FileStore(Workspace):
 
         if self.is_global_ws:
             PrintHooks.spacer()
-            log.warning("Note you are currently using the default `global` workspace.")
+            log.warning("Note you are currently using the default global workspace.")
             cprint(
                 "Create or switch to another workspace with the `workspace` command.",
                 style=STYLE_HINT,
@@ -619,6 +627,7 @@ class FileStore(Workspace):
     def walk_items(
         self,
         store_path: StorePath | None = None,
+        *,
         use_ignore: bool = True,
     ) -> Generator[StorePath, None, None]:
         """