metapathology¶

metapathology is a stdlib-only diagnostic tool for CPython's import system. It helps answer three questions:

• Which finder located each imported module?
• Where did code change sys.meta_path or sys.path_hooks?
• Which modules were found without going through the normal sys.path search?

It was created to investigate conflicts where one import customization prevents another from seeing a module. The monitor only observes: it never returns a module spec or loads a module itself.

Start here¶

Run a script with the same Python interpreter and environment as the target:

python -m metapathology myscript.py --my-args

Or run an importable module:

python -m metapathology -m pytest tests/

The target runs normally and a diagnostic report is written to standard error when it finishes. See Using metapathology for library integration and lifecycle control.

Guide¶

• Using metapathology — CLI and library workflows
• How it works — module caching, path hooks, and what the monitor records
• Reading the report — sections, finding labels, and investigation order
• Library API — public functions, Monitor, and event records
• Speed and memory use — overhead sources, benchmarks, and capture sizing
• Limitations and resource behavior — observation boundaries and runtime cost
• Development — invariants, checks, and documentation workflow

metapathology supports CPython 3.10 and newer and has no runtime dependencies.