importlens 0.1.1

Trustworthy diagnostics for Python imports.

importlens

importlens is a Python library and CLI for trustworthy diagnostics of Python imports.

The current v1 candidate is built to help developers inspect import-time cost, internal import structure, and circular dependencies without overstating certainty or acting like an automatic optimizer.

Problem

Python import issues are easy to feel and hard to inspect.

• CLI tools can feel slow without a clear picture of which imports dominate startup.
• Applications can accumulate tangled internal modules that make import cycles and fragile package structure harder to reason about.
• Raw profiling output exists, but it is hard to connect to package architecture and harder to trust without clear labeling.

importlens aims to combine measured runtime timing with approximate static graph analysis in a way that stays honest about what is known, what is inferred, and what remains uncertain.

Scope

V1 is intentionally small.

• profile: runtime import-time diagnostics for a local target
• graph: static import graph analysis for a local package or path
• cycles: cycle detection from the inferred static graph
• report: a combined human-readable or JSON summary

V1 will not include dashboards, IDE integration, auto-fixes, or deep support for dynamic import systems.

Current Status

Observed in this workspace:

• the current test suite passes locally (49 passed on the latest rerun)
• real-repo hardening runs completed against the pinned validation repositories
• graph and cycles are currently the strongest commands on real package targets
• profile and report remain more environment-sensitive on dependency-heavy repos

This means importlens is already credible as a static diagnostics tool, while the runtime-facing commands should still be treated as narrower and more environment-sensitive.

Installation

For standard use:

pip install importlens

For development and local testing:

python -m venv .venv
.venv\Scripts\activate
pip install -e .[dev]

Commands

importlens graph src/my_package
importlens cycles src/my_package
importlens profile app.py
importlens report app.py

Accepted target forms:

• local script paths such as app.py
• local package directories such as src/my_package
• local module targets such as pkg.module when they can be resolved locally

Example Output

Static graph analysis on a real package target:

importlens graph
target: ...\validation_repos\requests\src\requests
target_type: package
node_count: 18
edge_count: 304
limitations:
- Some imports could not be resolved statically and are reported as unresolved.

Cycle detection on the same target:

importlens cycles
target: ...\validation_repos\requests\src\requests
target_type: package
cycles:
- no cycles found

Runtime profiling on dependency-heavy repos currently fails honestly when the active environment cannot import the target:

error: Runtime profiling failed: ...
ModuleNotFoundError: No module named 'urllib3'

That failure mode is intentional product behavior for v1: importlens does not pretend a runtime profile succeeded when the target cannot actually import.

Validation

The repository includes:

• a product brief in PRODUCT_BRIEF.md
• a design specification in DESIGN_SPEC.md
• fixture packages under tests/fixtures/
• command, analysis, and report tests under tests/
• a real-repo hardening report in REAL_REPO_HARDENING.md
• hardening notes in PHASE7_HARDENING_NOTE.md
• explicit support boundaries in KNOWN_LIMITATIONS.md
• an architecture walkthrough in ARCHITECTURE.md
• an engineering decisions note in ENGINEERING_DECISIONS.md

CLI Target Forms

Accepted target forms for v1 are locked down early so command behavior stays testable:

• local script path, for example app.py
• local package directory, for example src/my_package
• local module target when it can be resolved reliably, for example pkg.module

The CLI should reject:

• URLs
• non-Python files
• missing paths
• ambiguous targets that cannot be resolved cleanly

Known Limitations

• Runtime timing is environment-dependent and should not be treated as a stable benchmark.
• Static graph analysis is approximate and will not fully model dynamic imports or plugin loading.
• Runtime-facing commands currently depend on the target's import environment being available.
• report currently supports script and module targets only; package-directory report support is intentionally deferred until runtime profiling support catches up.

For the current support matrix and empirical hardening results, see KNOWN_LIMITATIONS.md and REAL_REPO_HARDENING.md.

License

importlens is licensed under the MIT License. See LICENSE for details.