Skip to content

TC001, TC002, TC003 - documentation mentions import cycles which is misleading #15552

@DetachHead

Description

@DetachHead

the documentation for these three rules all mention import cycles:

Unused imports add a performance overhead at runtime, and risk creating import cycles. If an import is only used in typing-only contexts, it can instead be imported conditionally under an if TYPE_CHECKING: block to minimize runtime overhead.

for TC002 and TC003, mentioning import cycles isn't relevant because standard library or third party modules will never import from the source code that imported it, so i think the mention of import cycles should be removed from the documentation for these two rules.

for TC001, import cycles are a relevant concern because the imported module is part of your source code and therefore could have a circular dependency on the current file. however it's a common (and dangerous) misconception that import cycles are only an issue at runtime. it almost always means there's a problem with how your project is structured regardless of whether the import is TYPE_CHECKING only so it's misleading to suggest that a TYPE_CHECKING import is a suitable solution. see this discussion for an example.

perhaps the TC001 documentation can include a warning mentioning that TYPE_CHECKING imports are not the best solution to import cycles

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions