Merge branch 'typed-dict-in-type-narrowing' of https://github.com/ikonst/mypy into typed-dict-in-type-narrowing

Author: ikonst

.github/workflows/test.yml

@@ -64,7 +64,7 @@ jobs:
           toxenv: py
           tox_extra_args: "-n 2"
         - name: Test suite with py311-ubuntu, mypyc-compiled
-          python: '3.11-dev'
+          python: '3.11'
           arch: x64
           os: ubuntu-latest
           toxenv: py

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.6.0  # must match test-requirements.txt
+    rev: 22.10.0  # must match test-requirements.txt
     hooks:
       - id: black
   - repo: https://github.com/pycqa/isort
@@ -12,5 +12,5 @@ repos:
     hooks:
       - id: flake8
         additional_dependencies:
-          - flake8-bugbear==22.8.23  # must match test-requirements.txt
+          - flake8-bugbear==22.9.23  # must match test-requirements.txt
           - flake8-noqa==1.2.9       # must match test-requirements.txt

docs/source/cheat_sheet_py3.rst

@@ -34,39 +34,45 @@ Useful built-in types
 
 .. code-block:: python
 
-   from typing import List, Set, Dict, Tuple, Optional
-
    # For most types, just use the name of the type
    x: int = 1
    x: float = 1.0
    x: bool = True
    x: str = "test"
    x: bytes = b"test"
 
-   # For collections, the type of the collection item is in brackets
-   # (Python 3.9+)
+   # For collections on Python 3.9+, the type of the collection item is in brackets
    x: list[int] = [1]
    x: set[int] = {6, 7}
 
-   # In Python 3.8 and earlier, the name of the collection type is
-   # capitalized, and the type is imported from the 'typing' module
-   x: List[int] = [1]
-   x: Set[int] = {6, 7}
-
    # For mappings, we need the types of both keys and values
    x: dict[str, float] = {"field": 2.0}  # Python 3.9+
-   x: Dict[str, float] = {"field": 2.0}
 
    # For tuples of fixed size, we specify the types of all the elements
    x: tuple[int, str, float] = (3, "yes", 7.5)  # Python 3.9+
-   x: Tuple[int, str, float] = (3, "yes", 7.5)
 
    # For tuples of variable size, we use one type and ellipsis
    x: tuple[int, ...] = (1, 2, 3)  # Python 3.9+
+
+   # On Python 3.8 and earlier, the name of the collection type is
+   # capitalized, and the type is imported from the 'typing' module
+   from typing import List, Set, Dict, Tuple
+   x: List[int] = [1]
+   x: Set[int] = {6, 7}
+   x: Dict[str, float] = {"field": 2.0}
+   x: Tuple[int, str, float] = (3, "yes", 7.5)
    x: Tuple[int, ...] = (1, 2, 3)
 
-   # Use Optional[] for values that could be None
-   x: Optional[str] = some_function()
+   from typing import Union, Optional
+
+   # On Python 3.10+, use the | operator when something could be one of a few types
+   x: list[int | str] = [3, 5, "test", "fun"]  # Python 3.10+
+   # On earlier versions, use Union
+   x: list[Union[int, str]] = [3, 5, "test", "fun"]
+
+   # Use Optional[X] for a value that could be None
+   # Optional[X] is the same as X | None or Union[X, None]
+   x: Optional[str] = "something" if some_condition() else None
    # Mypy understands a value can't be None in an if-statement
    if x is not None:
        print(x.upper())
@@ -89,9 +95,10 @@ Functions
    def plus(num1: int, num2: int) -> int:
        return num1 + num2
 
-   # Add default value for an argument after the type annotation
-   def f(num1: int, my_float: float = 3.5) -> float:
-       return num1 + my_float
+   # If a function does not return a value, use None as the return type
+   # Default value for an argument goes after the type annotation
+   def show(value: str, excitement: int = 10) -> None:
+       print(value + "!" * excitement)
 
    # This is how you annotate a callable (function) value
    x: Callable[[int, float], float] = f
@@ -124,13 +131,61 @@ Functions
    quux(3, 5)  # error: Too many positional arguments for "quux"
    quux(x=3, y=5)  # error: Unexpected keyword argument "x" for "quux"
 
-   # This makes each positional arg and each keyword arg a "str"
+   # This says each positional arg and each keyword arg is a "str"
    def call(self, *args: str, **kwargs: str) -> str:
        reveal_type(args)  # Revealed type is "tuple[str, ...]"
        reveal_type(kwargs)  # Revealed type is "dict[str, str]"
        request = make_request(*args, **kwargs)
        return self.do_api_query(request)
 
+Classes
+*******
+
+.. code-block:: python
+
+   class MyClass:
+       # You can optionally declare instance variables in the class body
+       attr: int
+       # This is an instance variable with a default value
+       charge_percent: int = 100
+
+       # The "__init__" method doesn't return anything, so it gets return
+       # type "None" just like any other method that doesn't return anything
+       def __init__(self) -> None:
+           ...
+
+       # For instance methods, omit type for "self"
+       def my_method(self, num: int, str1: str) -> str:
+           return num * str1
+
+   # User-defined classes are valid as types in annotations
+   x: MyClass = MyClass()
+
+   # You can also declare the type of an attribute in "__init__"
+   class Box:
+       def __init__(self) -> None:
+           self.items: list[str] = []
+
+   # You can use the ClassVar annotation to declare a class variable
+   class Car:
+       seats: ClassVar[int] = 4
+       passengers: ClassVar[list[str]]
+
+   # If you want dynamic attributes on your class, have it
+   # override "__setattr__" or "__getattr__":
+   # - "__getattr__" allows for dynamic access to names
+   # - "__setattr__" allows for dynamic assignment to names
+   class A:
+       # This will allow assignment to any A.x, if x is the same type as "value"
+       # (use "value: Any" to allow arbitrary types)
+       def __setattr__(self, name: str, value: int) -> None: ...
+
+       # This will allow access to any A.x, if x is compatible with the return type
+       def __getattr__(self, name: str) -> int: ...
+
+   a.foo = 42  # Works
+   a.bar = 'Ex-parrot'  # Fails type checking
+
 When you're puzzled or when things are complicated
 **************************************************
 
@@ -143,9 +198,6 @@ When you're puzzled or when things are complicated
    # message with the type; remove it again before running the code.
    reveal_type(1)  # Revealed type is "builtins.int"
 
-   # Use Union when something could be one of a few types
-   x: list[Union[int, str]] = [3, 5, "test", "fun"]
-
    # If you initialize a variable with an empty container or "None"
    # you may have to help mypy a bit by providing an explicit type annotation
    x: list[str] = []
@@ -154,6 +206,8 @@ When you're puzzled or when things are complicated
    # Use Any if you don't know the type of something or it's too
    # dynamic to write a type for
    x: Any = mystery_function()
+   # Mypy will let you do anything with x!
+   x.whatever() * x["you"] + x("want") - any(x) and all(x) is super  # no errors
 
    # Use a "type: ignore" comment to suppress errors on a given line,
    # when your code confuses mypy or runs into an outright bug in mypy.
@@ -216,56 +270,6 @@ that are common in idiomatic Python are standardized.
 
 You can even make your own duck types using :ref:`protocol-types`.
 
-Classes
-*******
-
-.. code-block:: python
-
-   class MyClass:
-       # You can optionally declare instance variables in the class body
-       attr: int
-       # This is an instance variable with a default value
-       charge_percent: int = 100
-
-       # The "__init__" method doesn't return anything, so it gets return
-       # type "None" just like any other method that doesn't return anything
-       def __init__(self) -> None:
-           ...
-
-       # For instance methods, omit type for "self"
-       def my_method(self, num: int, str1: str) -> str:
-           return num * str1
-
-   # User-defined classes are valid as types in annotations
-   x: MyClass = MyClass()
-
-   # You can use the ClassVar annotation to declare a class variable
-   class Car:
-       seats: ClassVar[int] = 4
-       passengers: ClassVar[list[str]]
-
-   # You can also declare the type of an attribute in "__init__"
-   class Box:
-       def __init__(self) -> None:
-           self.items: list[str] = []
-
-   # If you want dynamic attributes on your class, have it override "__setattr__"
-   # or "__getattr__" in a stub or in your source code.
-   #
-   # "__setattr__" allows for dynamic assignment to names
-   # "__getattr__" allows for dynamic access to names
-   class A:
-       # This will allow assignment to any A.x, if x is the same type as "value"
-       # (use "value: Any" to allow arbitrary types)
-       def __setattr__(self, name: str, value: int) -> None: ...
-
-       # This will allow access to any A.x, if x is compatible with the return type
-       def __getattr__(self, name: str) -> int: ...
-
-   a.foo = 42  # Works
-   a.bar = 'Ex-parrot'  # Fails type checking
-
-
 Coroutines and asyncio
 **********************
 
@@ -290,11 +294,7 @@ Miscellaneous
 .. code-block:: python
 
    import sys
-   import re
-   from typing import Match, IO
-
-   # "typing.Match" describes regex matches from the re module
-   x: Match[str] = re.match(r'[0-9]+', "15")
+   from typing import IO
 
    # Use IO[] for functions that should accept or return any
    # object that comes from an open() call (IO[] does not
@@ -309,7 +309,7 @@ Miscellaneous
 
    # Forward references are useful if you want to reference a class before
    # it is defined
-   def f(foo: A) -> int:  # This will fail
+   def f(foo: A) -> int:  # This will fail at runtime with 'A' is not defined
        ...
 
    class A:

docs/source/existing_code.rst

@@ -168,6 +168,8 @@ fraction of production network requests.  This clearly requires more
 care, as type collection could impact the reliability or the
 performance of your service.
 
+.. _getting-to-strict:
+
 Introduce stricter options
 --------------------------
 
@@ -181,7 +183,7 @@ An excellent goal to aim for is to have your codebase pass when run against ``my
 This basically ensures that you will never have a type related error without an explicit
 circumvention somewhere (such as a ``# type: ignore`` comment).
 
-The following config is equivalent to ``--strict``:
+The following config is equivalent to ``--strict`` (as of mypy 0.990):
 
 .. code-block:: text
 

docs/source/extending_mypy.rst

@@ -155,23 +155,9 @@ When analyzing this code, mypy will call ``get_type_analyze_hook("lib.Vector")``
 so the plugin can return some valid type for each variable.
 
 **get_function_hook()** is used to adjust the return type of a function call.
-This is a good choice if the return type of some function depends on *values*
-of some arguments that can't be expressed using literal types (for example
-a function may return an ``int`` for positive arguments and a ``float`` for
-negative arguments). This hook will be also called for instantiation of classes.
-For example:
-
-.. code-block:: python
-
-   from contextlib import contextmanager
-   from typing import TypeVar, Callable
-
-   T = TypeVar('T')
-
-   @contextmanager  # built-in plugin can infer a precise type here
-   def stopwatch(timer: Callable[[], T]) -> Iterator[T]:
-       ...
-       yield timer()
+This hook will be also called for instantiation of classes.
+This is a good choice if the return type is too complex
+to be expressed by regular python typing.
 
 **get_function_signature_hook** is used to adjust the signature of a function.
 
@@ -251,31 +237,3 @@ mypy's cache for that module so that it can be rechecked. This hook
 should be used to report to mypy any relevant configuration data,
 so that mypy knows to recheck the module if the configuration changes.
 The hooks should return data encodable as JSON.
-
-Notes about the semantic analyzer
-*********************************
-
-Mypy 0.710 introduced a new semantic analyzer, and the old semantic
-analyzer was removed in mypy 0.730. Support for the new semantic analyzer
-required some changes to existing plugins. Here is a short summary of the
-most important changes:
-
-* The order of processing AST nodes is different. Code outside
-  functions is processed first, and functions and methods are
-  processed afterwards.
-
-* Each AST node can be processed multiple times to resolve forward
-  references.  The same plugin hook may be called multiple times, so
-  they need to be idempotent.
-
-* The ``anal_type()`` API method returns ``None`` if some part of
-  the type is not available yet due to forward references, for example.
-
-* When looking up symbols, you may encounter *placeholder nodes* that
-  are used for names that haven't been fully processed yet. You'll
-  generally want to request another semantic analysis iteration by
-  *deferring* in that case.
-
-See the docstring at the top of
-`mypy/plugin.py <https://github.com/python/mypy/blob/master/mypy/plugin.py>`_
-for more details.