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

scitex/introspect/_imports.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_imports.py
+
+"""Import analysis utilities using AST."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+from pathlib import Path
+
+from ._resolve import get_type_info, resolve_object
+
+
+def get_imports(
+    dotted_path: str,
+    categorize: bool = True,
+) -> dict:
+    """
+    Get all imports from a module's source code using AST.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the module
+    categorize : bool
+        Group imports by category (stdlib, third-party, local)
+
+    Returns
+    -------
+    dict
+        imports: list[dict] - All imports with details
+        categories: dict - Grouped by category (if categorize=True)
+
+    Examples
+    --------
+    >>> get_imports("scitex.audio")
+    """
+    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,
+        }
+
+    # Get source file
+    try:
+        source_file = inspect.getfile(obj)
+    except TypeError:
+        return {
+            "success": False,
+            "error": "Cannot get source file (builtin module?)",
+            "type_info": type_info,
+        }
+
+    # Read and parse source
+    try:
+        source = Path(source_file).read_text()
+        tree = ast.parse(source)
+    except Exception as e:
+        return {
+            "success": False,
+            "error": f"Cannot parse source: {e}",
+            "type_info": type_info,
+        }
+
+    imports = _extract_imports(tree)
+
+    result = {
+        "success": True,
+        "module": dotted_path,
+        "source_file": source_file,
+        "imports": imports,
+        "import_count": len(imports),
+        "type_info": type_info,
+    }
+
+    if categorize:
+        result["categories"] = _categorize_imports(imports)
+
+    return result
+
+
+def _extract_imports(tree: ast.AST) -> list[dict]:
+    """Extract all imports from an AST."""
+    imports = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append(
+                    {
+                        "type": "import",
+                        "module": alias.name,
+                        "alias": alias.asname,
+                        "line": node.lineno,
+                    }
+                )
+        elif isinstance(node, ast.ImportFrom):
+            module = node.module or ""
+            level = node.level  # Relative import level
+
+            for alias in node.names:
+                imports.append(
+                    {
+                        "type": "from",
+                        "module": module,
+                        "name": alias.name,
+                        "alias": alias.asname,
+                        "level": level,
+                        "line": node.lineno,
+                    }
+                )
+
+    return imports
+
+
+def _categorize_imports(imports: list[dict]) -> dict:
+    """Categorize imports into stdlib, third-party, local."""
+    import sys
+
+    stdlib_modules = (
+        set(sys.stdlib_module_names)
+        if hasattr(sys, "stdlib_module_names")
+        else _get_stdlib_modules()
+    )
+
+    categories = {
+        "stdlib": [],
+        "third_party": [],
+        "local": [],
+    }
+
+    for imp in imports:
+        module = imp["module"]
+        top_level = module.split(".")[0] if module else ""
+
+        # Relative imports are local
+        if imp.get("level", 0) > 0:
+            categories["local"].append(imp)
+        elif top_level in stdlib_modules:
+            categories["stdlib"].append(imp)
+        else:
+            categories["third_party"].append(imp)
+
+    return categories
+
+
+def _get_stdlib_modules() -> set:
+    """Get stdlib module names for Python < 3.10."""
+    import pkgutil
+
+    stdlib = set()
+    for module in pkgutil.iter_modules():
+        if module.name.startswith("_"):
+            continue
+        try:
+            spec = __import__(module.name).__spec__
+            if spec and spec.origin:
+                if "site-packages" not in spec.origin:
+                    stdlib.add(module.name)
+        except Exception:
+            pass
+
+    # Add common ones that might be missed
+    stdlib.update(
+        [
+            "abc",
+            "ast",
+            "asyncio",
+            "collections",
+            "contextlib",
+            "dataclasses",
+            "datetime",
+            "functools",
+            "inspect",
+            "io",
+            "itertools",
+            "json",
+            "logging",
+            "os",
+            "pathlib",
+            "re",
+            "sys",
+            "typing",
+            "unittest",
+            "warnings",
+        ]
+    )
+
+    return stdlib
+
+
+def get_dependencies(
+    dotted_path: str,
+    recursive: bool = False,
+    max_depth: int = 3,
+) -> dict:
+    """
+    Get module dependencies (what it imports).
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the module
+    recursive : bool
+        Recursively analyze imported modules
+    max_depth : int
+        Maximum recursion depth
+
+    Returns
+    -------
+    dict
+        dependencies: list[str] - Direct dependencies
+        tree: dict - Dependency tree (if recursive)
+    """
+    result = get_imports(dotted_path, categorize=True)
+    if not result.get("success"):
+        return result
+
+    # Get unique module names
+    deps = set()
+    for imp in result["imports"]:
+        module = imp["module"]
+        if module:
+            deps.add(module.split(".")[0])
+
+    result["dependencies"] = sorted(deps)
+    result["dependency_count"] = len(deps)
+
+    if recursive:
+        result["tree"] = _build_dep_tree(dotted_path, max_depth, set())
+
+    return result
+
+
+def _build_dep_tree(
+    module_path: str,
+    max_depth: int,
+    visited: set,
+    current_depth: int = 0,
+) -> dict:
+    """Build dependency tree recursively."""
+    if current_depth >= max_depth or module_path in visited:
+        return {"module": module_path, "truncated": True}
+
+    visited.add(module_path)
+
+    result = {"module": module_path, "imports": []}
+
+    imports_result = get_imports(module_path, categorize=False)
+    if not imports_result.get("success"):
+        return result
+
+    for imp in imports_result.get("imports", []):
+        module = imp["module"]
+        if module and module not in visited:
+            top_level = module.split(".")[0]
+            # Only recurse into non-stdlib
+            if top_level not in _get_stdlib_modules():
+                child = _build_dep_tree(module, max_depth, visited, current_depth + 1)
+                result["imports"].append(child)
+
+    return result

scitex/introspect/_mcp/__init__.py

@@ -0,0 +1,37 @@
+#!/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,
+    # Basic
+    docstring_handler,
+    examples_handler,
+    exports_handler,
+    imports_handler,
+    members_handler,
+    signature_handler,
+    source_handler,
+    type_hints_handler,
+)
+
+__all__ = [
+    # Basic
+    "signature_handler",
+    "docstring_handler",
+    "source_handler",
+    "members_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,208 @@
+#!/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 signature_handler(
+    dotted_path: str,
+    include_defaults: bool = True,
+    include_annotations: bool = True,
+) -> dict:
+    """Get the signature of a function, method, or class."""
+    try:
+        from .. import get_signature
+
+        result = get_signature(
+            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 source_handler(
+    dotted_path: str,
+    max_lines: int | None = None,
+    include_decorators: bool = True,
+) -> dict:
+    """Get the source code of a Python object."""
+    try:
+        from .. import get_source
+
+        result = get_source(
+            dotted_path,
+            max_lines=max_lines,
+            include_decorators=include_decorators,
+        )
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def members_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."""
+    try:
+        from .. import list_members
+
+        result = list_members(
+            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)}

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,
+    }