autosummary doesn’t report correct module on ImportError

[flying-sheep]

Describe the bug
Import warnings in autosummary mention the same class twice instead of mentioning what actually caused the problem.

To Reproduce
Steps to reproduce the behavior:

1. create a module a.py that imports a nonexistant module b.py

   import b
   
   class AClass: pass

2. document something in module a using autosummary:

   .. autosummary::
   
      a.AClass

Actual behavior

WARNING: [autosummary] failed to import 'a.AClass': no module named a.AClass

Expected behavior

WARNING: [autosummary] failed to import 'a.AClass': no module named b

Environment info

• OS: Linux
• Python version: 3.8
• Sphinx version: 3.1
• Sphinx extensions: sphinx.ext.autosummary

[tk0miya]

WARNING: [autosummary] failed to import 'a.AClass': no module named a.AClass

On my local, the reason of the failure is not shown. How did you get this warning?

At present, autosummary tries to import the target object in many ways.

.. py:module:: foo

.. py:class:: Bar

   .. autosummary::

      baz.qux.quux

For example, the extension tries to import the following modules for the above document:

• foo.bar.baz.qux.quux
• foo.bar.baz.qux (and getattr quux)
• foo.bar.baz (and getattr qux.quux)
• foo.baz.qux.quux
• foo.baz.qux (and getattr quux)
• foo.baz (and getattr qux.quux)
• baz.qux.quux
• baz.qux (and getattr quux)
• baz (and getattr qux.quux)

During this trial, many exceptions like ImportError and AttributeError, etc. is raised. As a result, autosummary does not show the reason of the importing failure. It would be better to show a good warning, but I don't have an idea.

[flying-sheep]

I assume it’s happening here:

sphinx/sphinx/ext/autosummary/generate.py

Lines 406 to 411 in 9fd9ede

	try:
	name, obj, parent, modname = import_by_name(entry.name)
	qualname = name.replace(modname + ".", "")
	except ImportError as e:
	_warn(__('[autosummary] failed to import %r: %s') % (entry.name, e))
	continue

I’m sorry my supposedly reproducible example doesn’t work properly … I’ll see if I can find a working one

[astrojuanlu]

I am experiencing this as well while trying to debug readthedocs/readthedocs.org#8326. I'm very deep into the debugging now, but basically this error shown in the logs:

sphinx.errors.SphinxWarning: [autosummary] failed to import 'd3rlpy.algos.AWAC': no module named d3rlpy.algos.AWAC

is actually caused by this:

(Pdb) l
621  
622             # try first interpret `name` as MODNAME.OBJ
623             modname = '.'.join(name_parts[:-1])
624             if modname:
625                 try:
626  ->                 mod = import_module(modname)
627                     return getattr(mod, name_parts[-1]), mod, modname
628                 except (ImportError, IndexError, AttributeError):
629                     pass
630  
631             # ... then as MODNAME, MODNAME.OBJ1, MODNAME.OBJ1.OBJ2, ...
(Pdb) p import_module(modname)
*** ImportError: (ModuleNotFoundError("No module named 'd3rlpy.dataset'"), 'Traceback (most recent call last):\n  ...')

unrolling the traceback:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/d3rlpy/envs/latest/lib/python3.7/site-packages/sphinx/ext/autodoc/importer.py", line 70, in import_module
    return importlib.import_module(modname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/d3rlpy/envs/latest/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 953, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/src/docs/../d3rlpy/__init__.py", line 6, in <module>
    from . import (
  File "/src/docs/../d3rlpy/algos/__init__.py", line 3, in <module>
    from .awac import AWAC
  File "/src/docs/../d3rlpy/algos/awac.py", line 3, in <module>
    from ..argument_utility import (
  File "/src/docs/../d3rlpy/argument_utility.py", line 6, in <module>
    from .models.encoders import EncoderFactory, create_encoder_factory
  File "/src/docs/../d3rlpy/models/__init__.py", line 1, in <module>
    from . import encoders, optimizers, q_functions
  File "/src/docs/../d3rlpy/models/encoders.py", line 7, in <module>
    from ..torch_utility import Swish
  File "/src/docs/../d3rlpy/torch_utility.py", line 10, in <module>
    from .dataset import TransitionMiniBatch
ModuleNotFoundError: No module named 'd3rlpy.dataset'

Hope I can provide a better reproducer.

[astrojuanlu]

Here is a simpler reproducer: https://github.com/astrojuanlu/sphinx-autosummary-tracebacks

(.venv) $ pip install -r requirements.txt
(.venv) $ python -c "import test_pkg.A; print(test_pkg.A)"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/home/juanlu/Projects/RTD/tmp/sphinx-autosummary-tracebacks/.venv/lib/python3.7/site-packages/test_pkg.py", line 7, in <module>
    import attr  # Do not install to surface problem
ModuleNotFoundError: No module named 'attr'
(.venv) $ make html
Running Sphinx v4.1.1
loading pickled environment... done
[autosummary] generating autosummary for: index.rst
WARNING: [autosummary] failed to import 'test_pkg.A': no module named test_pkg.A
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded, 1 warning.

The HTML pages are in build/html.
(.venv) $ python -m sphinx -W -b html source/ build/html
Running Sphinx v4.1.1
[autosummary] generating autosummary for: index.rst

Warning, treated as error:
[autosummary] failed to import 'test_pkg.A': no module named test_pkg.A

The error (both with and without -W) says no module named test_pkg.A when in fact the problem is that attrs is not installed.

[Pro]

I think the main issue for the "wrong" (not so helpful) error message is, that most of the ImportErrors in the autosummary code are just thrown away.

E.g., in the code snippet above there is:

622             # try first interpret `name` as MODNAME.OBJ
623             modname = '.'.join(name_parts[:-1])
624             if modname:
625                 try:
626  ->                 mod = import_module(modname)
627                     return getattr(mod, name_parts[-1]), mod, modname
628                 except (ImportError, IndexError, AttributeError):
629                     pass

I guess here should not be a pass, but something like storing the exception message into a variable. And if autosummary fails, use that variable value instead of the generic "no module named"

[Pro]

I added a pull request which implements my suggestion to collect the import errors: #9555

[Pro]

This is now solved via #10036. @tk0miya you can close this issue.