Merge branch 'master' into master

Author: changhoetyng

.git-blame-ignore-revs

@@ -6,3 +6,7 @@
 f98f78216ba9d6ab68c8e69c19e9f3c7926c5efe
 # run pyupgrade (#12711)
 fc335cb16315964b923eb1927e3aad1516891c28
+# update black to 23.3.0 (#15059)
+4276308be01ea498d946a79554b4a10b1cf13ccb
+# Update black to 24.1.1 (#16847)
+8107e53158d83d30bb04d290ac10d8d3ccd344f8

.github/workflows/test.yml

@@ -71,6 +71,22 @@ jobs:
           tox_extra_args: "-n 4"
           test_mypyc: true
 
+        - name: Test suite with py313-dev-ubuntu, mypyc-compiled
+          python: '3.13-dev'
+          arch: x64
+          os: ubuntu-latest
+          toxenv: py
+          tox_extra_args: "-n 4"
+          test_mypyc: true
+        # - name: Test suite with py314-dev-ubuntu
+        #   python: '3.14-dev'
+        #   arch: x64
+        #   os: ubuntu-latest
+        #   toxenv: py
+        #   tox_extra_args: "-n 4"
+        #   allow_failure: true
+        #   test_mypyc: true
+
         - name: mypyc runtime tests with py39-macos
           python: '3.9.18'
           arch: x64
@@ -119,51 +135,69 @@ jobs:
       MYPY_FORCE_TERMINAL_WIDTH: 200
       # Pytest
       PYTEST_ADDOPTS: --color=yes
+
     steps:
     - uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python }}
-        architecture: ${{ matrix.arch }}
+
     - name: Debug build
       if: ${{ matrix.debug_build }}
       run: |
         PYTHONVERSION=${{ matrix.python }}
         PYTHONDIR=~/python-debug/python-$PYTHONVERSION
         VENV=$PYTHONDIR/env
         ./misc/build-debug-python.sh $PYTHONVERSION $PYTHONDIR $VENV
+        # TODO: does this do anything? env vars aren't passed to the next step right
         source $VENV/bin/activate
+    - name: Latest Dev build
+      if: ${{ endsWith(matrix.python, '-dev') }}
+      run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential gdb lcov libbz2-dev libffi-dev libgdbm-dev liblzma-dev libncurses5-dev \
+            libreadline6-dev libsqlite3-dev libssl-dev lzma lzma-dev tk-dev uuid-dev zlib1g-dev
+          git clone --depth 1 https://github.com/python/cpython.git /tmp/cpython --branch $( echo ${{ matrix.python }} | sed 's/-dev//' )
+          cd /tmp/cpython
+          echo git rev-parse HEAD; git rev-parse HEAD
+          git show --no-patch
+          ./configure --prefix=/opt/pythondev
+          make -j$(nproc)
+          sudo make install
+          sudo ln -s /opt/pythondev/bin/python3 /opt/pythondev/bin/python
+          sudo ln -s /opt/pythondev/bin/pip3 /opt/pythondev/bin/pip
+          echo "/opt/pythondev/bin" >> $GITHUB_PATH
+    - uses: actions/setup-python@v5
+      if: ${{ !(matrix.debug_build || endsWith(matrix.python, '-dev')) }}
+      with:
+        python-version: ${{ matrix.python }}
+        architecture: ${{ matrix.arch }}
+
     - name: Install tox
-      run: pip install setuptools==68.2.2 tox==4.11.0
+      run: |
+        echo PATH; echo $PATH
+        echo which python; which python
+        echo which pip; which pip
+        echo python version; python -c 'import sys; print(sys.version)'
+        echo debug build; python -c 'import sysconfig; print(bool(sysconfig.get_config_var("Py_DEBUG")))'
+        echo os.cpu_count; python -c 'import os; print(os.cpu_count())'
+        echo os.sched_getaffinity; python -c 'import os; print(len(getattr(os, "sched_getaffinity", lambda *args: [])(0)))'
+        pip install setuptools==68.2.2 tox==4.11.0
+
     - name: Compiled with mypyc
       if: ${{ matrix.test_mypyc }}
       run: |
         pip install -r test-requirements.txt
         CC=clang MYPYC_OPT_LEVEL=0 MYPY_USE_MYPYC=1 pip install -e .
+
     - name: Setup tox environment
       run: |
-        tox run -e ${{ matrix.toxenv }} --notest
-        python -c 'import os; print("os.cpu_count", os.cpu_count(), "os.sched_getaffinity", len(getattr(os, "sched_getaffinity", lambda *args: [])(0)))'
+        tox run -e ${{ matrix.toxenv }} --notes
     - name: Test
       run: tox run -e ${{ matrix.toxenv }} --skip-pkg-install -- ${{ matrix.tox_extra_args }}
+      continue-on-error: ${{ matrix.allow_failure == 'true' }}
 
-  python-nightly:
-    runs-on: ubuntu-latest
-    name: Test suite with Python nightly
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: '3.13-dev'
-      - name: Install tox
-        run: pip install setuptools==68.2.2 tox==4.11.0
-      - name: Setup tox environment
-        run: tox run -e py --notest
-      - name: Test
-        run: tox run -e py --skip-pkg-install -- "-n 4"
-        continue-on-error: true
-      - name: Mark as a success
-        run: exit 0
+    - name: Mark as success (check failures manually)
+      if: ${{ matrix.allow_failure == 'true' }}
+      run: exit 0
 
   python_32bits:
     runs-on: ubuntu-latest

docs/source/additional_features.rst

@@ -46,21 +46,18 @@ define dataclasses. For example:
     UnorderedPoint(1, 2) < UnorderedPoint(3, 4)  # Error: Unsupported operand types
 
 Dataclasses can be generic and can be used in any other way a normal
-class can be used:
+class can be used (Python 3.12 syntax):
 
 .. code-block:: python
 
     from dataclasses import dataclass
-    from typing import Generic, TypeVar
-
-    T = TypeVar('T')
 
     @dataclass
-    class BoxedData(Generic[T]):
+    class BoxedData[T]:
         data: T
         label: str
 
-    def unbox(bd: BoxedData[T]) -> T:
+    def unbox[T](bd: BoxedData[T]) -> T:
         ...
 
     val = unbox(BoxedData(42, "<important>"))  # OK, inferred type is int
@@ -98,17 +95,16 @@ does **not** work:
 
 
 To have Mypy recognize a wrapper of :py:func:`dataclasses.dataclass <dataclasses.dataclass>`
-as a dataclass decorator, consider using the :py:func:`~typing.dataclass_transform` decorator:
+as a dataclass decorator, consider using the :py:func:`~typing.dataclass_transform`
+decorator (example uses Python 3.12 syntax):
 
 .. code-block:: python
 
     from dataclasses import dataclass, Field
-    from typing import TypeVar, dataclass_transform
-
-    T = TypeVar('T')
+    from typing import dataclass_transform
 
     @dataclass_transform(field_specifiers=(Field,))
-    def my_dataclass(cls: type[T]) -> type[T]:
+    def my_dataclass[T](cls: type[T]) -> type[T]:
         ...
         return dataclass(cls)
 
@@ -367,20 +363,20 @@ Extended Callable types
    This feature is deprecated.  You can use
    :ref:`callback protocols <callback_protocols>` as a replacement.
 
-As an experimental mypy extension, you can specify :py:data:`~typing.Callable` types
+As an experimental mypy extension, you can specify :py:class:`~collections.abc.Callable` types
 that support keyword arguments, optional arguments, and more.  When
-you specify the arguments of a :py:data:`~typing.Callable`, you can choose to supply just
+you specify the arguments of a :py:class:`~collections.abc.Callable`, you can choose to supply just
 the type of a nameless positional argument, or an "argument specifier"
 representing a more complicated form of argument.  This allows one to
 more closely emulate the full range of possibilities given by the
 ``def`` statement in Python.
 
 As an example, here's a complicated function definition and the
-corresponding :py:data:`~typing.Callable`:
+corresponding :py:class:`~collections.abc.Callable`:
 
 .. code-block:: python
 
-   from typing import Callable
+   from collections.abc import Callable
    from mypy_extensions import (Arg, DefaultArg, NamedArg,
                                 DefaultNamedArg, VarArg, KwArg)
 
@@ -453,7 +449,7 @@ purpose:
 In all cases, the ``type`` argument defaults to ``Any``, and if the
 ``name`` argument is omitted the argument has no name (the name is
 required for ``NamedArg`` and ``DefaultNamedArg``).  A basic
-:py:data:`~typing.Callable` such as
+:py:class:`~collections.abc.Callable` such as
 
 .. code-block:: python
 
@@ -465,7 +461,7 @@ is equivalent to the following:
 
    MyFunc = Callable[[Arg(int), Arg(str), Arg(int)], float]
 
-A :py:data:`~typing.Callable` with unspecified argument types, such as
+A :py:class:`~collections.abc.Callable` with unspecified argument types, such as
 
 .. code-block:: python
 

docs/source/cheat_sheet_py3.rst

@@ -72,9 +72,9 @@ Useful built-in types
    # 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
+   # Use X | None for a value that could be None on Python 3.10+
+   # Use Optional[X] on 3.9 and earlier; Optional[X] is the same as 'X | None'
+   x: str | None = "something" if some_condition() else None
    if x is not None:
        # Mypy understands x won't be None here because of the if-statement
        print(x.upper())
@@ -88,7 +88,8 @@ Functions
 
 .. code-block:: python
 
-   from typing import Callable, Iterator, Union, Optional
+   from collections.abc import Iterator, Callable
+   from typing import Union, Optional
 
    # This is how you annotate a function definition
    def stringify(num: int) -> str:
@@ -121,13 +122,14 @@ Functions
            i += 1
 
    # You can of course split a function annotation over multiple lines
-   def send_email(address: Union[str, list[str]],
-                  sender: str,
-                  cc: Optional[list[str]],
-                  bcc: Optional[list[str]],
-                  subject: str = '',
-                  body: Optional[list[str]] = None
-                  ) -> bool:
+   def send_email(
+       address: str | list[str],
+       sender: str,
+       cc: list[str] | None,
+       bcc: list[str] | None,
+       subject: str = '',
+       body: list[str] | None = None,
+   ) -> bool:
        ...
 
    # Mypy understands positional-only and keyword-only arguments
@@ -230,7 +232,7 @@ When you're puzzled or when things are complicated
    # 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] = []
-   x: Optional[str] = None
+   x: str | None = None
 
    # Use Any if you don't know the type of something or it's too
    # dynamic to write a type for
@@ -274,7 +276,8 @@ that are common in idiomatic Python are standardized.
 
 .. code-block:: python
 
-   from typing import Mapping, MutableMapping, Sequence, Iterable
+   from collections.abc import Mapping, MutableMapping, Sequence, Iterable
+   # or 'from typing import ...' (required in Python 3.8)
 
    # Use Iterable for generic iterables (anything usable in "for"),
    # and Sequence where a sequence (supporting "len" and "__getitem__") is
@@ -349,11 +352,26 @@ Decorators
 **********
 
 Decorator functions can be expressed via generics. See
-:ref:`declaring-decorators` for more details.
+:ref:`declaring-decorators` for more details. Example using Python 3.12
+syntax:
+
+.. code-block:: python
+
+    from collections.abc import Callable
+    from typing import Any
+
+    def bare_decorator[F: Callable[..., Any]](func: F) -> F:
+        ...
+
+    def decorator_args[F: Callable[..., Any]](url: str) -> Callable[[F], F]:
+        ...
+
+The same example using pre-3.12 syntax:
 
 .. code-block:: python
 
-    from typing import Any, Callable, TypeVar
+    from collections.abc import Callable
+    from typing import Any, TypeVar
 
     F = TypeVar('F', bound=Callable[..., Any])
 

docs/source/class_basics.rst

@@ -152,7 +152,8 @@ between class and instance variables with callable types. For example:
 
 .. code-block:: python
 
-   from typing import Callable, ClassVar
+   from collections.abc import Callable
+   from typing import ClassVar
 
    class A:
        foo: Callable[[int], None]

docs/source/command_line.rst

@@ -96,6 +96,10 @@ Optional arguments
 
     Show program's version number and exit.
 
+.. option:: -O FORMAT, --output FORMAT {json}
+
+    Set a custom output format.
+
 .. _config-file-flag:
 
 Config file
@@ -420,11 +424,11 @@ The following flags adjust how mypy handles values of type ``None``.
 
 .. option:: --implicit-optional
 
-    This flag causes mypy to treat arguments with a ``None``
-    default value as having an implicit :py:data:`~typing.Optional` type.
+    This flag causes mypy to treat parameters with a ``None``
+    default value as having an implicit optional type (``T | None``).
 
     For example, if this flag is set, mypy would assume that the ``x``
-    parameter is actually of type ``Optional[int]`` in the code snippet below
+    parameter is actually of type ``int | None`` in the code snippet below,
     since the default parameter is ``None``:
 
     .. code-block:: python
@@ -438,7 +442,7 @@ The following flags adjust how mypy handles values of type ``None``.
 
 .. option:: --no-strict-optional
 
-    This flag effectively disables checking of :py:data:`~typing.Optional`
+    This flag effectively disables checking of optional
     types and ``None`` values. With this option, mypy doesn't
     generally check the use of ``None`` values -- it is treated
     as compatible with every type.
@@ -575,26 +579,24 @@ of the above sections.
 .. option:: --local-partial-types
 
     In mypy, the most common cases for partial types are variables initialized using ``None``,
-    but without explicit ``Optional`` annotations. By default, mypy won't check partial types
+    but without explicit ``X | None`` annotations. By default, mypy won't check partial types
     spanning module top level or class top level. This flag changes the behavior to only allow
     partial types at local level, therefore it disallows inferring variable type for ``None``
     from two assignments in different scopes. For example:
 
     .. code-block:: python
 
-        from typing import Optional
-
         a = None  # Need type annotation here if using --local-partial-types
-        b: Optional[int] = None
+        b: int | None = None
 
         class Foo:
             bar = None  # Need type annotation here if using --local-partial-types
-            baz: Optional[int] = None
+            baz: int | None = None
 
             def __init__(self) -> None:
                 self.bar = 1
 
-        reveal_type(Foo().bar)  # Union[int, None] without --local-partial-types
+        reveal_type(Foo().bar)  # 'int | None' without --local-partial-types
 
     Note: this option is always implicitly enabled in mypy daemon and will become
     enabled by default for mypy in a future release.
@@ -630,13 +632,11 @@ of the above sections.
 
     .. code-block:: python
 
-       from typing import Text
-
        items: list[int]
        if 'some string' in items:  # Error: non-overlapping container check!
            ...
 
-       text: Text
+       text: str
        if text != b'other bytes':  # Error: non-overlapping equality check!
            ...