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's static type checking.

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.1.1, mccabe: 0.6.1, pycodestyle: 2.5.0, pyflakes: 2.1.1) CPython 3.7.4 on Darwin

Table of Warnings

Function Annotations

Method Annotations

Return Annotations

Type Comments

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 Pipenv to manage dependencies. With your fork cloned to your local machine, you can create a developer environment using:

$ pipenv sync --dev

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 installation script and configuration is also provided to create a pre-commit hook so linting errors aren't committed:

$ pipenv run precommit

Testing

A pytest suite is provided for testing across multiple Python environments via tox:

$ pipenv run test

Coverage

Test coverage is provided by pytest-cov via a pipenv script:

$ pipenv run coverage

When running via pipenv, details on missing coverage is provided in the report to allow the user to generate additional tests for full coverage.

e.g.

----------- coverage: platform win32, python 3.7.4-final-0 -----------
Name                                Stmts   Miss Branch BrPart  Cover   Missing
-------------------------------------------------------------------------------
flake8_annotations\__init__.py        108      0     38      0    99%   164
flake8_annotations\checker.py          57      0     30      0   100%
flake8_annotations\enums.py            15      0      0      0   100%
flake8_annotations\error_codes.py      85      0      0      0   100%
-------------------------------------------------------------------------------
TOTAL                                 265      0     68      0    99%