scitex 2.14.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/introspect/_members.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_members.py
+
+"""Member listing utilities."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Literal
+
+from ._resolve import get_type_info, resolve_object
+
+
+def list_members(
+    dotted_path: str,
+    filter: Literal["all", "public", "private", "dunder"] = "public",
+    kind: Literal["all", "functions", "classes", "data", "modules"] | None = None,
+    include_inherited: bool = False,
+) -> dict:
+    """
+    List members of a module or class.
+
+    Like Python's `dir()` but with filtering and metadata.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the module or class
+    filter : str
+        'all' - All members
+        'public' - Only public (no leading _)
+        'private' - Only private (single _)
+        'dunder' - Only dunder (__name__)
+    kind : str | None
+        Filter by type: 'functions', 'classes', 'data', 'modules'
+    include_inherited : bool
+        For classes, include inherited members
+
+    Returns
+    -------
+    dict
+        members: list[dict] - Each with name, kind, summary
+        count: int
+        type_info: dict
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    type_info = get_type_info(obj)
+
+    if inspect.isclass(obj) and not include_inherited:
+        member_names = list(obj.__dict__.keys())
+    else:
+        member_names = dir(obj)
+
+    if filter == "public":
+        member_names = [n for n in member_names if not n.startswith("_")]
+    elif filter == "private":
+        member_names = [
+            n for n in member_names if n.startswith("_") and not n.startswith("__")
+        ]
+    elif filter == "dunder":
+        member_names = [
+            n for n in member_names if n.startswith("__") and n.endswith("__")
+        ]
+
+    members = []
+    for name in sorted(member_names):
+        try:
+            member = getattr(obj, name)
+        except AttributeError:
+            continue
+
+        member_type_info = get_type_info(member)
+        member_kind = member_type_info["kind"]
+
+        if kind:
+            kind_map = {
+                "functions": ("function", "method", "builtin_function_or_method"),
+                "classes": ("class",),
+                "data": ("data",),
+                "modules": ("module",),
+            }
+            if kind in kind_map and member_kind not in kind_map[kind]:
+                continue
+
+        doc = inspect.getdoc(member) or ""
+        summary = doc.split("\n")[0] if doc else ""
+
+        members.append(
+            {
+                "name": name,
+                "kind": member_kind,
+                "summary": summary[:100] + "..." if len(summary) > 100 else summary,
+            }
+        )
+
+    return {
+        "success": True,
+        "members": members,
+        "count": len(members),
+        "type_info": type_info,
+    }
+
+
+def get_exports(dotted_path: str) -> dict:
+    """
+    Get the __all__ exports of a module.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the module
+
+    Returns
+    -------
+    dict
+        exports: list[str] - Names in __all__
+        has_all: bool - Whether __all__ is defined
+        type_info: dict
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    type_info = get_type_info(obj)
+
+    if not inspect.ismodule(obj):
+        return {
+            "success": False,
+            "error": f"'{dotted_path}' is not a module",
+            "type_info": type_info,
+        }
+
+    exports = getattr(obj, "__all__", None)
+
+    if exports is None:
+        exports = [n for n in dir(obj) if not n.startswith("_")]
+        has_all = False
+    else:
+        has_all = True
+
+    return {
+        "success": True,
+        "exports": list(exports),
+        "has_all": has_all,
+        "count": len(exports),
+        "type_info": type_info,
+    }

scitex/introspect/_resolve.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_resolve.py
+
+"""Object resolution and type information utilities."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from typing import Any
+
+
+def resolve_object(dotted_path: str) -> tuple[Any, str | None]:
+    """
+    Resolve a dotted path to a Python object.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path like 'scitex.plt.plot' or 'scitex.audio'
+
+    Returns
+    -------
+    tuple[Any, str | None]
+        (resolved_object, error_message)
+        If successful, error_message is None
+
+    Examples
+    --------
+    >>> obj, err = resolve_object("scitex.plt")
+    >>> obj, err = resolve_object("scitex.audio.speak")
+    """
+    parts = dotted_path.split(".")
+    obj = None
+    last_error = None
+
+    for i in range(len(parts), 0, -1):
+        module_path = ".".join(parts[:i])
+        try:
+            obj = importlib.import_module(module_path)
+            for attr_name in parts[i:]:
+                obj = getattr(obj, attr_name)
+            return obj, None
+        except (ImportError, AttributeError) as e:
+            last_error = str(e)
+            continue
+
+    return None, f"Could not resolve '{dotted_path}': {last_error}"
+
+
+def get_type_info(obj: Any) -> dict:
+    """
+    Get type information about an object.
+
+    Returns
+    -------
+    dict
+        type: str - The type name
+        kind: str - 'module', 'class', 'function', 'method', 'property', 'data'
+        module: str - Module where defined
+        qualname: str - Qualified name
+    """
+    type_name = type(obj).__name__
+
+    if inspect.ismodule(obj):
+        kind = "module"
+    elif inspect.isclass(obj):
+        kind = "class"
+    elif inspect.isfunction(obj) or inspect.isbuiltin(obj):
+        kind = "function"
+    elif inspect.ismethod(obj):
+        kind = "method"
+    elif isinstance(obj, property):
+        kind = "property"
+    elif callable(obj):
+        kind = "callable"
+    else:
+        kind = "data"
+
+    module_name = getattr(obj, "__module__", None)
+    qualname = getattr(obj, "__qualname__", getattr(obj, "__name__", str(obj)))
+
+    return {
+        "type": type_name,
+        "kind": kind,
+        "module": module_name,
+        "qualname": qualname,
+    }

scitex/introspect/_signature.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_signature.py
+
+"""Signature extraction utilities."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from ._resolve import get_type_info, resolve_object
+
+
+def _format_annotation(annotation: Any) -> str:
+    """Format a type annotation as a string."""
+    if annotation is None:
+        return "None"
+    if hasattr(annotation, "__name__"):
+        return annotation.__name__
+    return str(annotation).replace("typing.", "")
+
+
+def _build_signature_string(
+    obj: Any,
+    parameters: list[dict],
+    return_annotation: str | None,
+) -> str:
+    """Build a human-readable signature string."""
+    name = getattr(obj, "__name__", "?")
+
+    param_strs = []
+    for p in parameters:
+        s = p["name"]
+        if "annotation" in p:
+            s += f": {p['annotation']}"
+        if "default" in p:
+            s += f" = {p['default']}"
+        param_strs.append(s)
+
+    sig = f"{name}({', '.join(param_strs)})"
+    if return_annotation:
+        sig += f" -> {return_annotation}"
+
+    return sig
+
+
+def get_signature(
+    dotted_path: str,
+    include_defaults: bool = True,
+    include_annotations: bool = True,
+) -> dict:
+    """
+    Get the signature of a function, method, or class.
+
+    Like IPython's `func?` but returns structured data.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the callable (e.g., 'scitex.plt.plot')
+    include_defaults : bool
+        Include default values in signature
+    include_annotations : bool
+        Include type annotations
+
+    Returns
+    -------
+    dict
+        name: str
+        signature: str - Human-readable signature
+        parameters: list[dict] - Detailed parameter info
+        return_annotation: str | None
+        type_info: dict
+
+    Examples
+    --------
+    >>> get_signature("scitex.plt.plot")
+    {'name': 'plot', 'signature': 'plot(spec: dict, ...) -> dict', ...}
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    type_info = get_type_info(obj)
+
+    callable_obj = obj
+    if inspect.isclass(obj):
+        callable_obj = obj.__init__
+
+    try:
+        sig = inspect.signature(callable_obj)
+    except (ValueError, TypeError) as e:
+        return {
+            "success": False,
+            "error": f"Cannot get signature: {e}",
+            "type_info": type_info,
+        }
+
+    parameters = []
+    for name, param in sig.parameters.items():
+        if name == "self":
+            continue
+
+        param_info = {
+            "name": name,
+            "kind": str(param.kind).split(".")[-1],
+        }
+
+        if include_annotations and param.annotation != inspect.Parameter.empty:
+            param_info["annotation"] = _format_annotation(param.annotation)
+
+        if include_defaults and param.default != inspect.Parameter.empty:
+            param_info["default"] = repr(param.default)
+
+        parameters.append(param_info)
+
+    return_annotation = None
+    if include_annotations and sig.return_annotation != inspect.Signature.empty:
+        return_annotation = _format_annotation(sig.return_annotation)
+
+    sig_str = _build_signature_string(obj, parameters, return_annotation)
+
+    return {
+        "success": True,
+        "name": getattr(obj, "__name__", dotted_path.split(".")[-1]),
+        "signature": sig_str,
+        "parameters": parameters,
+        "return_annotation": return_annotation,
+        "type_info": type_info,
+    }

scitex/introspect/_source.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_source.py
+
+"""Source code retrieval utilities."""
+
+from __future__ import annotations
+
+import inspect
+
+from ._resolve import get_type_info, resolve_object
+
+
+def get_source(
+    dotted_path: str,
+    max_lines: int | None = None,
+    include_decorators: bool = True,
+) -> dict:
+    """
+    Get the source code of a Python object.
+
+    Like IPython's `func??`.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the object
+    max_lines : int | None
+        Limit output to first N lines (None = no limit)
+    include_decorators : bool
+        Include decorator lines
+
+    Returns
+    -------
+    dict
+        source: str
+        file: str - Source file path
+        line_start: int - Starting line number
+        line_count: int - Number of lines
+        type_info: dict
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    type_info = get_type_info(obj)
+
+    try:
+        source = inspect.getsource(obj)
+        source_file = inspect.getfile(obj)
+        _, line_start = inspect.getsourcelines(obj)
+    except (TypeError, OSError) as e:
+        return {
+            "success": False,
+            "error": f"Cannot get source: {e}",
+            "type_info": type_info,
+        }
+
+    lines = source.split("\n")
+    line_count = len(lines)
+
+    if not include_decorators and lines:
+        i = 0
+        while i < len(lines) and lines[i].strip().startswith("@"):
+            i += 1
+        lines = lines[i:]
+        source = "\n".join(lines)
+
+    if max_lines and len(lines) > max_lines:
+        lines = lines[:max_lines]
+        source = "\n".join(lines) + f"\n... ({line_count - max_lines} more lines)"
+
+    return {
+        "success": True,
+        "source": source,
+        "file": source_file,
+        "line_start": line_start,
+        "line_count": line_count,
+        "type_info": type_info,
+    }

scitex/introspect/_type_hints.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_type_hints.py
+
+"""Type hint analysis utilities."""
+
+from __future__ import annotations
+
+import inspect
+import typing
+from typing import Any, get_type_hints
+
+from ._resolve import get_type_info, resolve_object
+
+
+def get_type_hints_detailed(
+    dotted_path: str,
+    include_extras: bool = True,
+) -> dict:
+    """
+    Get detailed type hint information for a callable or class.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the function, method, or class
+    include_extras : bool
+        Include typing extras (Annotated metadata, etc.)
+
+    Returns
+    -------
+    dict
+        hints: dict[str, dict] - Parameter name to type info
+        return_hint: dict | None - Return type info
+        type_info: dict
+
+    Examples
+    --------
+    >>> get_type_hints_detailed("json.dumps")
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    type_info_obj = get_type_info(obj)
+
+    # Get the object to analyze
+    target = obj
+    if inspect.isclass(obj):
+        target = obj.__init__
+
+    try:
+        hints = get_type_hints(target, include_extras=include_extras)
+    except Exception as e:
+        # Some objects don't support get_type_hints
+        hints = getattr(target, "__annotations__", {})
+        if not hints:
+            return {
+                "success": False,
+                "error": f"Cannot get type hints: {e}",
+                "type_info": type_info_obj,
+            }
+
+    # Analyze each hint
+    analyzed_hints = {}
+    return_hint = None
+
+    for name, hint in hints.items():
+        hint_info = _analyze_type(hint)
+        if name == "return":
+            return_hint = hint_info
+        else:
+            analyzed_hints[name] = hint_info
+
+    return {
+        "success": True,
+        "hints": analyzed_hints,
+        "return_hint": return_hint,
+        "hint_count": len(analyzed_hints),
+        "type_info": type_info_obj,
+    }
+
+
+def _analyze_type(hint: Any) -> dict:
+    """Analyze a type hint and return structured info."""
+    result = {
+        "raw": _format_type(hint),
+        "origin": None,
+        "args": [],
+        "is_optional": False,
+        "is_union": False,
+        "is_generic": False,
+    }
+
+    # Get origin (e.g., list from list[int])
+    origin = typing.get_origin(hint)
+    if origin is not None:
+        result["origin"] = _format_type(origin)
+        result["is_generic"] = True
+
+        # Get args (e.g., int from list[int])
+        args = typing.get_args(hint)
+        if args:
+            result["args"] = [_format_type(a) for a in args]
+
+        # Check for Union/Optional
+        if origin is typing.Union:
+            result["is_union"] = True
+            # Optional is Union[X, None]
+            if type(None) in args:
+                result["is_optional"] = True
+
+    return result
+
+
+def _format_type(t: Any) -> str:
+    """Format a type as a readable string."""
+    if t is type(None):
+        return "None"
+    if hasattr(t, "__name__"):
+        return t.__name__
+    if hasattr(t, "_name"):
+        return t._name or str(t)
+    return str(t).replace("typing.", "")
+
+
+def get_class_annotations(dotted_path: str) -> dict:
+    """
+    Get all annotations for a class (class vars and methods).
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the class
+
+    Returns
+    -------
+    dict
+        class_vars: dict - Class variable annotations
+        methods: dict - Method annotations (name -> hints)
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    if not inspect.isclass(obj):
+        return {"success": False, "error": f"'{dotted_path}' is not a class"}
+
+    # Class-level annotations
+    class_vars = {}
+    for name, hint in getattr(obj, "__annotations__", {}).items():
+        class_vars[name] = _analyze_type(hint)
+
+    # Method annotations
+    methods = {}
+    for name, member in inspect.getmembers(obj):
+        if inspect.isfunction(member) or inspect.ismethod(member):
+            try:
+                hints = get_type_hints(member)
+                if hints:
+                    methods[name] = {k: _analyze_type(v) for k, v in hints.items()}
+            except Exception:
+                pass
+
+    return {
+        "success": True,
+        "class": dotted_path,
+        "class_vars": class_vars,
+        "methods": methods,
+        "class_var_count": len(class_vars),
+        "method_count": len(methods),
+    }

scitex/io/bundle/README.md

@@ -1,7 +1,7 @@
 <!-- ---
 !-- Timestamp: 2026-01-07
 !-- Author: ywatanabe
-!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/io/bundle/README.md
+!-- File: /home/ywatanabe/proj/scitex-python/src/scitex/io/bundle/README.md
 !-- --- -->
 
 # SciTeX Bundle I/O