sphinx-autodoc-typehints: typing.TYPE_CHECKING conditional imports break sphinx doc generation
Hi,
I’ve created a dummy repo highlighting my issue. There is a python module called mymodule and a README.md explaining my full step by step issue…
https://github.com/henryJack/sphinx_issue/blob/master/README.md
Problem
- When using the
sphinx-autodoc-typehintsextension with python 3.5+ typings It fails to build. The error meesage is:
Exception occurred:
File "<string>", line 1, in <module>
NameError: name 'B' is not defined
The full traceback has been saved in C:\Users\HENRY~1.TAN\AppData\Local\Temp\sphinx-err-wnuuyq83.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Procedure to reproduce the problem
Please see https://github.com/henryJack/sphinx_issue/blob/master/README.md
Basically, the problem lies in declaring imports using TYPE_CHECKING
from typing import TYPECHECKING
if TYPE_CHECKING:
from mymodule import MyClass
class NewClass:
def __init__(my_object `MyClass` = MyClass()):
self.object: `MyClass` = myobject
Error logs / results
Exception occurred:
File "<string>", line 1, in <module>
NameError: name 'B' is not defined
The full traceback has been saved in C:\Users\HENRY~1.TAN\AppData\Local\Temp\sphinx-err-wnuuyq83.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Expected results
It breaks the docs generator.
Environment info
- OS: Windows 10
- Python version: 3.6.1
- Sphinx version: latest
About this issue
- Original URL
- State: closed
- Created 7 years ago
- Reactions: 12
- Comments: 22 (1 by maintainers)
Commits related to this issue
- Document pytest plugin - Also add autodoc typing plugin to make typing hints documentation just slightly better. A side effect of agronholm/sphinx-autodoc-typehints#22 is that we have to remove typin... — committed to maroux/hedwig-python by maroux 6 years ago
- Use top-level modules for `if TYPE_CHECKING` Summary: sphinx-autodoc-typehints (https://github.com/agronholm/sphinx-autodoc-typehints) isn't happy with importing specific classes within the condition... — committed to facebook/Ax by kkashin 5 years ago
Well, fix the circular import. Then you won’t even need the
typing.TYPECHECKINGcondition. Running the code normally will not cause ‘B’ to be looked up so it won’t trigger the error.Circular imports for type checking are valid, they don’t need to be fixed
Firstly, thank you agronholm for your work on this module. The current PR seems like a reasonable first fix, and it would be nice to see it merged, but I had the beginnings of another idea. Might it be possible to perform two passes? On the first pass TYPE_CHECKING is False, and on the second True. No circular imports would occur on the second try since the relevant modules would have already executed all the way through and be in sys.modules. Thoughts?
Yes, that would be an acceptable fix. I’m just wondering if it should generate some kind of warning too, so as not to hide any problems.
Wouldn’t it be better though if offending types are just ignored and displayed as strings and not links. Currently, it breaks the whole make docs process. It’s a great library and I would still like to use it
I have just ran into this issue - similar to the closed MR from MyST-Parser.
When is this going to get fixed?
I have created a repository with a fully working example and step by step instructions on how to reproduce the error. https://github.com/henryJack/sphinx_issue/blob/master/README.md
The module in question is here https://github.com/henryJack/sphinx_issue/tree/master/mymodule. Yes, it does contain a circular import (which can happen when you introduce python 3.5 type hinting into the mix). The code is still valid python without it though