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

scitex/introspect/_mcp/__init__.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_mcp/__init__.py
+
+"""MCP tools for introspection."""
+
+from .handlers import (
+    # Advanced
+    call_graph_handler,
+    class_hierarchy_handler,
+    dependencies_handler,
+    # IPython-style names
+    dir_handler,
+    # Basic
+    docstring_handler,
+    examples_handler,
+    exports_handler,
+    imports_handler,
+    list_api_handler,
+    q_handler,
+    qq_handler,
+    type_hints_handler,
+)
+
+__all__ = [
+    # IPython-style names
+    "q_handler",
+    "qq_handler",
+    "dir_handler",
+    "list_api_handler",
+    # Basic
+    "docstring_handler",
+    "exports_handler",
+    "examples_handler",
+    # Advanced
+    "class_hierarchy_handler",
+    "type_hints_handler",
+    "imports_handler",
+    "dependencies_handler",
+    "call_graph_handler",
+]

scitex/introspect/_mcp/handlers.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_mcp/handlers.py
+
+"""MCP handlers for introspection tools."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+
+async def q_handler(
+    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?)."""
+    try:
+        from .. import q
+
+        result = q(
+            dotted_path,
+            include_defaults=include_defaults,
+            include_annotations=include_annotations,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def docstring_handler(
+    dotted_path: str,
+    format: Literal["raw", "parsed", "summary"] = "raw",
+) -> dict:
+    """Get the docstring of a Python object."""
+    try:
+        from .. import get_docstring
+
+        result = get_docstring(dotted_path, format=format)
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def qq_handler(
+    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??)."""
+    try:
+        from .. import qq
+
+        result = qq(
+            dotted_path,
+            max_lines=max_lines,
+            include_decorators=include_decorators,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def dir_handler(
+    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 dir())."""
+    try:
+        from .. import dir
+
+        result = dir(
+            dotted_path,
+            filter=filter,
+            kind=kind,
+            include_inherited=include_inherited,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def exports_handler(dotted_path: str) -> dict:
+    """Get the __all__ exports of a module."""
+    try:
+        from .. import get_exports
+
+        result = get_exports(dotted_path)
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def examples_handler(
+    dotted_path: str,
+    search_paths: list[str] | None = None,
+    max_results: int = 10,
+) -> dict:
+    """Find usage examples of a function/class in tests and examples."""
+    try:
+        from .. import find_examples
+
+        result = find_examples(
+            dotted_path,
+            search_paths=search_paths,
+            max_results=max_results,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# Advanced handlers
+
+
+async def class_hierarchy_handler(
+    dotted_path: str,
+    include_builtins: bool = False,
+    max_depth: int = 10,
+) -> dict:
+    """Get the inheritance hierarchy of a class."""
+    try:
+        from .. import get_class_hierarchy
+
+        result = get_class_hierarchy(
+            dotted_path,
+            include_builtins=include_builtins,
+            max_depth=max_depth,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def type_hints_handler(
+    dotted_path: str,
+    include_extras: bool = True,
+) -> dict:
+    """Get detailed type hint information."""
+    try:
+        from .. import get_type_hints_detailed
+
+        result = get_type_hints_detailed(
+            dotted_path,
+            include_extras=include_extras,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def imports_handler(
+    dotted_path: str,
+    categorize: bool = True,
+) -> dict:
+    """Get all imports from a module."""
+    try:
+        from .. import get_imports
+
+        result = get_imports(
+            dotted_path,
+            categorize=categorize,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def dependencies_handler(
+    dotted_path: str,
+    recursive: bool = False,
+    max_depth: int = 3,
+) -> dict:
+    """Get module dependencies."""
+    try:
+        from .. import get_dependencies
+
+        result = get_dependencies(
+            dotted_path,
+            recursive=recursive,
+            max_depth=max_depth,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def call_graph_handler(
+    dotted_path: str,
+    max_depth: int = 2,
+    timeout_seconds: int = 10,
+    internal_only: bool = True,
+) -> dict:
+    """Get the call graph of a function or module."""
+    try:
+        from .. import get_call_graph
+
+        result = get_call_graph(
+            dotted_path,
+            max_depth=max_depth,
+            timeout_seconds=timeout_seconds,
+            internal_only=internal_only,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def list_api_handler(
+    dotted_path: str,
+    max_depth: int = 5,
+    docstring: bool = False,
+    root_only: bool = False,
+) -> dict:
+    """List the API tree of a module recursively."""
+    try:
+        from .. import list_api
+
+        df = list_api(
+            dotted_path,
+            max_depth=max_depth,
+            docstring=docstring,
+            root_only=root_only,
+        )
+        return {
+            "success": True,
+            "api": df.to_dict(orient="records"),
+            "count": len(df),
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}

scitex/introspect/_members.py

@@ -0,0 +1,155 @@
+#!/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 builtins
+import inspect
+from typing import Literal
+
+from ._resolve import get_type_info, resolve_object
+
+# Save reference to built-in dir before shadowing
+_builtin_dir = builtins.dir
+
+
+def dir(
+    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 = _builtin_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 _builtin_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 q(
+    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?` (quick info).
+
+    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
+    --------
+    >>> q("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,
+    }