Merge remote-tracking branch 'upstream/master' into conditional-overloads

Author: cdce8p

.github/workflows/docs.yml

@@ -23,7 +23,7 @@ jobs:
         with:
           python-version: '3.7'
       - name: Install tox
-        run: pip install --upgrade 'setuptools!=50' 'virtualenv<16.7.11' tox==3.20.1
+        run: pip install --upgrade 'setuptools!=50' 'virtualenv>=20.6.0' tox==3.24.5
       - name: Setup tox environment
         run: tox -e ${{ env.TOXENV }} --notest
       - name: Test

.github/workflows/mypy_primer_comment.yml

@@ -42,42 +42,11 @@ jobs:
       - run: |
           cat diff_*.txt | head -c 30000 | tee fulldiff.txt
 
-      # Based on https://github.com/kanga333/comment-hider
-      - name: Hide old comments
-        uses: actions/github-script@v3
-        with:
-          github-token: ${{secrets.GITHUB_TOKEN}}
-          script: |
-            const fs = require('fs')
-
-            const response = await github.issues.listComments({
-              issue_number: fs.readFileSync("pr_number.txt", { encoding: "utf8" }),
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-            })
-            const botCommentIds = response.data
-              .filter(comment => comment.user.login === 'github-actions[bot]')
-              .map(comment => comment.node_id)
-
-            for (const id of botCommentIds) {
-              const resp = await github.graphql(`
-                mutation {
-                  minimizeComment(input: {classifier: OUTDATED, subjectId: "${id}"}) {
-                    minimizedComment {
-                      isMinimized
-                    }
-                  }
-                }
-              `)
-              if (resp.errors) {
-                throw new Error(resp.errors)
-              }
-            }
-
       - name: Post comment
+        id: post-comment
         uses: actions/github-script@v3
         with:
-          github-token: ${{secrets.GITHUB_TOKEN}}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const fs = require('fs')
             const data = fs.readFileSync('fulldiff.txt', { encoding: 'utf8' })
@@ -99,3 +68,11 @@ jobs:
               body
             })
             return prNumber
+
+      - name: Hide old comments
+        # v0.3.0
+        uses: kanga333/comment-hider@bbdf5b562fbec24e6f60572d8f712017428b92e0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          leave_visible: 1
+          issue_number: ${{ steps.post-comment.outputs.result }}

.github/workflows/test.yml

@@ -107,7 +107,7 @@ jobs:
         ./misc/build-debug-python.sh $PYTHONVERSION $PYTHONDIR $VENV
         source $VENV/bin/activate
     - name: Install tox
-      run: pip install --upgrade 'setuptools!=50' 'virtualenv>=20.6.0' tox==3.20.1
+      run: pip install --upgrade 'setuptools!=50' 'virtualenv>=20.6.0' tox==3.24.5
     - name: Compiled with mypyc
       if: ${{ matrix.test_mypyc }}
       run: |

CONTRIBUTING.md

@@ -54,6 +54,12 @@ You can also use `tox` to run tests, for instance:
 tox -e py
 ```
 
+The easiest way to run a single test is:
+```
+pytest -n0 -k 'test_name'
+```
+There's more useful information on writing and running tests [here](test-data/unit/README.md)
+
 ## First time contributors
 
 If you're looking for things to help with, browse our [issue tracker](https://github.com/python/mypy/issues)!
@@ -63,21 +69,24 @@ In particular, look for:
 - [good second issues](https://github.com/python/mypy/labels/good-second-issue)
 - [documentation issues](https://github.com/python/mypy/labels/documentation)
 
-It's also extremely easy to get started contributing to our sister project
-[typeshed](https://github.com/python/typeshed/issues) that provides type stubs
-for libraries. This is a great way to become familiar with type syntax.
-
-If you need help getting started, don't hesitate to ask on
-[gitter](https://gitter.im/python/typing).
+You do not need to ask for permission to work on any of these issues.
+Just fix the issue yourself, [try to add a unit test](#running-tests) and
+[open a pull request](#submitting-changes).
 
 To get help fixing a specific issue, it's often best to comment on the issue
-itself. The more details you provide about what you've tried and where you've
-looked, the easier it will be for you to get help.
+itself. You're much more likely to get help if you provide details about what
+you've tried and where you've looked (maintainers tend to help those who help
+themselves). [gitter](https://gitter.im/python/typing) can also be a good place
+to ask for help.
 
 Interactive debuggers like `pdb` and `ipdb` are really useful for getting
 started with the mypy codebase. This is a
 [useful tutorial](https://realpython.com/python-debugging-pdb/).
 
+It's also extremely easy to get started contributing to our sister project
+[typeshed](https://github.com/python/typeshed/issues) that provides type stubs
+for libraries. This is a great way to become familiar with type syntax.
+
 ## Submitting changes
 
 Even more excellent than a good bug report is a fix for a bug, or the

CREDITS

@@ -11,15 +11,18 @@ Dropbox core team:
 
   Jukka Lehtosalo <[email protected]>
   Ivan Levkivskyi <[email protected]>
+  Jared Hance
 
 Non-Dropbox core team members:
 
   Ethan Smith
   Guido van Rossum <[email protected]>
-  Jelle Zijlstra
+  Jelle Zijlstra <[email protected]>
   Michael J. Sullivan <[email protected]>
   Shantanu Jain
-  Xuanda Yang
+  Xuanda Yang <[email protected]>
+  Jingchen Ye <[email protected]>
+  Nikita Sobolev <[email protected]>
 
 Past Dropbox core team members:
 

docs/source/error_code_list2.rst

@@ -255,3 +255,36 @@ no error in practice. In such case, it might be prudent to annotate ``items: Seq
 This is similar in concept to ensuring that an expression's type implements an expected interface (e.g. ``Sized``),
 except that attempting to invoke an undefined method (e.g. ``__len__``) results in an error,
 while attempting to evaluate an object in boolean context without a concrete implementation results in a truthy value.
+
+
+.. _ignore-without-code:
+
+Check that ``# type: ignore`` include an error code [ignore-without-code]
+-------------------------------------------------------------------------
+
+Warn when a ``# type: ignore`` comment does not specify any error codes.
+This clarifies the intent of the ignore and ensures that only the
+expected errors are silenced.
+
+Example:
+
+.. code-block:: python
+
+    # mypy: enable-error-code ignore-without-code
+
+    class Foo:
+        def __init__(self, name: str) -> None:
+            self.name = name
+
+    f = Foo('foo')
+
+    # This line has a typo that mypy can't help with as both:
+    # - the expected error 'assignment', and
+    # - the unexpected error 'attr-defined'
+    # are silenced.
+    # Error: "type: ignore" comment without error code (consider "type: ignore[attr-defined]" instead)
+    f.nme = 42  # type: ignore
+
+    # This line warns correctly about the typo in the attribute name
+    # Error: "Foo" has no attribute "nme"; maybe "name"?
+    f.nme = 42  # type: ignore[assignment]

docs/source/error_codes.rst

@@ -31,6 +31,10 @@ or config `show_error_codes = True` to display error codes. Error codes are show
    $ mypy --show-error-codes prog.py
    prog.py:1: error: "str" has no attribute "trim"  [attr-defined]
 
+It's also possible to require error codes for ``type: ignore`` comments.
+See :ref:`ignore-without-code<ignore-without-code>` for more information.
+
+
 .. _silence-error-codes:
 
 Silencing errors based on error codes

docs/source/literal_types.rst

@@ -1,7 +1,10 @@
+Literal types and Enums
+=======================
+
 .. _literal_types:
 
 Literal types
-=============
+-------------
 
 Literal types let you indicate that an expression is equal to some specific
 primitive value. For example, if we annotate a variable with type ``Literal["foo"]``,
@@ -369,3 +372,130 @@ whatever type the parameter has. For example, ``Literal[3]`` is treated as a
 subtype of ``int`` and so will inherit all of ``int``'s methods directly. This
 means that ``Literal[3].__add__`` accepts the same arguments and has the same
 return type as ``int.__add__``.
+
+
+Enums
+-----
+
+Mypy has special support for :py:class:`enum.Enum` and its subclasses:
+:py:class:`enum.IntEnum`, :py:class:`enum.Flag`, :py:class:`enum.IntFlag`,
+and :py:class:`enum.StrEnum`.
+
+.. code-block:: python
+
+  from enum import Enum
+
+  class Direction(Enum):
+      up = 'up'
+      down = 'down'
+
+  reveal_type(Direction.up)  # Revealed type is "Literal[Direction.up]?"
+  reveal_type(Direction.down)  # Revealed type is "Literal[Direction.down]?"
+
+You can use enums to annotate types as you would expect:
+
+.. code-block:: python
+
+  class Movement:
+      def __init__(self, direction: Direction, speed: float) -> None:
+          self.direction = direction
+          self.speed = speed
+
+  Movement(Direction.up, 5.0)  # ok
+  Movement('up', 5.0)  # E: Argument 1 to "Movemement" has incompatible type "str"; expected "Direction"
+
+Exhaustive checks
+*****************
+
+Similiar to ``Literal`` types ``Enum`` supports exhaustive checks.
+Let's start with a definition:
+
+.. code-block:: python
+
+  from enum import Enum
+  from typing import NoReturn
+
+  def assert_never(value: NoReturn) -> NoReturn:
+      # This also works in runtime as well:
+      assert False, 'This code should never be reached, got: {0}'.format(value)
+
+  class Direction(Enum):
+      up = 'up'
+      down = 'down'
+
+Now, let's define an exhaustive check:
+
+.. code-block:: python
+
+  def choose_direction(direction: Direction) -> None:
+      if direction is Direction.up:
+          reveal_type(direction)  # N: Revealed type is "Literal[ex.Direction.up]"
+          print('Going up!')
+          return
+      elif direction is Direction.down:
+          print('Down')
+          return
+      assert_never(direction)
+
+And then test that it raises an error when some cases are not covered:
+
+.. code-block:: python
+
+  def choose_direction(direction: Direction) -> None:
+      if direction == Direction.up:
+          print('Going up!')
+          return
+      assert_never(direction)  # E: Argument 1 to "assert_never" has incompatible type "Direction"; expected "NoReturn"
+
+Extra Enum checks
+*****************
+
+Mypy also tries to support special features of ``Enum``
+the same way Python's runtime does.
+
+Extra checks:
+
+- Any ``Enum`` class with values is implicitly :ref:`final <final_attrs>`.
+  This is what happens in CPython:
+
+  .. code-block:: python
+
+    >>> class AllDirection(Direction):
+    ...     left = 'left'
+    ...     right = 'right'
+    Traceback (most recent call last):
+      ...
+    TypeError: Other: cannot extend enumeration 'Some'
+
+  We do the same thing:
+
+  .. code-block:: python
+
+    class AllDirection(Direction):  # E: Cannot inherit from final class "Some"
+        left = 'left'
+        right = 'right'
+
+- All ``Enum`` fields are implictly ``final`` as well.
+
+  .. code-block:: python
+
+    Direction.up = '^'  # E: Cannot assign to final attribute "up"
+
+- All field names are checked to be unique.
+
+  .. code-block:: python
+
+     class Some(Enum):
+        x = 1
+        x = 2  # E: Attempted to reuse member name "x" in Enum definition "Some"
+
+- Base classes have no conflicts and mixin types are correct.
+
+  .. code-block:: python
+
+    class WrongEnum(str, int, enum.Enum):
+        # E: Only a single data type mixin is allowed for Enum subtypes, found extra "int"
+        ...
+
+    class MixinAfterEnum(enum.Enum, Mixin): # E: No base classes are allowed after "enum.Enum"
+        ...

mypy/build.py

@@ -2186,8 +2186,10 @@ def type_checker(self) -> TypeChecker:
         if not self._type_checker:
             assert self.tree is not None, "Internal error: must be called on parsed file only"
             manager = self.manager
-            self._type_checker = TypeChecker(manager.errors, manager.modules, self.options,
-                                             self.tree, self.xpath, manager.plugin)
+            self._type_checker = TypeChecker(
+                manager.errors, manager.modules, self.options,
+                self.tree, self.xpath, manager.plugin,
+            )
         return self._type_checker
 
     def type_map(self) -> Dict[Expression, Type]:
@@ -2369,6 +2371,13 @@ def generate_unused_ignore_notes(self) -> None:
                 self.verify_dependencies(suppressed_only=True)
             self.manager.errors.generate_unused_ignore_errors(self.xpath)
 
+    def generate_ignore_without_code_notes(self) -> None:
+        if self.manager.errors.is_error_code_enabled(codes.IGNORE_WITHOUT_CODE):
+            self.manager.errors.generate_ignore_without_code_errors(
+                self.xpath,
+                self.options.warn_unused_ignores,
+            )
+
 
 # Module import and diagnostic glue
 
@@ -2830,8 +2839,15 @@ def load_graph(sources: List[BuildSource], manager: BuildManager,
             )
             manager.errors.report(
                 -1, -1,
-                "Are you missing an __init__.py? Alternatively, consider using --exclude to "
-                "avoid checking one of them.",
+                "See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules "  # noqa: E501
+                "for more info",
+                severity='note',
+            )
+            manager.errors.report(
+                -1, -1,
+                "Common resolutions include: a) using `--exclude` to avoid checking one of them, "
+                "b) adding `__init__.py` somewhere, c) using `--explicit-package-bases` or "
+                "adjusting MYPYPATH",
                 severity='note'
             )
 
@@ -2905,6 +2921,12 @@ def load_graph(sources: List[BuildSource], manager: BuildManager,
                                 "for more info",
                                 severity='note',
                             )
+                            manager.errors.report(
+                                -1, 0,
+                                "Common resolutions include: a) adding `__init__.py` somewhere, "
+                                "b) using `--explicit-package-bases` or adjusting MYPYPATH",
+                                severity='note',
+                            )
                             manager.errors.raise_error()
 
                         seen_files[newst_path] = newst
@@ -3155,6 +3177,7 @@ def process_stale_scc(graph: Graph, scc: List[str], manager: BuildManager) -> No
                 graph[id].finish_passes()
     for id in stale:
         graph[id].generate_unused_ignore_notes()
+        graph[id].generate_ignore_without_code_notes()
     if any(manager.errors.is_errors_for_file(graph[id].xpath) for id in stale):
         for id in stale:
             graph[id].transitive_error = True