For consistency with mypy, it would be nice to have an option/rule that behaved the same way as mypy regarding typing of __init__().

Currently, flake8-annotations always raises a violation if there is no return type annotation.

Mypy, however, raises an error if there are no annotations at all (as this would indicate an untyped function). i.e. If there are any annotations on parameters, then a return type is not needed. The return type is only needed when there are no parameters in order to mark the function as statically typed. e.g. def __init__(self, foo: str): and def __init__(self) -> None: are both correctly typed.

What versioning scheme would make sense for this package?

I'm debating between the following two options:

• SemVer: MAJOR.MINOR.PATCH
• CalVer: YYYY.0M.Micro

I'm leaning towards CalVer. Because this is a utility plugin to flake8 with nothing externally facing or backwards incompatible (flake8 compatibility is handled by version pinning), I'm finding it hard to come up with a meaningful metric to use for incrementing major/minor versions of the package; major, in particular.

One caveat to this would be the addition of error codes that would require the user to adjust their ignore settings, but I think this would be an issue with SemVer as well. This seems pretty simply solved by suffixing the error codes table in the README with something like "introduced in ..."

Describe the bug When an outer function returns None, but a function which is defined within it returns something that isn't None, the outer function is falsly marked with an ANN2** error.

Edit: Note this happens even when suppress-none-returning = True.

To Reproduce Minimal code example to reproduce the behavior:

def foo():
    def bar() -> int:
        return 1

    print(bar())


foo()

When running with --supress-none-returning:

$ flake8 --suppress-none-returning test.py
test.py:1:11: ANN201 Missing return type annotation for public function

Version Information

$ flake8 --version
3.7.9 (flake8-annotations: 2.0.0, flake8-comprehensions: 3.2.2, flake8-print: 3.1.4, flake8_pep3101: 1.2.1, import-order: 0.18.1, mccabe: 0.6.1, pycodestyle: 2.5.0, pyflakes: 2.1.1) CPython 3.8.1 on Linux

As well as your Python version:

$ python -V
Python 3.8.1

Add the ability to process type comments in addition to annotations, per PEP 484. Example:

def some_func(arg1, arg2, arg3=True):
    # type: (Optional[str], int, bool) -> Optional[str]
    ...

Rationale/use cases

• Improves "out of the box" support and encourages migration for projects moving from Python 2 to Python 3
• Projects that don't have annotations for other reasons (compatibility, DSLs, performance)
• Extension modules
• Modules that use annotations for other purposes

Note: mypy supports type comments, so it may have some parsing code that could be adapted.

This PR adds testing, yay! This is my first foray into formal testing with Python so please help me be sure I'm not doing something completely terrible.

Here are the currently targeted points for testing:

• [x] Function parsing
• [x] Argument parsing
• [x] Classification of Function as fully annotated
• [x] Warning classification
• [x] Emitting correct line & column numbers
• [x] Formatting warning message with argument name (where relevant)
• [x] Outputting correct tuple for flake8
• [x] Function and Argument object __str__ and __repr__ methods

Additionally:

• Adds testing to the CI & a blurb in the README
• Adds coverage reporting as a pipenv script.
• Adds coverage reporting to CI
• Replaces the debug string methods for Annotation and Function with proper __str__ and __repr__ methods
• Adds a Dependabot configuration file to limit the scope of the dependency checking to the non-dev dependences. I have enabled Dependabot for this project in order to help with keeping on top of changes to flake8.
• Fixes incorrectly configured flake8-docstrings (see: https://github.com/python-discord/organisation/issues/131)

See: #7 Closes: #16 Closes: #17 Closes: #19

The @property decorator was overlooked when creating the initial parsing logic.

Support for this should be added:

• [x] ClassDecoratorType enum constant
  • For the purposes of this tool, property, getter, setter, and deleter can probably safely be combined into a single PROPERTY constant
• [x] Handling by AST parser
• [x] Add error codes
• [x] Add error classification

Describe the bug

We just upgraded to 2.8.0 and have a bunch of litning errors stemming from code using the Any annotation. It looks like from the docs that those errors are intended to be off by default, but it's unclear from the docs how one would turn them on, and so I can't figure out if there's something we've done to turn them on, or if they're just actually on by default.

Is this a bug, or do we need to just disable this error?

Version Information Please provide the full output of flake8 --version

$ flake8 --version
4.0.0 (flake8-annotations: 2.8.0, flake8-bandit: 3.0.0, flake8-docstrings:
1.6.0, pydocstyle: 6.1.1, flake8_isort: 4.1.1, mccabe: 0.6.1, pycodestyle:
2.8.0, pyflakes: 2.4.0) CPython 3.7.12 on Linux

As well as your Python version:

$ python -V
Python 3.7.12

Description

Introduce warnings checking that collection generics are parametrised (even just by typing.Any).

I'm happy to work on it, but I would like to first hear feedback if this check makes sense, if yes what generics should be covered, should it be disabled by default for backwards compatibility and lastly – what are some good commits that I can follow to see how to implement it.

Rationale/Use Case

I often see people annotate their code with really unhelpful types such as list, typing.List, dict or typing.Dict purely to satisfy flake8-annotations warnings.

The idea is to nudge the developer into considering how their generic will be parametrised.

I.e. this would fail:

def my_fun(data: dict) -> None:
  return

But that would be fine:

from typing import Any

def my_fun(data: dict[Any, Any]) -> None:
  return

Of course, the idea is that this would make the developer consider declaring the type parameters even more precisely, e.g.:

from typing import Any

def my_fun(data: dict[str, Any]) -> None:
  return

Or even:

def my_fun(data: dict[str, int]) -> None:
  return

CC: @flaviojdz – we spoke about it a few months ago!

Description Currently flake8-annotations will report an error if the self or cls parameters are not annotated. It is not clear what flake8-annotations wants from the source code in order not to report these errors, and neither PEP 484 nor PEP 3107 offers any guidance as to how self or cls should be annotated. In fact PEP 484 suggests in Annotating class and instance methods that such annotation is not generally necessary:

In most cases the first argument of class and instance methods does not need to be annotated, and it is assumed to have the type of the containing class for instance methods, and a type object type corresponding to the containing class object for class methods.

This means that the out-of-the-box behaviour of flake8-annotations appears (at least at first glance) contrary to the guidelines of the PEPs it is supposed to be enforcing.

Given that neither PEP 484 nor PEP 3107 offer any general guidance on annotating self or cls parameters, the flake8-annotations README should add some examples of how to handle/avoid these errors.

Rationale/Use Case

Behaviour observed with flake8==3.7.9, flake8-annotations==2.0.1, running on CPython 3.7.6.

The error can be seen with even a very trivial class, e.g.:

class Foo:
    def __call__(self) -> float:
        return 1.0

I'm assuming here that the answer is not something like:

class Foo:
    def __call__(self: "Foo") -> float:
        return 1.0

which works, but is rather boilerplate-y and would make renaming a class very annoying.

I'm also assuming that the answer is not just "suppress that class of errors", e.g. with

flake8 --extend-ignore=ANN101,ANN102

which would seem a bit excessive given that there are probably a subset of cases (e.g. those mentioned in the PEP 484 link above) where one probably does want a self or cls annotation. (If it's possible to suppress ANN101 and 102 and still get validation of those special cases, it would be good to have a clear indication of that.)

Basically, please offer some clear guidance on this, given that the PEPs referred to would suggest that un-annotated self and cls is just fine most of the time, and hence flake8-annotations out-of-the-box behaviour is quite unintuitive.

I'd like to propose for discussion migrating the management of the developer environment from Pipenv to Poetry.

I've created a branch with a complete migration of the project for investigation here: https://github.com/python-discord/flake8-annotations/tree/poetry-adventures

I will state up front that there is no major advantage to making this switch, but rather a collection of minor differences that contribute to what I believe is an overall improvement for the developer. In the fairly recent past PyDis looked into migrating all of the repositories to Poetry, as at the time there was a mix between Pipenv and Poetry utilization. It was decided to unify on Pipenv, as it provides some functionality that's very useful for local development, like pipenv run scripts and support for local .env files when executing these scripts. It also provides the useful check for an up-to-date lock file during deployment for the build to proceed. Poetry's advantages related to building & uploading to PyPI are not useful for most of our repositories since they do not live on PyPI.

Pipenv's deployment-specific advantages

As flake8-annotations is a library, Pipenv's deployment-specific advantages & .env file support are not relevant here.

Poetry's lack of a pipenv run script equivalent

While Poetry does have a poetry run command, it lacks Pipenv's capability for defining scripts in the project configuration and instead is limited to executing the project via defined entry points. While a disadvantage for some of our other repositories that utilize some fairly detailed scripts to reduce developmoent tasks to one-liners, development of flake8-annotations has no need for this enhanced functionality. Both linting (poetry run flake8) and testing (tox) are similarly simply accomplished. poetry run flake8 is also insertable into the pre-commit config, preventing us from having to sync linting dependencies in the config file; we're currently using pipenv run lint to accomplish the same.

Simplification of dependency definition

Currently, project dependencies need to be synced between the Pipfile and setup.py. While we have a CI tool to check for synchronization (pipenv-check), which helps, it only checks for version conflicts and not absolute synchronization. Migrating to Poetry allows us to utilize a singular pyproject.toml file for dependency specifications. As it is a Python standard (ish?) format, it's supported by pip for installation without requiring Poetry as well. As the support landscape expands, things like tox and flake8 would also be able to be migrated into the file as well (tox currently has support but it's as a giant string, which I feel is less readable). This is a pretty significant quality of life advantage over Pipenv.

I have plans to declare black as an explicit dev dependency (it's already run locally), which requires pyproject.toml anyway.

Poetry's build tools

Poetry also provides built-in build tools, allowing for distributions to be built via the poetry built one-liner. While the python setup.py sdist bdist_wheel isn't super challenging, and is run by CI only anyway, it's still a nice simplifying one-liner to have.

Pipenv's future?

With pipenv's transfer of ownership to PyPA, development publically seems to have stalled. While the developers have fairly recently stated that work is progressing & blocked by a myriad of issues, communication has been scarce. Poetry, on the other hand, has a very active development cycle, with a recent 1.0 release & impending addition of a plugin API to support OSS contributions of functionality that is lacking from the core tool.

This repository’s flake8 pre-commit configuration currently utilizes the latest PyPi version of flake8-annotations when building its linting environment rather than the current state of the local repo. This can potentially lead to a result that conflicts with both a manual flake8 invocation and the linting CI pipeline, which utilize the current state of the repo to lint itself.

My research into method(s) to resolve this hasn’t been fruitful. Perhaps linting ourselves is an antipattern or I’m just bad at finding things on the internet, but if there’s no way to solve this then I’m inclined to remove pre-commit completely rather than have this conflict.

Would love to have some opinions and/or leads on this!

As touched on in #92, the current definition of and support for ellipses in partial type comments clashes with guidance provided in PEP 484:

Sometimes you want to specify the return type for a function or method without (yet) specifying the argument types. To support this explicitly, the argument list may be replaced with an ellipsis. Example:

def send_email(address, sender, cc, bcc, subject, body):
    # type: (...) -> bool
    """Send an email message.  Return True if successful."""
    <code>

This plugin currently supports mixing of ellipses and types within the same type comment as a means for partial hinting. For example, from the README:

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

Will show arg1 as missing a type hint.

While technically valid code, this type of notation is ambiguous and causes tools like mypy to error:

error: Ellipses cannot accompany other argument types in function type signature

This issue proposes the addition of an ANN300-level error to lint for this mixing of ellipses, as well as dropping explicit support for these annotations within the framework. This is considered a breaking change and will therefore be included in a major release. The new error may be introduced in a point release for compatibility evaluation, but will remain off by default until a major release.