Implement flake8-pyi

[JonathanPlasse]

flake8-pyi

Error codes

• Y001 Names of TypeVars, ParamSpecs and TypeVarTuples in stubs should usually start with _. This makes sure you don't accidentally expose names internal to the stub.
• Y002 If test must be a simple comparison against sys.platform or sys.version_info. Stub files support simple conditionals to indicate differences between Python versions or platforms, but type checkers only understand a limited subset of Python syntax, and this warning triggers on conditionals that type checkers will probably not understand.
• Y003 Unrecognized sys.version_info check. Similar, but triggers on some comparisons involving version checks.
• Y004 Version comparison must use only major and minor version. Type checkers like mypy don't know about patch versions of Python (e.g. 3.4.3 versus 3.4.4), only major and minor versions (3.3 versus 3.4). Therefore, version checks in stubs should only use the major and minor versions. If new functionality was introduced in a patch version, pretend that it was there all along.
• Y005 Version comparison must be against a length-n tuple.
• Y006 Use only < and >= for version comparisons. Comparisons involving > and <= may produce unintuitive results when tools do use the full sys.version_info tuple.
• Y007 Unrecognized sys.platform check. Platform checks should be simple string comparisons.
• Y008 Unrecognized platform. To prevent you from typos, we warn if you use a platform name outside a small set of known platforms (e.g. "linux" and "win32").
• Y009 Empty body should contain ..., not pass. This is just a stylistic choice, but it's the one typeshed made.
• Y010 Function body must contain only .... Stub files should not contain code, so function bodies should be empty.
• Y011 All default values for typed function arguments must be .... Type checkers ignore the default value, so the default value is not useful information in a stub file.
• Y012 Class body must not contain pass.
• Y013 Non-empty class body must not contain ....
• Y014 All default values for arguments must be .... A stronger version of Y011 that includes arguments without type annotations.
• Y015 Attribute must not have a default value other than ....
• Y016 Unions shouldn't contain duplicates, e.g. str | str is not allowed.
• Y017 Stubs should not contain assignments with multiple targets or non-name targets.
• Y018 A private TypeVar should be used at least once in the file in which it is defined.
• Y019 Certain kinds of methods should use _typeshed.Self instead of defining custom TypeVars for their return annotation. This check currently applies for instance methods that return self, class methods that return an instance of cls, and __new__ methods.
• Y020 Quoted annotations should never be used in stubs.
• Y021 Docstrings should not be included in stubs.
• Y022 Imports linting: use typing-module aliases to stdlib objects as little as possible (e.g. builtins.list over typing.List, collections.Counter over typing.Counter, etc.). (UP035)
• Y023 Where there is no detriment to backwards compatibility, import objects such as ClassVar and NoReturn from typing rather than typing_extensions.
• Y024 Use typing.NamedTuple instead of collections.namedtuple, as it allows for more precise type inference.
• Y025 Always alias collections.abc.Set when importing it, so as to avoid confusion with builtins.set.
• Y026 Type aliases should be explicitly demarcated with typing.TypeAlias.
• Y027 Same as Y022. Unlike Y022, however, the imports disallowed with this error code are required if you wish to write Python 2-compatible stubs. Switch this error code off in your config file if you support Python 2.
• Y028 Always use class-based syntax for typing.NamedTuple, instead of assignment-based syntax. (UP014)
• Y029 It is almost always redundant to define __str__ or __repr__ in a stub file, as the signatures are almost always identical to object.__str__ and object.__repr__.
• Y030 Union expressions should never have more than one Literal member, as Literal[1] | Literal[2] is semantically identical to Literal[1, 2].
• Y031 TypedDicts should use class-based syntax instead of assignment-based syntax wherever possible. (In situations where this is not possible, such as if a field is a Python keyword or an invalid identifier, this error will not be raised.) (UP013)
• Y032 The second argument of an __eq__ or __ne__ method should usually be annotated with object rather than Any.
• Y033 Do not use type comments (e.g. x = ... # type: int) in stubs, even if the stub supports Python 2. Always use annotations instead (e.g. x: int).
• Y034 Y034 detects common errors where certain methods are annotated as having a fixed return type, despite returning self at runtime. Such methods should be annotated with _typeshed.Self. This check looks for:

  1.  Any in-place BinOp dunder methods (__iadd__, __ior__, etc.) that do not return Self.
  2.  __new__, __enter__ and __aenter__ methods that return the class's name unparameterised.
  3.  __iter__ methods that return Iterator, even if the class inherits directly from Iterator.
  4.  __aiter__ methods that return AsyncIterator, even if the class inherits directly from AsyncIterator.

This check excludes methods decorated with @overload or @AbstractMethod.

• Y035 __all__ and __match_args__ in a stub file should always have values, as these special variables in a .pyi file have identical semantics to __all__ and __match_args__ in a .py file. E.g. write __all__ = ["foo", "bar"] instead of __all__: list[str].
• Y036 Y036 detects common errors in __exit__ and __aexit__ methods. For example, the first argument in an __exit__ method should either be annotated with object or type[BaseException] | None.
• Y037 Use PEP 604 syntax instead of typing.Union and typing.Optional. E.g. use str | int instead of Union[str, int], and use str | None instead of Optional[str]. (UP007)
• Y038 Use from collections.abc import Set as AbstractSet instead of from typing import AbstractSet. Like Y027, this error code should be switched off in your config file if your stubs support Python 2. (UP035)
• Y039 Use str instead of typing.Text. This error code is incompatible with stubs supporting Python 2. (Implemented as UP019.)
• Y040 Never explicitly inherit from object, as all classes implicitly inherit from object in Python 3. This error code is incompatible with stubs supporting Python 2. (Implemented as UP004.)
• Y041 Y041 detects redundant numeric unions. For example, PEP 484 specifies that type checkers should treat int as an implicit subtype of float, so int is redundant in the union int | float. In the same way, int is redundant in the union int | complex, and float is redundant in the union float | complex.
• Y042 Type alias names should use CamelCase rather than snake_case
• Y043 Do not use names ending in "T" for private type aliases. (The "T" suffix implies that an object is a TypeVar.)
• Y044 from __future__ import annotations has no effect in stub files, since type checkers automatically treat stubs as having those semantics.
• Y045 __iter__ methods should never return Iterable[T], as they should always return some kind of iterator.
• Y046 A private Protocol should be used at least once in the file in which it is defined.
• Y047 A private TypeAlias should be used at least once in the file in which it is defined.
• Y048 Function bodies should contain exactly one statement. (Note that if a function body includes a docstring, the docstring counts as a "statement".)
• Y049 A private TypedDict should be used at least once in the file in which it is defined.
• Y050 Prefer typing_extensions.Never over typing.NoReturn for argument annotations. This is a purely stylistic choice in the name of readability.
• Y051 Y051 detect redundant unions between Literal types and builtin supertypes. For example, Literal[5] is redundant in the union int | Literal[5], and Literal[True] is redundant in the union Literal[True] | bool.
• Y052 Y052 disallows assignments to constant values where the assignment does not have a type annotation. For example, x = 0 in the global namespace is ambiguous in a stub, as there are four different types that could be inferred for the variable x: int, Final[int], Literal[0], or Final[Literal[0]]. Enum members are excluded from this check, as are various special assignments such as __all__ and __match_args__.
• Y053 Only string and bytes literals <=50 characters long are permitted.
• Y054 Only numeric literals with a string representation <=10 characters long are permitted.
• Y055 Unions of the form type[X] \| type[Y] can be simplified to type[X \| Y]. Similarly, Union[type[X], type[Y]] can be simplified to type[Union[X, Y]].
• Y056 Do not call methods such as .append(), .extend() or .remove() on __all__. Different type checkers have varying levels of support for calling these methods on __all__. Use += instead, which is known to be supported by all major type checkers.

[SigureMo]

Flake8-pyi currently only works with .pyi files (PyCQA/flake8-pyi#118), it would be great if Ruff could support .py files.

Flake8-pyi author list some rules in qutebrowser/qutebrowser#7098 (comment) that can be easily apply to .py files

In addition, there are some rules that overlap with pyupgrade, such as Y037 and U007.

[charliermarsh]

These are being implemented under the PYI prefix (we tend to avoid single-letter prefixes like Y, since they lead to conflicts).

[sbdchd]

Since opening this issue Y014 and Y011 have changed their behavior to allow some defaults, do you think we should mirror the new behavior?

PyCQA/flake8-pyi#326
PyCQA/flake8-pyi#316

[charliermarsh]

@sbdchd - Yeah I'd vote to mirror their behavior.