kash-shell 0.3.9__py3-none-any.whl → 0.3.11__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/import_utils.py

@@ -15,21 +15,30 @@ Tallies: TypeAlias = dict[str, int]
 def import_subdirs(
     parent_package_name: str,
     parent_dir: Path,
-    subdir_names: list[str],
+    subdir_names: list[str] | None = None,
     tallies: Tallies | None = None,
 ):
     """
     Import all files in the given subdirectories of a single parent directory.
+    Wraps `pkgutil.iter_modules` to iterate over all modules in the subdirectories.
+    If `subdir_names` is `None`, will import all subdirectories.
     """
     if tallies is None:
         tallies = {}
+    if not subdir_names:
+        subdir_names = ["."]
 
     for subdir_name in subdir_names:
-        full_path = parent_dir / subdir_name
+        if subdir_name == ".":
+            full_path = parent_dir
+            package_name = parent_package_name
+        else:
+            full_path = parent_dir / subdir_name
+            package_name = f"{parent_package_name}.{subdir_name}"
+
         if not full_path.is_dir():
             raise FileNotFoundError(f"Subdirectory not found: {full_path}")
 
-        package_name = f"{parent_package_name}.{subdir_name}"
         for _module_finder, module_name, _is_pkg in pkgutil.iter_modules(path=[str(full_path)]):
             importlib.import_module(f"{package_name}.{module_name}")  # Propagate import errors
             tallies[package_name] = tallies.get(package_name, 0) + 1

kash/utils/common/type_utils.py

@@ -15,35 +15,6 @@ def not_none(value: T | None, message: str | None = None) -> T:
     return value
 
 
-def is_truthy(value: Any, strict: bool = True) -> bool:
-    """
-    True for all common string and non-string values for true. Useful for parsing
-    string values or command line arguments.
-    """
-    truthy_values = {"true", "1", "yes", "on", "y"}
-    falsy_values = {"false", "0", "no", "off", "n", ""}
-
-    if value is None:
-        return False
-    elif isinstance(value, str):
-        value = value.strip().lower()
-        if value in truthy_values:
-            return True
-        elif value in falsy_values:
-            return False
-    elif isinstance(value, (int, float)):
-        return value != 0
-    elif isinstance(value, bool):
-        return value
-    elif isinstance(value, (list, tuple, set, dict)):
-        return len(value) > 0
-
-    if strict:
-        raise ValueError(f"Could not convert type {type(value)} to boolean: {repr(value)}")
-
-    return bool(value)
-
-
 def as_dataclass(dict_data: dict[str, Any], dataclass_type: type[T]) -> T:
     """
     Convert a dict recursively to dataclass object, raising an error if the data does

kash/utils/common/url.py

@@ -67,15 +67,39 @@ def is_file_url(url: str | Url) -> bool:
     return url.startswith("file://")
 
 
-def parse_file_url(url: str | Url) -> Path | None:
+def parse_http_url(url: str | Url) -> ParseResult:
     """
-    Parse a file URL and return the path, or None if not a file URL.
+    Parse an http/https URL and return the parsed result, raising ValueError if
+    not an http/https URL.
+    """
+    parsed_url = urlparse(url)
+    if parsed_url.scheme in ("http", "https"):
+        return parsed_url
+    else:
+        raise ValueError(f"Not an http/https URL: {url}")
+
+
+def parse_file_url(url: str | Url) -> Path:
+    """
+    Parse a file URL and return the path, raising ValueError if not a file URL.
     """
     parsed_url = urlparse(url)
     if parsed_url.scheme == "file":
         return Path(parsed_url.path)
     else:
-        return None
+        raise ValueError(f"Not a file URL: {url}")
+
+
+def parse_s3_url(url: str | Url) -> tuple[str, str]:
+    """
+    Parse an S3 URL and return the bucket and key, raising ValueError if not an
+    S3 URL.
+    """
+    parsed_url = urlparse(url)
+    if parsed_url.scheme == "s3":
+        return parsed_url.netloc, parsed_url.path.lstrip("/")
+    else:
+        raise ValueError(f"Not an S3 URL: {url}")
 
 
 def as_file_url(path: str | Path) -> Url:

kash/utils/errors.py

@@ -139,6 +139,12 @@ class FileFormatError(ContentError):
     pass
 
 
+class ApiError(KashRuntimeError):
+    """Raised when an API call returns something unexpected."""
+
+    pass
+
+
 def _nonfatal_exceptions() -> tuple[type[Exception], ...]:
     exceptions: list[type[Exception]] = [SelfExplanatoryError, FileNotFoundError, IOError]
     try:

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