How to determine the modules available in a PyPI package

Question

Given a PyPI package name, like PyYAML, how can one programmatically determine the modules available within the package (distribution package) that could be imported?

Detail

I'm not specifically interested in PyYAML, it's just a good example of a popular PyPI package which has a different package name (PyYAML) from it's primary module name (yaml) such that you can't easily guess the module name from the package name.

I've seen other answers to questions that sound like this but are different, likely because of a naming collision

• package meaning a python construct allowing for a collection of modules
• package meaning a "Distribution Package", an archive file that contains Python packages, modules, and other resource files that are used to distribute a Release.

My question is about the relationship between distribution packages and the modules within.

Possible Solution Spaces

Areas that seem like they might be fruitful (but which I've not had success with yet) are :

• The pydoc.help function (surfaced as the help built-in) outputs a complete list of all available modules when called as help('modules'). This shows modules that have not been imported but could be. It outputs in a human readable form to stdout, and I've been unable to figure out how the pydoc code enumerates the modules.
  • I could imagine calling this, gathering the module list, installing a new distribution package into a virtualenv with pip programatically, calling it again and diffing the results.
• Progamatically installing a distribution package with pip in order to
  • Iterate through elements of the python path to find modules

Answer 1

My project johnnydep provides exactly this feature:

$ johnnydep --fields=import_names PyYAML
name    import_names
------  --------------
PyYAML  yaml

Note that some distributions export multiple top-level names, some distributions export none at all, and there is not necessarily any obvious relationship between the distribution name (used with a pip install command) and the package name (used with an import statement) - though it is a common convention for them to be matched.

For example, the popular project setuptools exposes three top-level names:

$ johnnydep --fields=import_names setuptools 
name        import_names
----------  ---------------------------------------
setuptools  easy_install, pkg_resources, setuptools

API usage is via attribute access:

>>> from johnnydep.lib import JohnnyDist
>>> jdist = JohnnyDist("setuptools")
>>> jdist.import_names
['easy_install', 'pkg_resources', 'setuptools']

If you are interested to know submodule names, not top-level names, that's possible with stdlib pkgutil, for example:

>>> import pkgutil, requests
>>> [name for finder, name, ispkg in pkgutil.walk_packages(requests.__path__)]
['__version__',
 '_internal_utils',
 'adapters',
 'api',
 'auth',
 'certs',
 'compat',
 'cookies',
 'exceptions',
 'help',
 'hooks',
 'models',
 'packages',
 'sessions',
 'status_codes',
 'structures',
 'utils']