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

scitex/introspect/_examples.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_examples.py
+
+"""Usage example finding utilities."""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+
+from ._resolve import resolve_object
+
+
+def find_examples(
+    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.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to search for (e.g., 'scitex.plt.plot')
+    search_paths : list[str] | None
+        Paths to search. If None, auto-detect from module location
+    max_results : int
+        Maximum number of examples to return
+
+    Returns
+    -------
+    dict
+        examples: list[dict] - Each with file, line, context
+        count: int
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    name = getattr(obj, "__name__", dotted_path.split(".")[-1])
+
+    if search_paths is None:
+        search_paths = []
+
+        module = dotted_path.split(".")[0]
+        try:
+            mod = importlib.import_module(module)
+            if hasattr(mod, "__file__") and mod.__file__:
+                mod_dir = Path(mod.__file__).parent
+                project_root = mod_dir.parent
+                for subdir in ["tests", "test", "examples", "example"]:
+                    test_dir = project_root / subdir
+                    if test_dir.exists():
+                        search_paths.append(str(test_dir))
+        except ImportError:
+            pass
+
+    if not search_paths:
+        return {
+            "success": True,
+            "examples": [],
+            "count": 0,
+            "message": "No test/example directories found",
+        }
+
+    examples = []
+
+    for search_path in search_paths:
+        path = Path(search_path)
+        if not path.exists():
+            continue
+
+        for py_file in path.rglob("*.py"):
+            try:
+                content = py_file.read_text()
+            except Exception:
+                continue
+
+            if name not in content:
+                continue
+
+            lines = content.split("\n")
+            for i, line in enumerate(lines):
+                if name in line:
+                    start = max(0, i - 2)
+                    end = min(len(lines), i + 3)
+                    context = "\n".join(lines[start:end])
+
+                    examples.append(
+                        {
+                            "file": str(py_file),
+                            "line": i + 1,
+                            "context": context,
+                        }
+                    )
+
+                    if len(examples) >= max_results:
+                        break
+
+            if len(examples) >= max_results:
+                break
+
+        if len(examples) >= max_results:
+            break
+
+    return {
+        "success": True,
+        "examples": examples,
+        "count": len(examples),
+        "search_paths": search_paths,
+    }

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)}