kash-shell 0.3.10__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/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

kash/utils/file_utils/file_formats_model.py

@@ -48,6 +48,7 @@ class Format(Enum):
     """`md_html` is Markdown with HTML, used for example when we structure Markdown with divs."""
     html = "html"
     """`markdown` should be simple and clean Markdown that we can use with LLMs."""
+    epub = "epub"
     yaml = "yaml"
     diff = "diff"
     python = "python"
@@ -56,12 +57,14 @@ class Format(Enum):
     xonsh = "xonsh"
     json = "json"
     csv = "csv"
+    xlsx = "xlsx"
     npz = "npz"
     log = "log"
 
     # Media formats.
     pdf = "pdf"
     docx = "docx"
+    pptx = "pptx"
     jpeg = "jpeg"
     png = "png"
     gif = "gif"
@@ -108,6 +111,7 @@ class Format(Enum):
             self.html,
             self.pdf,
             self.docx,
+            self.pptx,
         ]
 
     @property
@@ -128,7 +132,7 @@ class Format(Enum):
 
     @property
     def is_data(self) -> bool:
-        return self in [self.csv, self.npz]
+        return self in [self.csv, self.xlsx, self.npz]
 
     @property
     def is_binary(self) -> bool:
@@ -166,6 +170,7 @@ class Format(Enum):
             Format.markdown: MediaType.text,
             Format.md_html: MediaType.text,
             Format.html: MediaType.webpage,
+            Format.epub: MediaType.text,
             Format.yaml: MediaType.text,
             Format.diff: MediaType.text,
             Format.python: MediaType.text,
@@ -175,11 +180,13 @@ class Format(Enum):
             Format.csv: MediaType.text,
             Format.log: MediaType.text,
             Format.pdf: MediaType.text,
+            Format.xlsx: MediaType.text,
             Format.jpeg: MediaType.image,
             Format.png: MediaType.image,
             Format.gif: MediaType.image,
             Format.svg: MediaType.image,
             Format.docx: MediaType.text,
+            Format.pptx: MediaType.text,
             Format.mp3: MediaType.audio,
             Format.m4a: MediaType.audio,
             Format.mp4: MediaType.video,
@@ -200,6 +207,7 @@ class Format(Enum):
             FileExt.diff.value: Format.diff,
             FileExt.json.value: Format.json,
             FileExt.csv.value: Format.csv,
+            FileExt.xlsx.value: Format.xlsx,
             FileExt.npz.value: Format.npz,
             FileExt.log.value: Format.log,
             FileExt.py.value: Format.python,
@@ -207,6 +215,7 @@ class Format(Enum):
             FileExt.xsh.value: Format.xonsh,
             FileExt.pdf.value: Format.pdf,
             FileExt.docx.value: Format.docx,
+            FileExt.pptx.value: Format.pptx,
             FileExt.jpg.value: Format.jpeg,
             FileExt.png.value: Format.png,
             FileExt.gif.value: Format.gif,
@@ -214,6 +223,7 @@ class Format(Enum):
             FileExt.mp3.value: Format.mp3,
             FileExt.m4a.value: Format.m4a,
             FileExt.mp4.value: Format.mp4,
+            FileExt.epub.value: Format.epub,
         }
         return ext_to_format.get(file_ext.value, None)
 
@@ -228,10 +238,12 @@ class Format(Enum):
             Format.md_html: FileExt.md,
             Format.html: FileExt.html,
             Format.plaintext: FileExt.txt,
+            Format.epub: FileExt.epub,
             Format.yaml: FileExt.yml,
             Format.diff: FileExt.diff,
             Format.json: FileExt.json,
             Format.csv: FileExt.csv,
+            Format.xlsx: FileExt.xlsx,
             Format.npz: FileExt.npz,
             Format.log: FileExt.log,
             Format.python: FileExt.py,
@@ -239,6 +251,7 @@ class Format(Enum):
             Format.xonsh: FileExt.xsh,
             Format.pdf: FileExt.pdf,
             Format.docx: FileExt.docx,
+            Format.pptx: FileExt.pptx,
             Format.jpeg: FileExt.jpg,
             Format.png: FileExt.png,
             Format.gif: FileExt.gif,
@@ -260,6 +273,7 @@ class Format(Enum):
             "text/html": Format.html,
             "text/diff": Format.diff,
             "text/x-diff": Format.diff,
+            "application/epub+zip": Format.epub,
             "application/yaml": Format.yaml,
             "application/x-yaml": Format.yaml,
             "text/x-python": Format.python,
@@ -269,9 +283,11 @@ class Format(Enum):
             "text/x-xonsh": Format.xonsh,
             "application/json": Format.json,
             "text/csv": Format.csv,
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": Format.xlsx,
             "application/x-npz": Format.npz,
             "application/pdf": Format.pdf,
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document": Format.docx,
+            "application/vnd.openxmlformats-officedocument.presentationml.presentation": Format.pptx,
             "image/jpeg": Format.jpeg,
             "image/png": Format.png,
             "image/gif": Format.gif,

kash/web_gen/__init__.py

@@ -1,4 +0,0 @@
-from pathlib import Path
-
-base_templates_dir = Path(__file__).parent / "templates"
-"""Common base web page templates."""