Introspect Module (stx.introspect)

IPython-like code inspection for exploring Python packages.

Quick Reference

import scitex as stx

# Function signature (like IPython's func?)
stx.introspect.q("scitex.stats.test_ttest_ind")
# → name, signature, parameters, return type

# Full source code (like IPython's func??)
stx.introspect.qq("scitex.stats.test_ttest_ind")
# → complete source with line numbers

# List module members (like enhanced dir())
stx.introspect.dir("scitex.plt", filter="public", kind="functions")

# Recursive API tree
df = stx.introspect.list_api("scitex", max_depth=2)

IPython-Style Shortcuts

  • q(dotted_path) – Signature and parameters (like func?)

  • qq(dotted_path) – Full source code (like func??)

  • dir(dotted_path, filter, kind) – List members with filtering

Filters: "public", "private", "dunder", "all"

Kinds: "functions", "classes", "data", "modules"

Documentation

  • get_docstring(path, format) – Extract docstrings ("raw", "parsed", "summary")

  • get_exports(path) – Get __all__ exports

  • find_examples(path) – Find usage examples in tests/examples

Type Analysis

  • get_type_hints_detailed(path) – Full type annotation analysis

  • get_class_hierarchy(path) – Inheritance tree (MRO + subclasses)

  • get_class_annotations(path) – Class variable annotations

Code Analysis

  • get_imports(path, categorize) – All imports (AST-based, grouped by stdlib/third-party/local)

  • get_dependencies(path, recursive) – Module dependency tree

  • get_call_graph(path, max_depth) – Function call graph (with timeout protection)

API Tree

# Generate full module tree as DataFrame
df = stx.introspect.list_api("scitex", max_depth=3, docstring=True)

API Reference

scitex-introspect — IPython-style introspection for any Python package (standalone).

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

scitex.introspect.q(dotted_path, include_defaults=True, include_annotations=True)[source]

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:

name: str signature: str - Human-readable signature parameters: list[dict] - Detailed parameter info return_annotation: str | None type_info: dict

Return type:

dict

Examples

>>> q("scitex.plt.plot")
{'name': 'plot', 'signature': 'plot(spec: dict, ...) -> dict', ...}
scitex.introspect.qq(dotted_path, max_lines=None, include_decorators=True)[source]

Get the source code of a Python object.

Like IPython’s func?? (full source).

Parameters:

  • dotted_path (str) – Dotted path to the object

  • max_lines (int | None) – Limit output to first N lines (None = no limit)

  • include_decorators (bool) – Include decorator lines

Returns:

source: str file: str - Source file path line_start: int - Starting line number line_count: int - Number of lines type_info: dict

Return type:

dict

scitex.introspect.dir(dotted_path, filter='public', kind=None, include_inherited=False)[source]

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:

members: list[dict] - Each with name, kind, summary count: int type_info: dict

Return type:

dict

scitex.introspect.list_api(module, columns=['Type', 'Name', 'Docstring', 'Depth'], prefix='', max_depth=5, visited=None, docstring=False, tree=True, current_depth=0, print_output=False, skip_depwarnings=True, drop_duplicates=True, root_only=False)[source]

List the API of a module recursively and return as a DataFrame.

Like a recursive dir() that shows the entire module tree.

Example

>>> df = list_api(scitex)
>>> print(df)
   Type           Name                    Docstring  Depth
0    M            scitex  Module description              0
1    F  scitex.some_function  Function description        1
2    C  scitex.SomeClass  Class description               1
...
Parameters:

  • module (Union[str, Any]) – Module to inspect (string name or actual module)

  • columns (List[str]) – Columns to include in output DataFrame

  • prefix (str) – Prefix for nested modules

  • max_depth (int) – Maximum recursion depth

  • visited (Optional[Set[str]]) – Set of visited modules to prevent cycles

  • docstring (bool) – Whether to include docstrings

  • tree (bool) – Whether to display tree structure

  • current_depth (int) – Current recursion depth

  • print_output (bool) – Whether to print results

  • skip_depwarnings (bool) – Whether to skip DeprecationWarnings

  • drop_duplicates (bool) – Whether to remove duplicate module entries

  • root_only (bool) – Whether to show only root-level modules

Returns:

Module structure with specified columns

Return type:

pd.DataFrame

scitex.introspect.get_docstring(dotted_path, format='raw')[source]

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:

docstring: str sections: dict (if format=’parsed’) type_info: dict

Return type:

dict

scitex.introspect.get_exports(dotted_path)[source]

Get the __all__ exports of a module.

Parameters:

dotted_path (str) – Dotted path to the module

Returns:

exports: list[str] - Names in __all__ has_all: bool - Whether __all__ is defined type_info: dict

Return type:

dict

scitex.introspect.find_examples(dotted_path, search_paths=None, max_results=10)[source]

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:

examples: list[dict] - Each with file, line, context count: int

Return type:

dict

scitex.introspect.resolve_object(dotted_path)[source]

Resolve a dotted path to a Python object.

Parameters:

dotted_path (str) – Dotted path like ‘scitex.plt.plot’ or ‘scitex.audio’

Returns:

(resolved_object, error_message) If successful, error_message is None

Return type:

tuple[Any, str | None]

Examples

>>> obj, err = resolve_object("scitex.plt")
>>> obj, err = resolve_object("scitex.audio.speak")
scitex.introspect.get_type_info(obj)[source]

Get type information about an object.

Returns:

type: str - The type name kind: str - ‘module’, ‘class’, ‘function’, ‘method’, ‘property’, ‘data’ module: str - Module where defined qualname: str - Qualified name

Return type:

dict

scitex.introspect.get_class_hierarchy(dotted_path, include_builtins=False, max_depth=10)[source]

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:

mro: list[str] - Method Resolution Order (parent classes) subclasses: list[dict] - Known subclasses (recursive) type_info: dict

Return type:

dict

Examples

>>> get_class_hierarchy("collections.abc.Mapping")
scitex.introspect.get_mro(dotted_path, include_builtins=False)[source]

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:

mro: list[str] - Qualified names in MRO order

Return type:

dict

scitex.introspect.get_type_hints_detailed(dotted_path, include_extras=True)[source]

Get detailed type hint information for a callable or class.

Parameters:

  • dotted_path (str) – Dotted path to the function, method, or class

  • include_extras (bool) – Include typing extras (Annotated metadata, etc.)

Returns:

hints: dict[str, dict] - Parameter name to type info return_hint: dict | None - Return type info type_info: dict

Return type:

dict

Examples

>>> get_type_hints_detailed("json.dumps")
scitex.introspect.get_class_annotations(dotted_path)[source]

Get all annotations for a class (class vars and methods).

Parameters:

dotted_path (str) – Dotted path to the class

Returns:

class_vars: dict - Class variable annotations methods: dict - Method annotations (name -> hints)

Return type:

dict

scitex.introspect.get_imports(dotted_path, categorize=True)[source]

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:

imports: list[dict] - All imports with details categories: dict - Grouped by category (if categorize=True)

Return type:

dict

Examples

>>> get_imports("scitex.audio")
scitex.introspect.get_dependencies(dotted_path, recursive=False, max_depth=3)[source]

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:

dependencies: list[str] - Direct dependencies tree: dict - Dependency tree (if recursive)

Return type:

dict

scitex.introspect.get_call_graph(dotted_path, max_depth=2, timeout_seconds=10, internal_only=True)[source]

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:

calls: list[dict] - Functions this function calls called_by: list[dict] - Functions that call this (if module) graph: dict - Full call graph tree

Return type:

dict

Examples

>>> get_call_graph("scitex.audio.speak")
scitex.introspect.get_function_calls(dotted_path, include_methods=True, include_builtins=False)[source]

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:

calls: list[str] - Names of called functions

Return type:

dict