Add a warning for tuple[int] annotations (#410)

Fixes #131

The error code is disabled by default, so as to avoid false positives.
If this PR is merged, I can work on creating a non-blocking
mypy_primer-esque workflow for typeshed (which runs flake8 only on
changed files, with `--extend-select=Y090`, and posts a comment showing
the new errors) to flag potential issues in PRs.

Co-authored-by: Jelle Zijlstra <[email protected]>

Author: AlexWaygood

.flake8

@@ -24,10 +24,10 @@
 #           produces false positives if you're surrounding things with double quotes
 
 [flake8]
+extend-select = B9
 max-line-length = 80
 max-complexity = 12
 noqa-require-code = true
-select = B,C,E,F,W,Y,B9,NQA
 per-file-ignores =
   *.py: B905, B907, B950, E203, E501, W503, W291, W293
   *.pyi: B, E301, E302, E305, E501, E701, E704, W503

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Change Log
 
+## Unreleased
+
+* Introduce Y090, which warns if you have an annotation such as `tuple[int]` or
+  `Tuple[int]`. These mean "a tuple of length 1, in which the sole element is
+  of type `int`". This is sometimes what you want, but more usually you'll want
+  `tuple[int, ...]`, which means "a tuple of arbitrary (possibly 0) length, in
+  which all elements are of type `int`".
+
+  This error code is disabled by default due to the risk of false-positive
+  errors. To enable it, use the `--extend-select=Y090` option.
+
 ## 23.6.0
 
 Features:

ERRORCODES.md

@@ -1,6 +1,6 @@
 ## List of warnings
 
-The following warnings are currently emitted:
+The following warnings are currently emitted by default:
 
 | Code | Description
 |------|-------------
@@ -60,3 +60,18 @@ The following warnings are currently emitted:
 | 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.
 | Y057 | Do not use `typing.ByteString` or `collections.abc.ByteString`. These types have unclear semantics, and are deprecated; use  `typing_extensions.Buffer` or a union such as `bytes \| bytearray \| memoryview` instead. See [PEP 688](https://peps.python.org/pep-0688/) for more details.
+
+## Warnings disabled by default
+
+The following error codes are also provided, but are disabled by default due to
+the risk of false-positive errors. To enable these error codes, use
+`--extend-select={code1,code2,...}` on the command line or in your flake8
+configuration file.
+
+Note that `--extend-select` **will not work** if you have
+`--select` specified on the command line or in your configuration file. We
+recommend only using `--extend-select`, never `--select`.
+
+| Code | Description
+|------|------------
+| Y090 | `tuple[int]` means "a tuple of length 1, in which the sole element is of type `int`". Consider using `tuple[int, ...]` instead, which means "a tuple of arbitrary (possibly 0) length, in which all elements are of type `int`".

pyi.py

@@ -1355,10 +1355,22 @@ def visit_BinOp(self, node: ast.BinOp) -> None:
 
         self._check_union_members(members, is_pep_604_union=True)
 
+    def _Y090_error(self, node: ast.Subscript) -> None:
+        current_code = unparse(node)
+        typ = unparse(node.slice)
+        copied_node = deepcopy(node)
+        new_slice = ast.Tuple(elts=[copied_node.slice, ast.Constant(...)])
+        if sys.version_info >= (3, 9):
+            copied_node.slice = new_slice
+        else:
+            copied_node.slice = ast.Index(new_slice)
+        suggestion = unparse(copied_node)
+        self.error(node, Y090.format(original=current_code, typ=typ, new=suggestion))
+
     def visit_Subscript(self, node: ast.Subscript) -> None:
         subscripted_object = node.value
         subscripted_object_name = _get_name_of_class_if_from_modules(
-            subscripted_object, modules=_TYPING_MODULES
+            subscripted_object, modules=_TYPING_MODULES | {"builtins"}
         )
         self.visit(subscripted_object)
         if subscripted_object_name == "Literal":
@@ -1370,6 +1382,8 @@ def visit_Subscript(self, node: ast.Subscript) -> None:
             self._visit_slice_tuple(node.slice, subscripted_object_name)
         else:
             self.visit(node.slice)
+            if subscripted_object_name in {"tuple", "Tuple"}:
+                self._Y090_error(node)
 
     def _visit_slice_tuple(self, node: ast.Tuple, parent: str | None) -> None:
         if parent == "Union":
@@ -2002,6 +2016,7 @@ def run(self) -> Iterable[Error]:
     def add_options(parser: OptionManager) -> None:
         """This is brittle, there's multiple levels of caching of defaults."""
         parser.parser.set_defaults(filename="*.py,*.pyi")
+        parser.extend_default_ignore(DISABLED_BY_DEFAULT)
         parser.add_option(
             "--no-pyi-aware-file-checker",
             default=False,
@@ -2109,3 +2124,10 @@ def parse_options(options: argparse.Namespace) -> None:
 Y057 = (
     "Y057 Do not use {module}.ByteString, which has unclear semantics and is deprecated"
 )
+Y090 = (
+    'Y090 "{original}" means '
+    '"a tuple of length 1, in which the sole element is of type {typ!r}". '
+    'Perhaps you meant "{new}"?'
+)
+
+DISABLED_BY_DEFAULT = ["Y090"]

tests/disabled_by_default.pyi

@@ -0,0 +1,9 @@
+# This test file checks that disabled-by-default error codes aren't triggered,
+# unless they're explicitly enabled
+from typing import (  # Y022 Use "tuple[Foo, Bar]" instead of "typing.Tuple[Foo, Bar]" (PEP 585 syntax)
+    Tuple,
+)
+
+# These would trigger Y090, but it's disabled by default
+x: tuple[int]
+y: Tuple[str]

tests/single_element_tuples.pyi

@@ -0,0 +1,8 @@
+# flags: --extend-select=Y090
+import builtins
+import typing
+
+a: tuple[int]  # Y090 "tuple[int]" means "a tuple of length 1, in which the sole element is of type 'int'". Perhaps you meant "tuple[int, ...]"?
+b: typing.Tuple[builtins.str]  # Y022 Use "tuple[Foo, Bar]" instead of "typing.Tuple[Foo, Bar]" (PEP 585 syntax)  # Y090 "typing.Tuple[builtins.str]" means "a tuple of length 1, in which the sole element is of type 'builtins.str'". Perhaps you meant "typing.Tuple[builtins.str, ...]"?
+c: tuple[int, ...]
+d: typing.Tuple[builtins.str, builtins.complex]  # Y022 Use "tuple[Foo, Bar]" instead of "typing.Tuple[Foo, Bar]" (PEP 585 syntax)

tests/test_pyi_files.py

@@ -35,12 +35,13 @@ def test_pyi_file(path: str) -> None:
             expected_output += f"{path}:{lineno}: {match.group(1)}{message}\n"
 
     bad_flag_msg = (
-        "--ignore flags in test files override the .flake8 config file. "
-        "Use --extend-ignore instead."
-    )
+        "--{flag} flags in test files override the .flake8 config file. "
+        "Use --extend-{flag} instead."
+    ).format
+
     for flag in flags:
         option = flag.split("=")[0]
-        assert option != "--ignore", bad_flag_msg
+        assert option not in {"--ignore", "--select"}, bad_flag_msg(option[2:])
 
     # Silence DeprecationWarnings from our dependencies (pyflakes, flake8-bugbear, etc.)
     #