Extract top-level import names from PyPI without requiring local installation

[m-aciek]

Is your feature request related to a problem? Please describe.

Currently, deptry relies on the presence of installed packages in the runtime environment to map declared dependencies to top-level imports. While this avoids installing packages explicitly, it still requires them to be available locally.

Describe the solution you would like

I'd like to suggest an enhancement: allow deptry to extract top-level import names directly from PyPI, without needing the package to be installed. This could be done by querying the PyPI JSON API, downloading the .whl file for a given distribution, and reading the top_level.txt file from its .dist-info directory.

This would enable:

• Analysis of projects in clean or containerized environments,
• Easier integration with CI pipelines where dependency installation is undesired,
• Potential fallback behavior when a dependency is declared but not installed.

Additional context

The top-level imports can be found in top_level.txt within .dist-info inside .whl files hosted on PyPI. This could serve as a lightweight and deterministic way to get the needed information without installing or importing anything.

This idea could also complement or even help automate the package-module-name-map feature, by providing a way to infer unknown mappings programmatically when they’re not explicitly configured.

The mapping would be based on the latest version of each package on PyPI, which should generally be safe, as top-level import names tend to be stable and rarely change across versions.

Would you be open to exploring this as an optional mode or fallback? I’d be happy to contribute ideas or code if this aligns with the project’s direction.