flake8-type-checking 0.1.0

A flake8 plugin to flag imports exclusively used for type annotations

flake8-type-checking

Lets you know which imports to put inside type-checking blocks, and helps you manage forward references.

See the typing.TYPE_CHECKING docs for context.

Codes

Primary codes

Code	Description
TCH001	Move import into a type-checking block
TCH101	Move third-party import into a type-checking block
TCH102	Found multiple type checking blocks

Secondary codes

Choose TCHA or TCHB as they are incompatible (but both valid).

Code	Description
TCHA001	Add 'from __future__ import annotations' import
TCHA002	Annotation does not need to be a string literal

Code	Description
TCHB001	Annotation needs to be made into a string literal
TCHB002	Annotation does not need to be a string literal

Rationale

We generally want to use TYPE_CHECKING blocks for imports where we can, to guard against import cycles. An added bonus is that guarded imports are not loaded when you start your app, so theoretically you should get a slight performance boost there as well.

Once imports are guarded, type hints should be treated as forward references. Remaining error codes are there to help manage that, either by telling your to use string literals where needed, or by enabling postponed evaluation of annotations.

The error code series TCHA and TCHB should therefore be considered mutually exclusive, as they represent two different ways of solving the same problem.

See this excellent stackoverflow answer for a quick explanation of forward references.

Installation

pip install flake8-type-checking

Examples

Bad code

models/a.py

from models.b import B

class A(Model):
    def foo(self, b: B): ...

models/b.py

from models.a import A

class B(Model):
    def bar(self, a: A): ...

Will result in these errors

>> a.py: TCH101: Move third-party import 'models.b.B' into a type-checking block
>> b.py: TCH101: Move third-party import 'models.a.A' into a type-checking block

and consequently trigger these errors if imports are purely moved into type-checking block, without proper forward reference handling

>> a.py: TCHA001: Add 'from __future__ import annotations' import
>> b.py: TCHA001: Add 'from __future__ import annotations' import

or

>> a.py: TCHB001: Annotation 'B' needs to be made into a string literal
>> b.py: TCHB001: Annotation 'A' needs to be made into a string literal

Good code

models/a.py

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from models.b import B

class A(Model):
    def foo(self, b: 'B'): ...

models/b.py

# TCHA
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from models.a import A

class B(Model):
    def bar(self, a: A): ...

or

# TCHB
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from models.a import A

class B(Model):
    def bar(self, a: 'A'): ...

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-type-checking ]

Supporting the project

Leave a ✯ if this project helped you!

Contributions are always welcome 👏