From 58f2629c2c059382d943b2552296e8a09c755316 Mon Sep 17 00:00:00 2001 From: CoprDistGit Date: Mon, 10 Apr 2023 20:12:15 +0000 Subject: automatic import of python-flake8-annotations --- python-flake8-annotations.spec | 752 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 752 insertions(+) create mode 100644 python-flake8-annotations.spec (limited to 'python-flake8-annotations.spec') diff --git a/python-flake8-annotations.spec b/python-flake8-annotations.spec new file mode 100644 index 0000000..173f339 --- /dev/null +++ b/python-flake8-annotations.spec @@ -0,0 +1,752 @@ +%global _empty_manifest_terminate_build 0 +Name: python-flake8-annotations +Version: 3.0.0 +Release: 1 +Summary: Flake8 Type Annotation Checks +License: MIT +URL: https://github.com/sco1/flake8-annotations +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/0d/20/6e9f19f645d4a084351cd38e4b1b4896bddddc92aced9e01fb8a7eaf737c/flake8_annotations-3.0.0.tar.gz +BuildArch: noarch + +Requires: python3-attrs +Requires: python3-flake8 + +%description +# flake8-annotations +[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flake8-annotations/3.0.0?logo=python&logoColor=FFD43B)](https://pypi.org/project/flake8-annotations/) +[![PyPI](https://img.shields.io/pypi/v/flake8-annotations?logo=Python&logoColor=FFD43B)](https://pypi.org/project/flake8-annotations/) +[![PyPI - License](https://img.shields.io/pypi/l/flake8-annotations?color=magenta)](https://github.com/sco1/flake8-annotations/blob/main/LICENSE) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/sco1/flake8-annotations/main.svg)](https://results.pre-commit.ci/latest/github/sco1/flake8-annotations/main) +[![Open in Visual Studio Code](https://img.shields.io/badge/Open%20in-VSCode.dev-blue)](https://github.dev/sco1/flake8-annotations) + +`flake8-annotations` is a plugin for [Flake8](http://flake8.pycqa.org/en/latest/) that detects the absence of [PEP 3107-style](https://www.python.org/dev/peps/pep-3107/) function annotations. + +What this won't do: replace [mypy](http://mypy-lang.org/), check type comments (see: [PEP 484](https://peps.python.org/pep-0484/#type-comments)), check variable annotations (see: [PEP 526](https://www.python.org/dev/peps/pep-0526/)), or respect stub files. + +## Installation +Install from PyPi with your favorite `pip` invocation: + +```bash +$ 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: + + + +```bash +$ flake8 --version +6.0.0 (flake8-annotations: 3.0.0, mccabe: 0.7.0, pycodestyle: 2.10.0, pyflakes: 3.0.1) CPython 3.11.0 on Darwin +``` + + +## Table of Warnings +With the exception of `ANN4xx`-level 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 | + +### Opinionated Warnings +These warnings are disabled by default. +| ID | Description | +|----------|------------------------------------------------------------------------| +| `ANN401` | Dynamically typed expressions (typing.Any) are disallowed.2 | +| `ANN402` | Type comments are disallowed. | + +Use [`extend-select`](https://flake8.pycqa.org/en/latest/user/options.html#cmdoption-flake8-extend-ignore) to enable opinionated warnings without overriding other implicit configurations3. + +**Notes:** +1. See: [PEP 484](https://www.python.org/dev/peps/pep-0484/#annotating-instance-and-class-methods) and [PEP 563](https://www.python.org/dev/peps/pep-0563/) for suggestions on annotating `self` and `cls` arguments +2. See: [Dynamic Typing Caveats](#dynamic-typing-caveats) +3. Common pitfall: the use of [`ignore`](https://flake8.pycqa.org/en/latest/user/options.html#cmdoption-flake8-ignore) will enable all implicitly disabled warnings + +## 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` + +### `--allow-untyped-nested`: `bool` +Suppress all errors for dynamically typed nested 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](https://mypy.readthedocs.io/en/stable/class_basics.html?#annotating-init-methods) for additional details. + +Default: `False` + +### `--dispatch-decorators`: `list[str]` +Comma-separated list of decorators flake8-annotations should consider as dispatch decorators. Linting errors are suppressed for functions decorated with at least one of these functions. + +Decorators are matched based on their attribute name. For example, `"singledispatch"` will match any of the following: + * `import functools; @functools.singledispatch` + * `import functools as ; @.singledispatch` + * `from functools import singledispatch; @singledispatch` + +**NOTE:** Deeper imports, such as `a.b.singledispatch` are not supported. + +See: [Generic Functions](#generic-functions) for additional information. + +Default: `"singledispatch, singledispatchmethod"` + +### `--overload-decorators`: `list[str]` +Comma-separated list of decorators flake8-annotations should consider as [`typing.overload`](https://docs.python.org/3/library/typing.html#typing.overload) decorators. + +Decorators are matched based on their attribute name. For example, `"overload"` will match any of the following: + * `import typing; @typing.overload` + * `import typing as ; @.overload` + * `from typing import overload; @overload` + +**NOTE:** Deeper imports, such as `a.b.overload` are not supported. + +See: [The `typing.overload` Decorator](#the-typingoverload-decorator) for additional information. + +Default: `"overload"` + +### `--allow-star-arg-any` +Suppress `ANN401` for dynamically typed `*args` and `**kwargs`. + +Default: `False` + +## Generic Functions +Per the Python Glossary, a [generic function](https://docs.python.org/3/glossary.html#term-generic-function) is defined as: + +> A function composed of multiple functions implementing the same operation for different types. Which implementation should be used during a call is determined by the dispatch algorithm. + +In the standard library we have some examples of decorators for implementing these generic functions: [`functools.singledispatch`](https://docs.python.org/3/library/functools.html#functools.singledispatch) and [`functools.singledispatchmethod`](https://docs.python.org/3/library/functools.html#functools.singledispatchmethod). In the spirit of the purpose of these decorators, errors for missing annotations for functions decorated with at least one of these are ignored. + +For example, this code: + +```py +import functools + +@functools.singledispatch +def foo(a): + print(a) + +@foo.register +def _(a: list) -> None: + for idx, thing in enumerate(a): + print(idx, thing) +``` + +Will not raise any linting errors for `foo`. + +Decorator(s) to treat as defining generic functions may be specified by the [`--dispatch-decorators`](#--dispatch-decorators-liststr) configuration option. + +## The `typing.overload` Decorator +Per the [`typing`](https://docs.python.org/3/library/typing.html#typing.overload) 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: + +```py +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. + +Decorator(s) to treat as `typing.overload` may be specified by the [`--overload-decorators`](#--overload-decorators-liststr) configuration option. + +## Dynamic Typing Caveats +Support is only provided for the following patterns: + * `from typing import any; foo: Any` + * `import typing; foo: typing.Any` + * `import typing as ; foo: .Any` + +Nested dynamic types (e.g. `typing.Tuple[typing.Any]`) and redefinition (e.g. `from typing import Any as Foo`) will not be identified. + +## Contributing + +### Development Environment +This project uses [Poetry](https://python-poetry.org/) 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: + +```bash +$ 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](https://pre-commit.com) configuration is also provided to create a pre-commit hook so linting errors aren't committed: + +```bash +$ pre-commit install +``` + +### Testing & Coverage +A [pytest](https://docs.pytest.org/en/latest/) suite is provided, with coverage reporting from [pytest-cov](https://github.com/pytest-dev/pytest-cov). A [tox](https://github.com/tox-dev/tox/) configuration is provided to test across all supported versions of Python. Testing will be skipped for Python versions that cannot be found. + +```bash +$ 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. + + + +%package -n python3-flake8-annotations +Summary: Flake8 Type Annotation Checks +Provides: python-flake8-annotations +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-flake8-annotations +# flake8-annotations +[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flake8-annotations/3.0.0?logo=python&logoColor=FFD43B)](https://pypi.org/project/flake8-annotations/) +[![PyPI](https://img.shields.io/pypi/v/flake8-annotations?logo=Python&logoColor=FFD43B)](https://pypi.org/project/flake8-annotations/) +[![PyPI - License](https://img.shields.io/pypi/l/flake8-annotations?color=magenta)](https://github.com/sco1/flake8-annotations/blob/main/LICENSE) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/sco1/flake8-annotations/main.svg)](https://results.pre-commit.ci/latest/github/sco1/flake8-annotations/main) +[![Open in Visual Studio Code](https://img.shields.io/badge/Open%20in-VSCode.dev-blue)](https://github.dev/sco1/flake8-annotations) + +`flake8-annotations` is a plugin for [Flake8](http://flake8.pycqa.org/en/latest/) that detects the absence of [PEP 3107-style](https://www.python.org/dev/peps/pep-3107/) function annotations. + +What this won't do: replace [mypy](http://mypy-lang.org/), check type comments (see: [PEP 484](https://peps.python.org/pep-0484/#type-comments)), check variable annotations (see: [PEP 526](https://www.python.org/dev/peps/pep-0526/)), or respect stub files. + +## Installation +Install from PyPi with your favorite `pip` invocation: + +```bash +$ 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: + + + +```bash +$ flake8 --version +6.0.0 (flake8-annotations: 3.0.0, mccabe: 0.7.0, pycodestyle: 2.10.0, pyflakes: 3.0.1) CPython 3.11.0 on Darwin +``` + + +## Table of Warnings +With the exception of `ANN4xx`-level 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 | + +### Opinionated Warnings +These warnings are disabled by default. +| ID | Description | +|----------|------------------------------------------------------------------------| +| `ANN401` | Dynamically typed expressions (typing.Any) are disallowed.2 | +| `ANN402` | Type comments are disallowed. | + +Use [`extend-select`](https://flake8.pycqa.org/en/latest/user/options.html#cmdoption-flake8-extend-ignore) to enable opinionated warnings without overriding other implicit configurations3. + +**Notes:** +1. See: [PEP 484](https://www.python.org/dev/peps/pep-0484/#annotating-instance-and-class-methods) and [PEP 563](https://www.python.org/dev/peps/pep-0563/) for suggestions on annotating `self` and `cls` arguments +2. See: [Dynamic Typing Caveats](#dynamic-typing-caveats) +3. Common pitfall: the use of [`ignore`](https://flake8.pycqa.org/en/latest/user/options.html#cmdoption-flake8-ignore) will enable all implicitly disabled warnings + +## 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` + +### `--allow-untyped-nested`: `bool` +Suppress all errors for dynamically typed nested 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](https://mypy.readthedocs.io/en/stable/class_basics.html?#annotating-init-methods) for additional details. + +Default: `False` + +### `--dispatch-decorators`: `list[str]` +Comma-separated list of decorators flake8-annotations should consider as dispatch decorators. Linting errors are suppressed for functions decorated with at least one of these functions. + +Decorators are matched based on their attribute name. For example, `"singledispatch"` will match any of the following: + * `import functools; @functools.singledispatch` + * `import functools as ; @.singledispatch` + * `from functools import singledispatch; @singledispatch` + +**NOTE:** Deeper imports, such as `a.b.singledispatch` are not supported. + +See: [Generic Functions](#generic-functions) for additional information. + +Default: `"singledispatch, singledispatchmethod"` + +### `--overload-decorators`: `list[str]` +Comma-separated list of decorators flake8-annotations should consider as [`typing.overload`](https://docs.python.org/3/library/typing.html#typing.overload) decorators. + +Decorators are matched based on their attribute name. For example, `"overload"` will match any of the following: + * `import typing; @typing.overload` + * `import typing as ; @.overload` + * `from typing import overload; @overload` + +**NOTE:** Deeper imports, such as `a.b.overload` are not supported. + +See: [The `typing.overload` Decorator](#the-typingoverload-decorator) for additional information. + +Default: `"overload"` + +### `--allow-star-arg-any` +Suppress `ANN401` for dynamically typed `*args` and `**kwargs`. + +Default: `False` + +## Generic Functions +Per the Python Glossary, a [generic function](https://docs.python.org/3/glossary.html#term-generic-function) is defined as: + +> A function composed of multiple functions implementing the same operation for different types. Which implementation should be used during a call is determined by the dispatch algorithm. + +In the standard library we have some examples of decorators for implementing these generic functions: [`functools.singledispatch`](https://docs.python.org/3/library/functools.html#functools.singledispatch) and [`functools.singledispatchmethod`](https://docs.python.org/3/library/functools.html#functools.singledispatchmethod). In the spirit of the purpose of these decorators, errors for missing annotations for functions decorated with at least one of these are ignored. + +For example, this code: + +```py +import functools + +@functools.singledispatch +def foo(a): + print(a) + +@foo.register +def _(a: list) -> None: + for idx, thing in enumerate(a): + print(idx, thing) +``` + +Will not raise any linting errors for `foo`. + +Decorator(s) to treat as defining generic functions may be specified by the [`--dispatch-decorators`](#--dispatch-decorators-liststr) configuration option. + +## The `typing.overload` Decorator +Per the [`typing`](https://docs.python.org/3/library/typing.html#typing.overload) 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: + +```py +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. + +Decorator(s) to treat as `typing.overload` may be specified by the [`--overload-decorators`](#--overload-decorators-liststr) configuration option. + +## Dynamic Typing Caveats +Support is only provided for the following patterns: + * `from typing import any; foo: Any` + * `import typing; foo: typing.Any` + * `import typing as ; foo: .Any` + +Nested dynamic types (e.g. `typing.Tuple[typing.Any]`) and redefinition (e.g. `from typing import Any as Foo`) will not be identified. + +## Contributing + +### Development Environment +This project uses [Poetry](https://python-poetry.org/) 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: + +```bash +$ 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](https://pre-commit.com) configuration is also provided to create a pre-commit hook so linting errors aren't committed: + +```bash +$ pre-commit install +``` + +### Testing & Coverage +A [pytest](https://docs.pytest.org/en/latest/) suite is provided, with coverage reporting from [pytest-cov](https://github.com/pytest-dev/pytest-cov). A [tox](https://github.com/tox-dev/tox/) configuration is provided to test across all supported versions of Python. Testing will be skipped for Python versions that cannot be found. + +```bash +$ 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. + + + +%package help +Summary: Development documents and examples for flake8-annotations +Provides: python3-flake8-annotations-doc +%description help +# flake8-annotations +[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flake8-annotations/3.0.0?logo=python&logoColor=FFD43B)](https://pypi.org/project/flake8-annotations/) +[![PyPI](https://img.shields.io/pypi/v/flake8-annotations?logo=Python&logoColor=FFD43B)](https://pypi.org/project/flake8-annotations/) +[![PyPI - License](https://img.shields.io/pypi/l/flake8-annotations?color=magenta)](https://github.com/sco1/flake8-annotations/blob/main/LICENSE) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/sco1/flake8-annotations/main.svg)](https://results.pre-commit.ci/latest/github/sco1/flake8-annotations/main) +[![Open in Visual Studio Code](https://img.shields.io/badge/Open%20in-VSCode.dev-blue)](https://github.dev/sco1/flake8-annotations) + +`flake8-annotations` is a plugin for [Flake8](http://flake8.pycqa.org/en/latest/) that detects the absence of [PEP 3107-style](https://www.python.org/dev/peps/pep-3107/) function annotations. + +What this won't do: replace [mypy](http://mypy-lang.org/), check type comments (see: [PEP 484](https://peps.python.org/pep-0484/#type-comments)), check variable annotations (see: [PEP 526](https://www.python.org/dev/peps/pep-0526/)), or respect stub files. + +## Installation +Install from PyPi with your favorite `pip` invocation: + +```bash +$ 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: + + + +```bash +$ flake8 --version +6.0.0 (flake8-annotations: 3.0.0, mccabe: 0.7.0, pycodestyle: 2.10.0, pyflakes: 3.0.1) CPython 3.11.0 on Darwin +``` + + +## Table of Warnings +With the exception of `ANN4xx`-level 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 | + +### Opinionated Warnings +These warnings are disabled by default. +| ID | Description | +|----------|------------------------------------------------------------------------| +| `ANN401` | Dynamically typed expressions (typing.Any) are disallowed.2 | +| `ANN402` | Type comments are disallowed. | + +Use [`extend-select`](https://flake8.pycqa.org/en/latest/user/options.html#cmdoption-flake8-extend-ignore) to enable opinionated warnings without overriding other implicit configurations3. + +**Notes:** +1. See: [PEP 484](https://www.python.org/dev/peps/pep-0484/#annotating-instance-and-class-methods) and [PEP 563](https://www.python.org/dev/peps/pep-0563/) for suggestions on annotating `self` and `cls` arguments +2. See: [Dynamic Typing Caveats](#dynamic-typing-caveats) +3. Common pitfall: the use of [`ignore`](https://flake8.pycqa.org/en/latest/user/options.html#cmdoption-flake8-ignore) will enable all implicitly disabled warnings + +## 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` + +### `--allow-untyped-nested`: `bool` +Suppress all errors for dynamically typed nested 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](https://mypy.readthedocs.io/en/stable/class_basics.html?#annotating-init-methods) for additional details. + +Default: `False` + +### `--dispatch-decorators`: `list[str]` +Comma-separated list of decorators flake8-annotations should consider as dispatch decorators. Linting errors are suppressed for functions decorated with at least one of these functions. + +Decorators are matched based on their attribute name. For example, `"singledispatch"` will match any of the following: + * `import functools; @functools.singledispatch` + * `import functools as ; @.singledispatch` + * `from functools import singledispatch; @singledispatch` + +**NOTE:** Deeper imports, such as `a.b.singledispatch` are not supported. + +See: [Generic Functions](#generic-functions) for additional information. + +Default: `"singledispatch, singledispatchmethod"` + +### `--overload-decorators`: `list[str]` +Comma-separated list of decorators flake8-annotations should consider as [`typing.overload`](https://docs.python.org/3/library/typing.html#typing.overload) decorators. + +Decorators are matched based on their attribute name. For example, `"overload"` will match any of the following: + * `import typing; @typing.overload` + * `import typing as ; @.overload` + * `from typing import overload; @overload` + +**NOTE:** Deeper imports, such as `a.b.overload` are not supported. + +See: [The `typing.overload` Decorator](#the-typingoverload-decorator) for additional information. + +Default: `"overload"` + +### `--allow-star-arg-any` +Suppress `ANN401` for dynamically typed `*args` and `**kwargs`. + +Default: `False` + +## Generic Functions +Per the Python Glossary, a [generic function](https://docs.python.org/3/glossary.html#term-generic-function) is defined as: + +> A function composed of multiple functions implementing the same operation for different types. Which implementation should be used during a call is determined by the dispatch algorithm. + +In the standard library we have some examples of decorators for implementing these generic functions: [`functools.singledispatch`](https://docs.python.org/3/library/functools.html#functools.singledispatch) and [`functools.singledispatchmethod`](https://docs.python.org/3/library/functools.html#functools.singledispatchmethod). In the spirit of the purpose of these decorators, errors for missing annotations for functions decorated with at least one of these are ignored. + +For example, this code: + +```py +import functools + +@functools.singledispatch +def foo(a): + print(a) + +@foo.register +def _(a: list) -> None: + for idx, thing in enumerate(a): + print(idx, thing) +``` + +Will not raise any linting errors for `foo`. + +Decorator(s) to treat as defining generic functions may be specified by the [`--dispatch-decorators`](#--dispatch-decorators-liststr) configuration option. + +## The `typing.overload` Decorator +Per the [`typing`](https://docs.python.org/3/library/typing.html#typing.overload) 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: + +```py +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. + +Decorator(s) to treat as `typing.overload` may be specified by the [`--overload-decorators`](#--overload-decorators-liststr) configuration option. + +## Dynamic Typing Caveats +Support is only provided for the following patterns: + * `from typing import any; foo: Any` + * `import typing; foo: typing.Any` + * `import typing as ; foo: .Any` + +Nested dynamic types (e.g. `typing.Tuple[typing.Any]`) and redefinition (e.g. `from typing import Any as Foo`) will not be identified. + +## Contributing + +### Development Environment +This project uses [Poetry](https://python-poetry.org/) 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: + +```bash +$ 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](https://pre-commit.com) configuration is also provided to create a pre-commit hook so linting errors aren't committed: + +```bash +$ pre-commit install +``` + +### Testing & Coverage +A [pytest](https://docs.pytest.org/en/latest/) suite is provided, with coverage reporting from [pytest-cov](https://github.com/pytest-dev/pytest-cov). A [tox](https://github.com/tox-dev/tox/) configuration is provided to test across all supported versions of Python. Testing will be skipped for Python versions that cannot be found. + +```bash +$ 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. + + + +%prep +%autosetup -n flake8-annotations-3.0.0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-flake8-annotations -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Mon Apr 10 2023 Python_Bot - 3.0.0-1 +- Package Spec generated -- cgit v1.2.3