flake8-typing-only-imports
A Flake8 plugin that identifies which Python imports should be moved into or out of type-checking blocks to improve performance and prevent circular imports.
What is flake8-typing-only-imports?
flake8-type-checking is a Flake8 plugin that helps Python developers manage imports used exclusively for type hinting. It identifies which imports can be moved into `typing.TYPE_CHECKING` blocks to reduce runtime overhead and prevent import circularity issues. The plugin provides actionable error codes to refactor code for better performance and maintainability.
Python developers using type hints who want to optimize import performance, avoid circular imports, and maintain clean codebases, especially those working with large libraries or frameworks like FastAPI, Pydantic, or SQLAlchemy.
Developers choose this plugin because it automates the tedious process of managing type-checking imports, reduces runtime memory usage, and integrates seamlessly with popular Python frameworks to prevent false positives, ensuring reliable and efficient linting.
Overview
Flake8 plugin for managing type-checking imports & forward references.
Use Cases
Best For
- Optimizing Python codebases with heavy libraries like pandas used only for type hints
- Preventing import circularity in large Python projects with interconnected modules
- Enforcing consistent use of TYPE_CHECKING blocks in teams using type hints
- Integrating with FastAPI or Pydantic projects to avoid false linting positives
- Reducing startup time and memory usage by eliminating unnecessary runtime imports
- Automating refactoring of type annotations to use forward references correctly
Not Ideal For
- Projects not using Python type hints at all
- Small, single-file scripts where import optimization has negligible impact
- Teams using linters other than Flake8, such as ruff or pylint
- Codebases targeting Python versions below 3.7, where forward reference features are limited
Pros & Cons
Pros
Scans code to identify imports used only for type hints, providing specific error codes like TC001-TC003 for actionable refactoring, as shown in the pandas example.
Includes dedicated settings for Pydantic, FastAPI, SQLAlchemy, and others to minimize false positives, ensuring accurate linting in complex projects without manual overrides.
Helps refactor code to break import cycles by guarding type-only imports, demonstrated in the detailed circularity example with models A and B.
Eliminates runtime cost of heavy imports like pandas by moving them into TYPE_CHECKING blocks, directly reducing startup time and memory usage.
Cons
Requires managing multiple settings in flake8 config, such as enabling framework support and choosing between TC100/TC200 error ranges, which can be overwhelming for teams.
For FastAPI dependency support, it disables linting for all function annotations to prevent false positives, sacrificing precision for safety as admitted in the README.
Only works with Flake8, so projects using alternative linters like ruff cannot benefit without switching or integrating Flake8 into their workflow.
Frequently Asked Questions
Related Projects
wemake-python-styleguideThe strictest and most opinionated python linter ever!
flake8-annotationsFlake8 Type Annotation Checking
flake8-type-checkingFlake8 plugin for managing type-checking imports & forward references.
flake8-pyiA plugin for Flake8 that provides specializations for type hinting stub files
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.