Repository navigation
Avoid relying on typing.TYPE_CHECKING to the maximum possible extent #468
Description
During investigation of #454 and related doc rendering issues, it has come to my attention that the type checking detection logic does not work well with Sphinx (ex: sphinx-doc/sphinx#13137, sphinx-doc/sphinx#11225).
Independently, Ralf has pointed out that it makes code debugging harder (#463 (comment)).
The idea of having a if TYPE_CHECKING: check is to avoid unnecessary imports or circular imports. If such issues do not exist, we should avoid using it.
Activity
mdboom commentedon Jun 10, 2026
In the process of completing #2061 and getting type checking working as part of pre-commit, it's clear that
TYPE_CHECKINGis still necessary in some cases to avoid circular imports. I agree we should only use it when absolutely necessary, but I don't think there is any way to avoid it fully.The hypothesis that it prevents Sphinx from linking things seems to be untrue.