ml_switcheroo.discovery.inspector¶

Inspection Engine for Python Packages.

This module provides the ApiInspector, a hybrid static-dynamic analysis tool designed to extract API signatures (functions, classes, and attributes) from Python packages.

It employs a two-stage strategy:

  1. Static Analysis (Griffe): Attempts to parse the source code first. This is safer and provides richer information (like docstrings and parameter names) without executing code.

  2. Runtime Introspection (Inspect): Falls back to importing the module and inspecting live objects. This is necessary for C-extensions or dynamic imports that static analysis misses.

Memory Safety:

Includes recursion safeguards (visited set tracking) and an optional blacklist to prevent infinite loops or memory explosion when traversing circular references in large libraries like PyTorch or TensorFlow.

Classes¶

ApiInspector

A robust inspector for discovering API surfaces of installed libraries.

Module Contents¶

class ml_switcheroo.discovery.inspector.ApiInspector¶

A robust inspector for discovering API surfaces of installed libraries.

_package_cache¶

Cache of statically parsed Griffe trees to avoid re-parsing large packages.

inspect(package_name: str, unsafe_modules: Set[str] | None = None) → Dict[str, Any]¶

Scans a package and returns a flat catalog of its public API.

Attempts static analysis first, then falls back to runtime inspection.

Parameters:

  • package_name – The importable name of the package (e.g. ‘torch’, ‘jax’).

  • unsafe_modules – A set of submodule names to exclude from recursion (e.g., {‘_C’, ‘distributed’}).

Returns:

Dict mapping ‘fully.qualified.name’ -> {metadata_dict}. Metadata dict contains ‘name’, ‘type’, ‘params’, etc.