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

Table of Warnings

All warnings are enabled by default.

Function Annotations

Method Annotations

Return Annotations

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

--mypy-init-return: bool

Allow omission of a return type hint for __init__ if at least one argument is annotated. See mypy's documentation for additional details.

Default: False

The typing.overload Decorator

Per the typing documentation:

The @overload decorator allows describing functions and methods that support multiple different combinations of argument types. A series of @overload-decorated definitions must be followed by exactly one non-@overload-decorated definition (for the same function/method).

In the spirit of the purpose of this decorator, errors for missing annotations for non-@overload-decorated functions are ignored if they meet this criteria.

For example, this code:

import typing


@typing.overload
def foo(a: int) -> int:
    ...

def foo(a):
    ...

Will not raise linting errors for missing annotations for the arguments & return of the non-decorated foo definition.

NOTE: If importing directly, the typing.overload decorator will not be recognized if it is imported with an alias (e.g. from typing import overload as please_dont_do_this). Aliasing of the typing module is supported (e.g. import typing as t; @t.overload).

Caveats for PEP 484-style Type Comments

Mixing argument-level and function-level type comments

Support is provided for mixing argument-level and function-level type comments.

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

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

Partial type comments

Partially type hinted functions are supported for non-static class methods.

For example:

class Foo:
    def __init__(self):
        # type: () -> None
        ...

    def bar(self, a):
        # type: (int) -> int
        ...

Will consider bar's self argument as unannotated and use the int type hint for a.

Partial type comments utilizing ellipses as placeholders is also supported:

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.

Deprecation notice: Explicit support for utilization of ellipses as placeholders will be removed in version 3.0. See this issue for more information.

Contributing

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.