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

scitex/gen/__init__.py

@@ -1,15 +1,45 @@
 #!/usr/bin/env python3
-"""Scitex gen module."""
+"""Scitex gen module.
+
+NOTE: This module is being refactored. Many functions are being moved to
+more appropriate locations. For backward compatibility, they are re-exported
+here with deprecation warnings.
+
+Recommended imports:
+- ci -> scitex.stats.descriptive.ci
+- check_host, is_host, verify_host -> scitex.os
+- detect_environment, is_notebook, is_script -> scitex.context
+- list_api -> scitex.introspect
+- run_shellcommand, run_shellscript -> scitex.sh
+- xml2dict, XmlDictConfig, XmlListConfig -> scitex.io
+- title_case -> scitex.str
+- symlink -> scitex.path
+"""
+
+import warnings
+
+
+def _deprecation_warning(old_path, new_path):
+    warnings.warn(
+        f"{old_path} is deprecated, use {new_path} instead",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
+# ci -> scitex.stats.descriptive.ci (with re-export for backward compat)
+from scitex.stats.descriptive import ci
 
 # Optional: DimHandler requires torch
 try:
     from ._DimHandler import DimHandler
 except ImportError:
     DimHandler = None
+# check_host moved to scitex.os (re-export for backward compatibility)
+from scitex.os import check_host, is_host, verify_host
+
 from ._alternate_kwarg import alternate_kwarg
 from ._cache import cache
-from ._check_host import check_host, is_host, verify_host
-from ._ci import ci
 from ._deprecated_close import (
     close as _deprecated_close,
 )
@@ -27,7 +57,9 @@ try:
     from ._embed import embed
 except ImportError:
     embed = None
-from ._inspect_module import inspect_module
+# list_api moved to scitex.introspect (re-export for backward compatibility)
+from scitex.introspect import list_api
+
 from ._is_ipython import is_ipython, is_script
 from ._less import less
 from ._list_packages import list_packages, main
@@ -51,9 +83,11 @@ except ImportError:
     to_nanz = None
     to_z = None
     unbias = None
+# shell functions moved to scitex.sh (re-export for backward compatibility)
+from scitex.sh import run_shellcommand, run_shellscript
+
 from ._paste import paste
 from ._print_config import print_config, print_config_main
-from ._shell import run_shellcommand, run_shellscript
 from ._src import src
 from ._TimeStamper import TimeStamper
 
@@ -62,20 +96,23 @@ start = _deprecated_start
 close = _deprecated_close
 running2finished = _deprecated_running2finished
 
-from ._detect_environment import (
+# environment detection moved to scitex.context (re-export for backward compatibility)
+from scitex.context import (
     detect_environment,
-    get_output_directory,
-    is_notebook,
-)
-from ._get_notebook_path import (
     get_notebook_directory,
+    get_notebook_info_simple,
     get_notebook_name,
     get_notebook_path,
+    get_output_directory,
+    is_notebook,
 )
+
+# title_case moved to scitex.str (re-export for backward compatibility)
+from scitex.str import title_case
+
 from ._symlink import symlink
 from ._symlog import symlog
 from ._title2path import title2path
-from ._title_case import main, title_case
 from ._to_even import to_even
 from ._to_odd import to_odd
 
@@ -99,10 +136,9 @@ except ImportError:
     pass  # Already set to None above
 from ._wrap import wrap
 from ._xml2dict import XmlDictConfig, XmlListConfig, xml2dict
-from .misc import float_linspace
 
 # Import from misc module
-from .misc import connect_nums
+from .misc import connect_nums, float_linspace
 
 __all__ = [
     "ArrayLike",
@@ -122,7 +158,7 @@ __all__ = [
     "dir2npy",
     "embed",
     "float_linspace",
-    "inspect_module",
+    "list_api",
     "is_host",
     "is_ipython",
     "is_script",

scitex/gen/_list_packages.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Time-stamp: "2024-11-03 02:11:54 (ywatanabe)"
 # File: ./scitex_repo/src/scitex/gen/_list_packages.py
 """
@@ -25,8 +24,6 @@ except ImportError:
     # Fallback for older Python versions
     from importlib_metadata import distributions
 
-from ._inspect_module import inspect_module
-
 
 def list_packages(
     max_depth: int = 1,
@@ -80,10 +77,12 @@ def list_packages(
         pkg for pkg in installed_packages if pkg not in safelist
     ]
 
+    from scitex.introspect import list_api
+
     all_dfs = []
     for package_name in installed_packages:
         try:
-            df = inspect_module(
+            df = list_api(
                 package_name,
                 docstring=False,  # Speed up by skipping docstrings
                 print_output=False,
@@ -116,6 +115,7 @@ def main() -> Optional[int]:
 
 if __name__ == "__main__":
     import matplotlib.pyplot as plt
+
     import scitex
 
     CONFIG, sys.stdout, sys.stderr, plt, CC = scitex.session.start(

scitex/introspect/__init__.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/introspect/__init__.py
+
+"""
+Introspection utilities for Python packages.
+
+Provides IPython-like introspection capabilities for any Python package.
+
+IPython-style shortcuts:
+- q: Function/class signature with type hints (like `func?`)
+- qq: Full source code (like `func??`)
+- dir: List attributes/methods (like `dir()`)
+- list_api: Recursive module API tree
+
+Basic Introspection:
+- get_docstring: Docstring extraction with parsing
+- get_exports: Module's __all__ contents
+- find_examples: Find usage examples in tests/examples
+
+Advanced Introspection:
+- get_class_hierarchy: Inheritance tree (MRO + subclasses)
+- get_mro: Method Resolution Order only
+- get_type_hints_detailed: Detailed type annotation analysis
+- get_class_annotations: Class variable and method annotations
+- get_imports: Static import analysis using AST
+- get_dependencies: Module dependency analysis
+- get_call_graph: Function call graph (with timeout protection)
+- get_function_calls: Simple outgoing calls list
+"""
+
+from ._core import (
+    # IPython-style names
+    dir,
+    # Basic
+    find_examples,
+    # Advanced - Call graph
+    get_call_graph,
+    # Advanced - Type hints
+    get_class_annotations,
+    # Advanced - Class hierarchy
+    get_class_hierarchy,
+    # Advanced - Imports
+    get_dependencies,
+    get_docstring,
+    get_exports,
+    get_function_calls,
+    get_imports,
+    get_mro,
+    get_type_hints_detailed,
+    get_type_info,
+    q,
+    qq,
+    resolve_object,
+)
+from ._list_api import list_api
+
+__all__ = [
+    # IPython-style names
+    "q",
+    "qq",
+    "dir",
+    "list_api",
+    # Basic
+    "get_docstring",
+    "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/_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,
+    }