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

kash/utils/common/function_inspect.py

@@ -2,111 +2,172 @@ import inspect
 import types
 from collections.abc import Callable
 from dataclasses import dataclass
+from enum import Enum
 from inspect import Parameter
-from typing import Any, Union, cast, get_args, get_origin  # pyright: ignore
+from typing import Any, Union, cast, get_args, get_origin  # pyright: ignore[reportDeprecated]
 
-NO_DEFAULT = Parameter.empty
+NO_DEFAULT = Parameter.empty  # Alias for clarity
+
+ParameterKind = Parameter.POSITIONAL_ONLY.__class__
 
 
 @dataclass(frozen=True)
 class FuncParam:
+    """
+    Hold structured information about a single function parameter.
+    """
+
     name: str
-    type: type | None
-    default: Any
-    position: int | None
-    is_varargs: bool
+    kind: ParameterKind  # e.g., POSITIONAL_OR_KEYWORD
+    annotation: Any  # The raw type annotation (can be Parameter.empty)
+    default: Any  # The raw default value (can be Parameter.empty)
+    position: int | None  # Position index for positional args, None for keyword-only
 
-    @property
-    def is_positional(self) -> bool:
-        """Is this a purely positional parameter, with no default value?"""
-        return self.position is not None and not self.has_default
+    # Resolved type information
+    # This is the concrete, simplified main type (e.g., str from str | None, list from list[int])
+    effective_type: type | None
+    inner_type: type | None  # For collections, the type of elements (e.g., str from list[str])
+    is_explicitly_optional: bool  # True if original annotation was Optional[X] or X | None
 
     @property
     def has_default(self) -> bool:
         """Does this parameter have a default value?"""
         return self.default != NO_DEFAULT
 
+    @property
+    def is_pure_positional(self) -> bool:
+        """Is this a plain or varargs positional parameter, with no default value?"""
+        return self.position is not None and not self.has_default
+
+    @property
+    def is_positional_only(self) -> bool:
+        """Is a true positional parameter, with no default value."""
+        return self.kind == Parameter.POSITIONAL_ONLY
 
-def inspect_function_params(func: Callable[..., Any], unwrap: bool = True) -> list[FuncParam]:
+    @property
+    def is_positional_or_keyword(self) -> bool:
+        return self.kind == Parameter.POSITIONAL_OR_KEYWORD
+
+    @property
+    def is_varargs(self) -> bool:
+        return self.kind == Parameter.VAR_POSITIONAL or self.kind == Parameter.VAR_KEYWORD
+
+    @property
+    def is_keyword_only(self) -> bool:
+        return self.kind == Parameter.KEYWORD_ONLY
+
+
+def _resolve_type_details(annotation: Any) -> tuple[type | None, type | None, bool]:
     """
-    Get names and types of parameters on a Python function. Just a convenience wrapper
-    around `inspect.signature` to give parameter names, types, and default values.
-
-    It also parses `Optional` types to return the underlying type and unwraps
-    decorated functions to get the underlying parameters. Returns a list of
-    `FuncParam` values.
-
-    Note that technically, parameters are of 5 types, positional-only,
-    positional-or-keyword, keyword-only, varargs, or varargs-keyword, which is what
-    `inspect` tells you, but in practice you typically just want to know
-    `FuncParam.is_positional()`, i.e. if it is a pure positional parameter (no default)
-    and not a keyword (with a default).
+    Resolves an annotation into (effective_type, inner_type, is_explicitly_optional).
+
+    - effective_type: The main type (e.g., str from Optional[str], list from list[int]).
+    - inner_type: The type of elements if effective_type is a collection
+                  (e.g., int from list[int]). For non-collection or unparameterized
+                  collection, this is None.
+    - is_explicitly_optional: True if the annotation was X | None or Optional[X].
     """
-    unwrapped = inspect.unwrap(func) if unwrap else func
-    signature = inspect.signature(unwrapped)
-    params: list[FuncParam] = []
+    if annotation is Parameter.empty or annotation is Any:
+        return (None, None, False)
 
-    for i, param in enumerate(signature.parameters.values()):
-        is_positional = param.kind in (
-            Parameter.POSITIONAL_ONLY,
-            Parameter.POSITIONAL_OR_KEYWORD,
-            Parameter.VAR_POSITIONAL,
-        )
-        is_varargs = param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD)
-        has_default = param.default != NO_DEFAULT
-
-        # Get type from type annotation or default value.
-        param_type: type | None = None
-        if param.annotation != Parameter.empty:
-            param_type = _extract_simple_type(param.annotation)
-        elif param.default is not Parameter.empty:
-            param_type = type(param.default)
-
-        func_param = FuncParam(
-            name=param.name,
-            type=param_type,
-            default=param.default if has_default else NO_DEFAULT,
-            position=i + 1 if is_positional else None,
-            is_varargs=is_varargs,
-        )
-        params.append(func_param)
+    current_annotation = annotation
+    is_optional_flag = False
 
-    return params
+    # Unwrap Optional[T] or T | None (from Python 3.10+ UnionType)
+    origin: type | None = get_origin(current_annotation)
+    args = get_args(current_annotation)
+
+    if origin is Union or (  # pyright: ignore[reportDeprecated]
+        hasattr(types, "UnionType") and isinstance(current_annotation, types.UnionType)
+    ):
+        non_none_args = [arg for arg in args if arg is not type(None)]
+        if len(non_none_args) == 1:
+            is_optional_flag = True
+            current_annotation = non_none_args[0]
+            origin = get_origin(current_annotation)  # Re-evaluate for the unwrapped type
+            args = get_args(current_annotation)
+        elif not non_none_args:  # Handles Union[NoneType] or just NoneType
+            return (type(None), None, True)
+        # If multiple non_none_args (e.g., int | str), current_annotation remains the Union for now.
+
+    #  Determine effective_type and inner_type from (potentially unwrapped) current_annotation
+    final_effective_type: type | None = None
+    final_inner_type: type | None = None
+
+    if isinstance(
+        current_annotation, type
+    ):  # Covers simple types (int, str) and resolved Union types (int | str)
+        final_effective_type = current_annotation
+    elif origin and isinstance(origin, type):  # Generics like list, dict, tuple (e.g., list[str])
+        final_effective_type = cast(type, origin)  # This would be `list` for `list[str]`
+        if args and _is_type_tuple(args) and args[0] is not Any:
+            # For simplicity, take the first type argument as inner_type.
+            # E.g., for list[str], inner_type is str. For dict[str, int], inner_type is str.
+            final_inner_type = args[0]
+            # A more sophisticated approach might handle all args for tuples like tuple[str, int]
+
+    return final_effective_type, final_inner_type, is_optional_flag
+
+
+def _is_type_tuple(args: tuple[Any, ...]) -> bool:
+    """Are all args types?"""
+    if not args:
+        return False
+    return all(isinstance(arg, type) for arg in args)
 
 
-def _extract_simple_type(annotation: Any) -> type | None:
+def inspect_function_params(func: Callable[..., Any], unwrap: bool = True) -> list[FuncParam]:
     """
-    Extract a single Type from an annotation that is an explicit simple type (like `str` or
-    an enum) or a simple Union (such as `str` from `Optional[str]`). Return None if it's not
-    clear.
+    Inspects a Python function's signature and returns a list of `ParamInfo` objects.
+    A convenience wrapper for `inspect.signature` that provides a detailed, structured
+    representation of each parameter, making it easier to build tools like CLI argument
+    parsers. By default, it unwraps decorated functions to get to the original signature.
     """
-    if isinstance(annotation, type):
-        return annotation
+    unwrapped_func = inspect.unwrap(func) if unwrap else func
+    signature = inspect.signature(unwrapped_func)
 
-    # Handle pipe syntax (str | None) from Python 3.10+
-    if hasattr(types, "UnionType") and isinstance(annotation, types.UnionType):
-        args = get_args(annotation)
-        non_none_args = [arg for arg in args if arg is not type(None)]
-        if len(non_none_args) == 1 and isinstance(non_none_args[0], type):
-            return non_none_args[0]
+    param_infos: list[FuncParam] = []
 
-    origin = get_origin(annotation)
-    if origin is Union:  # pyright: ignore
-        args = get_args(annotation)
-        non_none_args = [arg for arg in args if arg is not type(None)]
-        if len(non_none_args) == 1 and isinstance(non_none_args[0], type):
-            return non_none_args[0]
-    elif origin and isinstance(origin, type):
-        # Cast origin to type to satisfy the type checker
-        return cast(type, origin)  # pyright: ignore
+    for i, (param_name, param_obj) in enumerate(signature.parameters.items()):
+        effective_type, inner_type, is_optional = _resolve_type_details(param_obj.annotation)
+
+        # Fallback: if type is not resolved from annotation, try to infer from default value.
+        if (
+            effective_type is None
+            and param_obj.default is not NO_DEFAULT
+            and param_obj.default is not None
+        ):
+            if not is_optional:  # Avoid setting NoneType if it was Optional[SomethingElse]
+                effective_type = type(param_obj.default)
+
+        # Determine position
+        is_positional = param_obj.kind in (
+            Parameter.POSITIONAL_ONLY,
+            Parameter.POSITIONAL_OR_KEYWORD,
+            Parameter.VAR_POSITIONAL,
+        )
+        position = i + 1 if is_positional else None
+
+        info = FuncParam(
+            name=param_name,
+            kind=param_obj.kind,
+            annotation=param_obj.annotation,  # Store raw annotation
+            default=param_obj.default,  # Store raw default
+            position=position,
+            effective_type=effective_type,
+            inner_type=inner_type,
+            is_explicitly_optional=is_optional,
+        )
+        param_infos.append(info)
 
-    return None
+    return param_infos
 
 
 ## Tests
 
 
-def test_inspect_function_params():
+def test_inspect_function_parameters_updated():
+    # Test functions from your original example
     def func0(path: str | None = None) -> list:
         return [path]
 
@@ -124,55 +185,244 @@ def test_inspect_function_params():
     def func4() -> list:
         return []
 
-    def func5(x: int, y: int = 3, *, z: int = 4, **kwargs):  # pyright: ignore[reportUnusedParameter]
-        pass
+    def func5(x: int, y: int = 3, *, z: int = 4, **kwargs):
+        return [x, y, z, kwargs]
 
-    params0 = inspect_function_params(func0)
-    params1 = inspect_function_params(func1)
-    params2 = inspect_function_params(func2)
-    params3 = inspect_function_params(func3)
-    params4 = inspect_function_params(func4)
-    params5 = inspect_function_params(func5)
+    class MyEnum(Enum):
+        ITEM1 = "item1"
+        ITEM2 = "item2"
+
+    def func6(opt_enum: MyEnum | None = MyEnum.ITEM1):
+        return [opt_enum]
 
-    print("\ninspect:")
-    print(repr(params0))
-    print()
-    print(repr(params1))
-    print()
-    print(repr(params2))
-    print()
-    print(repr(params3))
-    print()
-    print(repr(params4))
-    print()
-    print(repr(params5))
-
-    assert params0 == [FuncParam(name="path", type=str, default=None, position=1, is_varargs=False)]
+    def func7(numbers: list[int]):
+        return [numbers]
 
+    def func8(maybe_list: list[str] | None = None):
+        return [maybe_list]
+
+    params0 = inspect_function_params(func0)
+    print("\ninspect_function_parameters results:")
+    print(f"func0: {params0}")
+    assert params0 == [
+        FuncParam(
+            name="path",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=(str | None),
+            default=None,
+            position=1,
+            effective_type=str,
+            inner_type=None,
+            is_explicitly_optional=True,
+        )
+    ]
+
+    params1 = inspect_function_params(func1)
+    print(f"func1: {params1}")
     assert params1 == [
-        FuncParam(name="arg1", type=str, default=NO_DEFAULT, position=1, is_varargs=False),
-        FuncParam(name="arg2", type=str, default=NO_DEFAULT, position=2, is_varargs=False),
-        FuncParam(name="arg3", type=int, default=NO_DEFAULT, position=3, is_varargs=False),
-        FuncParam(name="option_one", type=bool, default=False, position=4, is_varargs=False),
-        FuncParam(name="option_two", type=str, default=None, position=5, is_varargs=False),
+        FuncParam(
+            name="arg1",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=str,
+            default=NO_DEFAULT,
+            position=1,
+            effective_type=str,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
+        FuncParam(
+            name="arg2",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=str,
+            default=NO_DEFAULT,
+            position=2,
+            effective_type=str,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
+        FuncParam(
+            name="arg3",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=int,
+            default=NO_DEFAULT,
+            position=3,
+            effective_type=int,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
+        FuncParam(
+            name="option_one",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=bool,
+            default=False,
+            position=4,
+            effective_type=bool,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),  # bool default makes it not explicitly Optional from type
+        FuncParam(
+            name="option_two",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=(str | None),
+            default=None,
+            position=5,
+            effective_type=str,
+            inner_type=None,
+            is_explicitly_optional=True,
+        ),
     ]
 
+    params2 = inspect_function_params(func2)
+    print(f"func2: {params2}")
     assert params2 == [
-        FuncParam(name="paths", type=str, default=NO_DEFAULT, position=1, is_varargs=True),
-        FuncParam(name="summary", type=bool, default=False, position=None, is_varargs=False),
-        FuncParam(name="iso_time", type=bool, default=False, position=None, is_varargs=False),
+        FuncParam(
+            name="paths",
+            kind=Parameter.VAR_POSITIONAL,
+            annotation=str,
+            default=NO_DEFAULT,
+            position=1,
+            effective_type=str,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),  # For *args: T, effective_type is T
+        FuncParam(
+            name="summary",
+            kind=Parameter.KEYWORD_ONLY,
+            annotation=(bool | None),
+            default=False,
+            position=None,
+            effective_type=bool,
+            inner_type=None,
+            is_explicitly_optional=True,
+        ),
+        FuncParam(
+            name="iso_time",
+            kind=Parameter.KEYWORD_ONLY,
+            annotation=bool,
+            default=False,
+            position=None,
+            effective_type=bool,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
     ]
 
+    params3 = inspect_function_params(func3)
+    print(f"func3: {params3}")
     assert params3 == [
-        FuncParam(name="arg1", type=str, default=NO_DEFAULT, position=1, is_varargs=False),
-        FuncParam(name="keywords", type=None, default=NO_DEFAULT, position=None, is_varargs=True),
+        FuncParam(
+            name="arg1",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=str,
+            default=NO_DEFAULT,
+            position=1,
+            effective_type=str,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
+        FuncParam(
+            name="keywords",
+            kind=Parameter.VAR_KEYWORD,
+            annotation=Parameter.empty,
+            default=NO_DEFAULT,
+            position=None,
+            effective_type=None,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
     ]
 
+    params4 = inspect_function_params(func4)
+    print(f"func4: {params4}")
     assert params4 == []
 
+    params5 = inspect_function_params(func5)
+    print(f"func5: {params5}")
     assert params5 == [
-        FuncParam(name="x", type=int, default=NO_DEFAULT, position=1, is_varargs=False),
-        FuncParam(name="y", type=int, default=3, position=2, is_varargs=False),
-        FuncParam(name="z", type=int, default=4, position=None, is_varargs=False),
-        FuncParam(name="kwargs", type=None, default=NO_DEFAULT, position=None, is_varargs=True),
+        FuncParam(
+            name="x",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=int,
+            default=NO_DEFAULT,
+            position=1,
+            effective_type=int,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
+        FuncParam(
+            name="y",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=int,
+            default=3,
+            position=2,
+            effective_type=int,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
+        FuncParam(
+            name="z",
+            kind=Parameter.KEYWORD_ONLY,
+            annotation=int,
+            default=4,
+            position=None,
+            effective_type=int,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
+        FuncParam(
+            name="kwargs",
+            kind=Parameter.VAR_KEYWORD,
+            annotation=Parameter.empty,
+            default=NO_DEFAULT,
+            position=None,
+            effective_type=None,
+            inner_type=None,
+            is_explicitly_optional=False,
+        ),
+    ]
+
+    params6 = inspect_function_params(func6)
+    print(f"func6: {params6}")
+
+    assert params6 == [
+        FuncParam(
+            name="opt_enum",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=(MyEnum | None),
+            default=MyEnum.ITEM1,
+            position=1,
+            effective_type=MyEnum,
+            inner_type=None,
+            is_explicitly_optional=True,
+        )
+    ]
+
+    params7 = inspect_function_params(func7)
+    print(f"func7: {params7}")
+    assert params7 == [
+        FuncParam(
+            name="numbers",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=list[int],
+            default=NO_DEFAULT,
+            position=1,
+            effective_type=list,
+            inner_type=int,
+            is_explicitly_optional=False,
+        )
+    ]
+
+    params8 = inspect_function_params(func8)
+    print(f"func8: {params8}")
+    assert params8 == [
+        FuncParam(
+            name="maybe_list",
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=(list[str] | None),
+            default=None,
+            position=1,
+            effective_type=list,
+            inner_type=str,
+            is_explicitly_optional=True,
+        )
     ]

kash/utils/common/inflection.py

@@ -0,0 +1,22 @@
+from functools import cache
+
+# Had been using the `inflect` package, but it takes over 1s to import.
+# pluralizer seems simpler and fine for common English usage.
+
+
+@cache
+def _get_pluralizer():
+    from pluralizer import Pluralizer
+
+    return Pluralizer()
+
+
+def plural(word: str, count: int | None = None) -> str:
+    """
+    Pluralize or singularize a word based on the count.
+    """
+    from chopdiff.docs import is_word
+
+    if not is_word(word):
+        return word
+    return _get_pluralizer().pluralize(word, count=count)

kash/utils/common/task_stack.py

@@ -3,7 +3,6 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 
 from kash.config.text_styles import (
-    EMOJI_ACTION,
     EMOJI_BREADCRUMB_SEP,
     EMOJI_MSG_INDENT,
     TASK_STACK_HEADER,
@@ -93,9 +92,8 @@ class TaskStack:
         if not self.stack:
             return ""
         else:
-            prefix = f"{self.prefix_str()} {EMOJI_BREADCRUMB_SEP} "
-            sep = f"\n{prefix}"
-            return prefix + sep.join(state.full_str() for state in self.stack)
+            sep = f" {EMOJI_BREADCRUMB_SEP} "
+            return f"{EMOJI_BREADCRUMB_SEP} " + sep.join(state.full_str() for state in self.stack)
 
     def prefix_str(self) -> str:
         if not self.stack:
@@ -107,8 +105,7 @@ class TaskStack:
         return f"TaskStack({self.full_str()})"
 
     def log_stack(self):
-        self._print()
-        self._log.message(f"{EMOJI_ACTION} {TASK_STACK_HEADER}\n%s", self.full_str())
+        self._log.message(f"{TASK_STACK_HEADER} %s", self.full_str())
 
     @contextmanager
     def context(self, name: str, total_parts: int = 1, unit: str = ""):
@@ -123,9 +120,7 @@ class TaskStack:
         except Exception as e:
             # Log immediately where the exception occurred, but don't double-log.
             if e not in self.exceptions_logged:
-                self._log.warning(
-                    "Exception in task context: %s: %s", type(e).__name__, e, exc_info=True
-                )
+                self._log.info("Exception in task context: %s: %s", type(e).__name__, e)
                 self.exceptions_logged.add(e)
             self.next(last_had_error=True)
             raise
@@ -139,12 +134,6 @@ class TaskStack:
 
         return get_logger(__name__)
 
-    @property
-    def _print(self):
-        from kash.shell.output.shell_output import cprint
-
-        return cprint
-
 
 task_stack_var: contextvars.ContextVar[TaskStack | None] = contextvars.ContextVar(
     "task_stack", default=None

kash/utils/errors.py

@@ -3,6 +3,8 @@ Common hierarchy of error types. These inherit from standard errors like
 ValueError and FileExistsError but are more fine-grained.
 """
 
+from functools import cache
+
 
 class KashRuntimeError(ValueError):
     """Base class for kash runtime errors."""
@@ -145,8 +147,14 @@ class ApiError(KashRuntimeError):
     pass
 
 
-def _nonfatal_exceptions() -> tuple[type[Exception], ...]:
+@cache
+def get_nonfatal_exceptions() -> tuple[type[Exception], ...]:
+    """
+    Exceptions that are not fatal and usually don't merit a full stack trace.
+    """
     exceptions: list[type[Exception]] = [SelfExplanatoryError, FileNotFoundError, IOError]
+
+    # Slow imports, do lazily.
     try:
         from xonsh.tools import XonshError
 
@@ -155,14 +163,15 @@ def _nonfatal_exceptions() -> tuple[type[Exception], ...]:
         pass
 
     try:
-        import litellm
+        import openai
 
-        exceptions.append(litellm.exceptions.APIError)
+        # LiteLLM exceptions subclass openai.APIError
+        exceptions.append(openai.APIError)
     except ImportError:
         pass
 
     try:
-        import yt_dlp
+        import yt_dlp.utils
 
         exceptions.append(yt_dlp.utils.DownloadError)
     except ImportError:
@@ -171,12 +180,8 @@ def _nonfatal_exceptions() -> tuple[type[Exception], ...]:
     return tuple(exceptions)
 
 
-NONFATAL_EXCEPTIONS = _nonfatal_exceptions()
-"""Exceptions that are not fatal and usually don't merit a full stack trace."""
-
-
 def is_fatal(exception: Exception) -> bool:
-    for e in NONFATAL_EXCEPTIONS:
+    for e in get_nonfatal_exceptions():
         if isinstance(exception, e):
             return False
     return True

kash/utils/file_utils/file_ext.py

@@ -20,6 +20,7 @@ class FileExt(Enum):
     diff = "diff"
     json = "json"
     csv = "csv"
+    xlsx = "xlsx"
     npz = "npz"
     log = "log"
     py = "py"
@@ -34,6 +35,8 @@ class FileExt(Enum):
     mp3 = "mp3"
     m4a = "m4a"
     mp4 = "mp4"
+    pptx = "pptx"
+    epub = "epub"
 
     @property
     def dot_ext(self) -> str:
@@ -50,6 +53,7 @@ class FileExt(Enum):
             self.py,
             self.sh,
             self.xsh,
+            self.epub,
         ]
 
     @property