flake8-annotations 2.2.1

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.8.2 (flake8-annotations: 2.2.1, mccabe: 0.6.1, pycodestyle: 5.0.2, pyflakes: 2.2.0) CPython 3.8.2 on Darwin

Table of Warnings

All warnings are enabled by default.

Function Annotations

ID	Description
ANN001	Missing type annotation for function argument
ANN002	Missing type annotation for *args
ANN003	Missing type annotation for **kwargs

Method Annotations

ID	Description
ANN101	Missing type annotation for self in method1
ANN102	Missing type annotation for cls in classmethod1

Return Annotations

ID	Description
ANN201	Missing return type annotation for public function
ANN202	Missing return type annotation for protected function
ANN203	Missing return type annotation for secret function
ANN204	Missing return type annotation for special method
ANN205	Missing return type annotation for staticmethod
ANN206	Missing return type annotation for classmethod

Type Comments

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

Notes:

1. See: PEP 484 and PEP 563 for suggestions on annotating self and cls arguments.

Configuration Options

Some opinionated flags are provided to tailor the linting errors emitted:

--suppress-none-returning: bool

Suppress ANN200-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

--suppress-dummy-args: bool

Suppress ANN000-level errors for dummy arguments, defined as _.

Default: False

--allow-untyped-defs: bool

Suppress all errors for dynamically typed functions. A function is considered dynamically typed if it does not contain any type hints.

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

Ellipses 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 install the project and its dependencies to create a development environment using:

$ poetry install

Note: An editable installation of flake8-annotations in the developer environment is required in order for the plugin to be registered for Flake8. By default, Poetry includes an editable install of the project itself when poetry install is invoked.

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.