flake8-typing-only-imports 0.1.12

A flake8 plugin that flags imports exclusively used for type annotations

flake8-typing-only-imports

A flake8 plugin to help you identify which imports to put into type-checking blocks.

Beyond this, it will also help you manage forward references however you would like to.

Installation

pip install flake8-typing-only-imports

Active codes

Code	Description
TYO100	Import should be moved to a type-checking block

Deactivated (by default) codes

Code	Description
TYO101	Third-party import should be moved to a type-checking block
TYO200	Missing 'from __future__ import annotations' import
TYO201	Annotation is wrapped in unnecessary quotes
TYO300	Annotation should be wrapped in quotes
TYO301	Annotation is wrapped in unnecessary quotes

If you wish to activate any of these checks, you need to pass them to flake8's select argument (docs).

TYO101 is deactivated by default, mostly because misplaced third party imports don't carry with it the same level of consequence that local imports can have - they will never lead to import circularity issues. Activating TYO101 will mostly help the initialization time of your app.

Please note, TYO200s and TYO300s are mutually exclusive. Don't activate both series. Read on for an in-depth explanation.

Motivation

Two common issues when annotating large code bases are:

1. Import circularity issues
2. Annotating not-yet-defined structures

These problems are largely solved by two Python features:

1. Type checking blocks

   
   The builtin typing library, as of Python 3.7, provides a TYPE_CHECKING block you can put type annotation imports into (see docs).

   from typing import TYPE_CHECKING
   
   if TYPE_CHECKING:
       # this code is not evaluated at runtime
       from foo import bar
   

2. Forward references
   
   

   When you've got unevaluated imports (in type checking block), or you try to reference not-yet-defined structures, forward references are the answer. They can be used, like this:

   class Foo:
       def bar(self) -> 'Foo':
           return Foo()
   

   And ever since PEP563 was implemented, you also have the option of doing this:

   from __future__ import annotations
   
   class Foo:
       def bar(self) -> Foo:
           return Foo()
   

   See this excellent stackoverflow response explaining forward references, if you'd like more context.

With that said, the aim of this plugin is to automate the management of type annotation imports (type-checking block import management), and keeping track of the forward references that become necessary as a consequence.

As a pre-commit hook

You can run this flake8 plugin as a pre-commit hook:

- repo: https://gitlab.com/pycqa/flake8
  rev: 3.7.8
  hooks:
  - id: flake8
    additional_dependencies: [flake8-typing-only-imports]

Supporting the project

Leave a ⭐️  if this project helped you!

Contributions are always welcome 👏