flake8-annotations 1.2.0

Flake8 Type Annotation Checks

flake8-annotations

flake8-annotations is a plugin for Flake8 that detects the absence of PEP 3107-style function annotations and PEP 484-style type comments (see: Caveats).

What this won't do: Check variable annotations (see: PEP 526), respect stub files, or replace mypy.

Installation

Install from PyPi with your favorite pip invocation:

$ pip install flake8-annotations

It will then be run automatically as part of Flake8.

You can verify it's being picked up by invoking the following in your shell:

$ flake8 --version
3.7.8 (flake8-annotations: 1.2.0, mccabe: 0.6.1, pycodestyle: 2.5.0, pyflakes: 2.1.1) CPython 3.7.4 on Darwin

Table of Warnings

Function Annotations

ID	Description
TYP001	Missing type annotation for function argument
TYP002	Missing type annotation for *args
TYP003	Missing type annotation for **kwargs

Method Annotations

ID	Description
TYP101	Missing type annotation for self in method
TYP102	Missing type annotation for cls in classmethod

Return Annotations

ID	Description
TYP201	Missing return type annotation for public function
TYP202	Missing return type annotation for protected function
TYP203	Missing return type annotation for secret function
TYP204	Missing return type annotation for special method
TYP205	Missing return type annotation for staticmethod
TYP206	Missing return type annotation for classmethod

Type Comments

ID	Description
TYP301	PEP 484 disallows both type annotations and type comments

Configuration Options

--suppress-none-returning: bool

Suppress TYP200-level errors for functions that meet one of the following criteria:

• Contain no return statement, or
• Explicit return statement(s) all return None (explicitly or implicitly).

Default: False

Caveats for PEP 484-style Type Comments

Function type comments

Function type comments are assumed to contain both argument and return type hints

Yes:

# type: (int, int) -> bool

No:

# type: (int, int)

Python cannot parse the latter and will raise SyntaxError: unexpected EOF while parsing

Mixing argument type comments and function type comments

Support is provided for mixing argument and function type comments, provided that the function type comment use an Ellipsis for the arguments.

def foo(
    arg1,  # type: bool
    arg2,  # type: bool
):  # type: (...) -> bool
    pass

Ellipes are ignored by flake8-annotations parser.

Note: If present, function type comments will override any argument type comments.

Partial type comments

Partially type hinted functions are supported

For example:

def foo(arg1, arg2):
    # type: (bool) -> bool
    pass

Will show arg2 as missing a type hint.

def foo(arg1, arg2):
    # type: (..., bool) -> bool
    pass

Will show arg1 as missing a type hint.

Contributing

Please take some time to read through our contributing guidelines before helping us with this project.

Development Environment

This project uses Poetry to manage dependencies. With your fork cloned to your local machine, you can create a developer environment using:

$ poetry install

Note: flake8-annotations is included in the Pipfile as an editable dependency so it will be included when flake8 is invoked in your developer environment.

A pre-commit configuration is also provided to create a pre-commit hook so linting errors aren't committed:

$ pre-commit install

Testing & Coverage

A pytest suite is provided, with coverage reporting from pytest-cov. A tox configuration is provided to test across all supported versions of Python. Testing will be skipped for Python versions that cannot be found.

$ tox

Details on missing coverage, including in the test suite, is provided in the report to allow the user to generate additional tests for full coverage.