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

scitex/introspect/_call_graph.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_call_graph.py
+
+"""Call graph analysis using AST with timeout protection."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import signal
+from contextlib import contextmanager
+from pathlib import Path
+
+from ._resolve import get_type_info, resolve_object
+
+
+class TimeoutError(Exception):
+    """Raised when operation times out."""
+
+    pass
+
+
+@contextmanager
+def timeout(seconds: int):
+    """Context manager for timeout (Unix only)."""
+
+    def handler(signum, frame):
+        raise TimeoutError(f"Operation timed out after {seconds}s")
+
+    # Only works on Unix
+    try:
+        old_handler = signal.signal(signal.SIGALRM, handler)
+        signal.alarm(seconds)
+        try:
+            yield
+        finally:
+            signal.alarm(0)
+            signal.signal(signal.SIGALRM, old_handler)
+    except (ValueError, AttributeError):
+        # Windows or signal not available - no timeout
+        yield
+
+
+def get_call_graph(
+    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 using static AST analysis.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the function or module
+    max_depth : int
+        Maximum depth to traverse calls
+    timeout_seconds : int
+        Timeout in seconds (0 = no timeout)
+    internal_only : bool
+        Only show calls to functions in the same module
+
+    Returns
+    -------
+    dict
+        calls: list[dict] - Functions this function calls
+        called_by: list[dict] - Functions that call this (if module)
+        graph: dict - Full call graph tree
+
+    Examples
+    --------
+    >>> get_call_graph("scitex.audio.speak")
+    """
+    try:
+        if timeout_seconds > 0:
+            with timeout(timeout_seconds):
+                return _analyze_call_graph(dotted_path, max_depth, internal_only)
+        else:
+            return _analyze_call_graph(dotted_path, max_depth, internal_only)
+    except TimeoutError as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "partial": True,
+        }
+
+
+def _analyze_call_graph(
+    dotted_path: str,
+    max_depth: int,
+    internal_only: bool,
+) -> dict:
+    """Perform the actual call graph analysis."""
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    type_info = get_type_info(obj)
+
+    # Get source file
+    try:
+        source_file = inspect.getfile(obj)
+        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,
+        }
+
+    # Build function index for the module
+    func_index = _build_function_index(tree)
+
+    if inspect.isfunction(obj):
+        # Analyze single function
+        func_name = obj.__name__
+        if func_name not in func_index:
+            return {
+                "success": False,
+                "error": f"Function '{func_name}' not found in source",
+                "type_info": type_info,
+            }
+
+        calls = _get_function_calls(func_index[func_name], internal_only, func_index)
+        called_by = _find_callers(func_name, func_index)
+
+        return {
+            "success": True,
+            "function": func_name,
+            "calls": calls,
+            "call_count": len(calls),
+            "called_by": called_by,
+            "caller_count": len(called_by),
+            "type_info": type_info,
+        }
+
+    elif inspect.ismodule(obj):
+        # Analyze entire module
+        graph = {}
+        for func_name, func_node in func_index.items():
+            calls = _get_function_calls(func_node, internal_only, func_index)
+            graph[func_name] = {
+                "calls": calls,
+                "line": func_node.lineno,
+            }
+
+        return {
+            "success": True,
+            "module": dotted_path,
+            "graph": graph,
+            "function_count": len(graph),
+            "type_info": type_info,
+        }
+
+    else:
+        return {
+            "success": False,
+            "error": "Can only analyze functions or modules",
+            "type_info": type_info,
+        }
+
+
+def _build_function_index(tree: ast.AST) -> dict[str, ast.FunctionDef]:
+    """Build index of all functions in the AST."""
+    index = {}
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            index[node.name] = node
+    return index
+
+
+def _get_function_calls(
+    func_node: ast.FunctionDef,
+    internal_only: bool,
+    func_index: dict,
+) -> list[dict]:
+    """Extract all function calls from a function."""
+    calls = []
+    seen = set()
+
+    for node in ast.walk(func_node):
+        if isinstance(node, ast.Call):
+            call_info = _extract_call_info(node)
+            if call_info and call_info["name"] not in seen:
+                # Filter to internal only if requested
+                if internal_only and call_info["name"] not in func_index:
+                    continue
+                seen.add(call_info["name"])
+                calls.append(call_info)
+
+    return calls
+
+
+def _extract_call_info(node: ast.Call) -> dict | None:
+    """Extract information about a function call."""
+    func = node.func
+
+    if isinstance(func, ast.Name):
+        # Simple call: func()
+        return {
+            "name": func.id,
+            "type": "function",
+            "line": node.lineno,
+        }
+    elif isinstance(func, ast.Attribute):
+        # Method call: obj.method()
+        if isinstance(func.value, ast.Name):
+            return {
+                "name": f"{func.value.id}.{func.attr}",
+                "type": "method",
+                "object": func.value.id,
+                "method": func.attr,
+                "line": node.lineno,
+            }
+        else:
+            return {
+                "name": func.attr,
+                "type": "method",
+                "method": func.attr,
+                "line": node.lineno,
+            }
+
+    return None
+
+
+def _find_callers(
+    func_name: str,
+    func_index: dict[str, ast.FunctionDef],
+) -> list[dict]:
+    """Find all functions that call the given function."""
+    callers = []
+
+    for caller_name, caller_node in func_index.items():
+        if caller_name == func_name:
+            continue
+
+        for node in ast.walk(caller_node):
+            if isinstance(node, ast.Call):
+                call_info = _extract_call_info(node)
+                if call_info and call_info["name"] == func_name:
+                    callers.append(
+                        {
+                            "name": caller_name,
+                            "line": caller_node.lineno,
+                        }
+                    )
+                    break
+
+    return callers
+
+
+def get_function_calls(
+    dotted_path: str,
+    include_methods: bool = True,
+    include_builtins: bool = False,
+) -> dict:
+    """
+    Get just the outgoing calls from a function.
+
+    Simpler version of get_call_graph for quick lookup.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the function
+    include_methods : bool
+        Include method calls (obj.method())
+    include_builtins : bool
+        Include builtin function calls
+
+    Returns
+    -------
+    dict
+        calls: list[str] - Names of called functions
+    """
+    result = get_call_graph(dotted_path, max_depth=1, internal_only=False)
+
+    if not result.get("success"):
+        return result
+
+    calls = result.get("calls", [])
+
+    # Filter
+    filtered = []
+    builtins = {"print", "len", "range", "str", "int", "float", "list", "dict", "set"}
+
+    for call in calls:
+        name = call["name"]
+        if not include_methods and call.get("type") == "method":
+            continue
+        if not include_builtins and name in builtins:
+            continue
+        filtered.append(name)
+
+    return {
+        "success": True,
+        "function": dotted_path,
+        "calls": filtered,
+        "call_count": len(filtered),
+    }

scitex/introspect/_class_hierarchy.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_class_hierarchy.py
+
+"""Class hierarchy analysis utilities."""
+
+from __future__ import annotations
+
+import inspect
+
+from ._resolve import get_type_info, resolve_object
+
+
+def get_class_hierarchy(
+    dotted_path: str,
+    include_builtins: bool = False,
+    max_depth: int = 10,
+) -> dict:
+    """
+    Get the inheritance hierarchy of a class.
+
+    Shows both parent classes (MRO) and known subclasses.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the class (e.g., 'pandas.DataFrame')
+    include_builtins : bool
+        Include builtin classes like object, type in hierarchy
+    max_depth : int
+        Maximum depth for subclass traversal
+
+    Returns
+    -------
+    dict
+        mro: list[str] - Method Resolution Order (parent classes)
+        subclasses: list[dict] - Known subclasses (recursive)
+        type_info: dict
+
+    Examples
+    --------
+    >>> get_class_hierarchy("collections.abc.Mapping")
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    type_info = get_type_info(obj)
+
+    if not inspect.isclass(obj):
+        return {
+            "success": False,
+            "error": f"'{dotted_path}' is not a class",
+            "type_info": type_info,
+        }
+
+    # Get MRO (parent classes)
+    mro = []
+    for cls in inspect.getmro(obj):
+        if not include_builtins and cls.__module__ == "builtins":
+            continue
+        mro.append(
+            {
+                "name": cls.__name__,
+                "module": cls.__module__,
+                "qualname": f"{cls.__module__}.{cls.__name__}",
+            }
+        )
+
+    # Get subclasses recursively
+    subclasses = _get_subclasses_recursive(obj, max_depth, include_builtins)
+
+    return {
+        "success": True,
+        "class": dotted_path,
+        "mro": mro,
+        "mro_count": len(mro),
+        "subclasses": subclasses,
+        "subclass_count": _count_subclasses(subclasses),
+        "type_info": type_info,
+    }
+
+
+def _get_subclasses_recursive(
+    cls: type,
+    max_depth: int,
+    include_builtins: bool,
+    current_depth: int = 0,
+) -> list[dict]:
+    """Recursively get all subclasses."""
+    if current_depth >= max_depth:
+        return []
+
+    result = []
+    try:
+        for sub in cls.__subclasses__():
+            if not include_builtins and sub.__module__ == "builtins":
+                continue
+
+            sub_info = {
+                "name": sub.__name__,
+                "module": sub.__module__,
+                "qualname": f"{sub.__module__}.{sub.__name__}",
+            }
+
+            children = _get_subclasses_recursive(
+                sub, max_depth, include_builtins, current_depth + 1
+            )
+            if children:
+                sub_info["subclasses"] = children
+
+            result.append(sub_info)
+    except Exception:
+        pass
+
+    return result
+
+
+def _count_subclasses(subclasses: list[dict]) -> int:
+    """Count total subclasses including nested."""
+    count = len(subclasses)
+    for sub in subclasses:
+        if "subclasses" in sub:
+            count += _count_subclasses(sub["subclasses"])
+    return count
+
+
+def get_mro(dotted_path: str, include_builtins: bool = False) -> dict:
+    """
+    Get just the Method Resolution Order (parent classes).
+
+    Simpler version of get_class_hierarchy for just parents.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the class
+    include_builtins : bool
+        Include builtin classes
+
+    Returns
+    -------
+    dict
+        mro: list[str] - Qualified names in MRO order
+    """
+    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"}
+
+    mro = []
+    for cls in inspect.getmro(obj):
+        if not include_builtins and cls.__module__ == "builtins":
+            continue
+        mro.append(f"{cls.__module__}.{cls.__name__}")
+
+    return {
+        "success": True,
+        "class": dotted_path,
+        "mro": mro,
+    }

scitex/introspect/_core.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_core.py
+
+"""Core introspection module - re-exports all utilities."""
+
+# Basic introspection
+# Advanced introspection
+from ._call_graph import get_call_graph, get_function_calls
+from ._class_hierarchy import get_class_hierarchy, get_mro
+from ._docstring import get_docstring
+from ._examples import find_examples
+from ._imports import get_dependencies, get_imports
+from ._members import get_exports, list_members
+from ._resolve import get_type_info, resolve_object
+from ._signature import get_signature
+from ._source import get_source
+from ._type_hints import get_class_annotations, get_type_hints_detailed
+
+__all__ = [
+    # Basic
+    "get_signature",
+    "get_docstring",
+    "get_source",
+    "list_members",
+    "get_exports",
+    "find_examples",
+    "resolve_object",
+    "get_type_info",
+    # Advanced - Class hierarchy
+    "get_class_hierarchy",
+    "get_mro",
+    # Advanced - Type hints
+    "get_type_hints_detailed",
+    "get_class_annotations",
+    # Advanced - Imports
+    "get_imports",
+    "get_dependencies",
+    # Advanced - Call graph
+    "get_call_graph",
+    "get_function_calls",
+]

scitex/introspect/_docstring.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/_docstring.py
+
+"""Docstring extraction and parsing utilities."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Literal
+
+from ._resolve import get_type_info, resolve_object
+
+
+def _parse_docstring(docstring: str) -> dict:
+    """Parse numpy/google style docstring into sections."""
+    sections = {
+        "summary": "",
+        "description": "",
+        "parameters": "",
+        "returns": "",
+        "examples": "",
+        "notes": "",
+    }
+
+    if not docstring:
+        return sections
+
+    section_patterns = [
+        (r"Parameters?\s*\n[-=]+", "parameters"),
+        (r"Returns?\s*\n[-=]+", "returns"),
+        (r"Examples?\s*\n[-=]+", "examples"),
+        (r"Notes?\s*\n[-=]+", "notes"),
+        (r"Raises?\s*\n[-=]+", "raises"),
+        (r"See Also\s*\n[-=]+", "see_also"),
+    ]
+
+    lines = docstring.split("\n")
+
+    i = 0
+    summary_lines = []
+    while i < len(lines):
+        line = lines[i].strip()
+        if not line:
+            if summary_lines:
+                break
+        elif any(re.match(p, line, re.IGNORECASE) for p, _ in section_patterns):
+            break
+        else:
+            summary_lines.append(line)
+        i += 1
+
+    sections["summary"] = " ".join(summary_lines)
+
+    current_section = "description"
+    current_content = []
+
+    for line in lines[i:]:
+        matched = False
+        for pattern, section_name in section_patterns:
+            if re.match(pattern, line, re.IGNORECASE):
+                if current_content:
+                    sections[current_section] = "\n".join(current_content).strip()
+                current_section = section_name
+                current_content = []
+                matched = True
+                break
+
+        if not matched:
+            current_content.append(line)
+
+    if current_content:
+        sections[current_section] = "\n".join(current_content).strip()
+
+    return sections
+
+
+def get_docstring(
+    dotted_path: str,
+    format: Literal["raw", "parsed", "summary"] = "raw",
+) -> dict:
+    """
+    Get the docstring of a Python object.
+
+    Parameters
+    ----------
+    dotted_path : str
+        Dotted path to the object
+    format : str
+        'raw' - Return full docstring as-is
+        'parsed' - Parse numpy/google style into sections
+        'summary' - Return only first line/paragraph
+
+    Returns
+    -------
+    dict
+        docstring: str
+        sections: dict (if format='parsed')
+        type_info: dict
+    """
+    obj, error = resolve_object(dotted_path)
+    if error:
+        return {"success": False, "error": error}
+
+    type_info = get_type_info(obj)
+    docstring = inspect.getdoc(obj) or ""
+
+    if format == "summary":
+        lines = docstring.split("\n\n")
+        summary = lines[0].strip() if lines else ""
+        return {
+            "success": True,
+            "docstring": summary,
+            "type_info": type_info,
+        }
+
+    if format == "parsed":
+        sections = _parse_docstring(docstring)
+        return {
+            "success": True,
+            "docstring": docstring,
+            "sections": sections,
+            "type_info": type_info,
+        }
+
+    return {
+        "success": True,
+        "docstring": docstring,
+        "type_info": type_info,
+    }