Merge branch 'master' into fix_typevar_default

Author: randolf-scholz

.github/workflows/mypy_primer.yml

@@ -67,6 +67,7 @@ jobs:
             --debug \
             --additional-flags="--debug-serialize" \
             --output concise \
+            --mypy-install-librt \
             | tee diff_${{ matrix.shard-index }}.txt
           ) || [ $? -eq 1 ]
       - if: ${{ matrix.shard-index == 0 }}

docs/source/command_line.rst

@@ -372,7 +372,7 @@ definitions or calls.
 
 .. option:: --untyped-calls-exclude
 
-    This flag allows to selectively disable :option:`--disallow-untyped-calls`
+    This flag allows one to selectively disable :option:`--disallow-untyped-calls`
     for functions and methods defined in specific packages, modules, or classes.
     Note that each exclude entry acts as a prefix. For example (assuming there
     are no type annotations for ``third_party_lib`` available):
@@ -562,7 +562,7 @@ potentially problematic or redundant in some way.
 
 .. option:: --deprecated-calls-exclude
 
-    This flag allows to selectively disable :ref:`deprecated<code-deprecated>` warnings
+    This flag allows one to selectively disable :ref:`deprecated<code-deprecated>` warnings
     for functions and methods defined in specific packages, modules, or classes.
     Note that each exclude entry acts as a prefix. For example (assuming ``foo.A.func`` is deprecated):
 
@@ -1255,12 +1255,18 @@ Miscellaneous
    stub packages were found, they are installed and then another run
    is performed.
 
-.. option:: --junit-xml JUNIT_XML
+.. option:: --junit-xml JUNIT_XML_OUTPUT_FILE
 
     Causes mypy to generate a JUnit XML test result document with
     type checking results. This can make it easier to integrate mypy
     with continuous integration (CI) tools.
 
+.. option:: --junit-format {global,per_file}
+
+    If --junit-xml is set, specifies format.
+    global (default): single test with all errors;
+    per_file: one test entry per file with failures.
+
 .. option:: --find-occurrences CLASS.MEMBER
 
     This flag will make mypy print out all usages of a class member

docs/source/common_issues.rst

@@ -731,7 +731,7 @@ This example demonstrates both safe and unsafe overrides:
 
     class NarrowerReturn(A):
         # A more specific return type is fine
-        def test(self, t: Sequence[int]) -> List[str]:  # OK
+        def test(self, t: Sequence[int]) -> list[str]:  # OK
             ...
 
     class GeneralizedReturn(A):
@@ -746,7 +746,7 @@ not necessary:
 .. code-block:: python
 
     class NarrowerArgument(A):
-        def test(self, t: List[int]) -> Sequence[str]:  # type: ignore[override]
+        def test(self, t: list[int]) -> Sequence[str]:  # type: ignore[override]
             ...
 
 .. _unreachable:

docs/source/config_file.rst

@@ -1153,6 +1153,15 @@ These options may only be set in the global section (``[mypy]``).
     type checking results. This can make it easier to integrate mypy
     with continuous integration (CI) tools.
 
+.. confval:: junit_format
+
+    :type: string
+    :default: ``global``
+
+    If junit_xml is set, specifies format.
+    global (default): single test with all errors;
+    per_file: one test entry per file with failures.
+
 .. confval:: scripts_are_modules
 
     :type: boolean

docs/source/error_code_list.rst

@@ -1032,8 +1032,8 @@ Warn about top level await expressions [top-level-await]
 This error code is separate from the general ``[syntax]`` errors, because in
 some environments (e.g. IPython) a top level ``await`` is allowed. In such
 environments a user may want to use ``--disable-error-code=top-level-await``,
-that allows to still have errors for other improper uses of ``await``, for
-example:
+which allows one to still have errors for other improper uses of ``await``,
+for example:
 
 .. code-block:: python
 

docs/source/error_code_list2.rst

@@ -676,3 +676,26 @@ Example:
                 print("red")
             case _:
                 print("other")
+
+.. _code-untyped-decorator:
+
+Error if an untyped decorator makes a typed function effectively untyped [untyped-decorator]
+--------------------------------------------------------------------------------------------
+
+If enabled with :option:`--disallow-untyped-decorators <mypy --disallow-untyped-decorators>`
+mypy generates an error if a typed function is wrapped by an untyped decorator
+(as this would effectively remove the benefits of typing the function).
+
+Example:
+
+.. code-block:: python
+
+        def printing_decorator(func):
+            def wrapper(*args, **kwds):
+                print("Calling", func)
+                return func(*args, **kwds)
+            return wrapper
+        # A decorated function.
+        @printing_decorator  # E: Untyped decorator makes function "add_forty_two" untyped  [untyped-decorator]
+        def add_forty_two(value: int) -> int:
+            return value + 42

docs/source/mypy_daemon.rst

@@ -252,16 +252,16 @@ command.
 Statically inspect expressions
 ******************************
 
-The daemon allows to get declared or inferred type of an expression (or other
+The daemon allows one to get the declared or inferred type of an expression (or other
 information about an expression, such as known attributes or definition location)
-using ``dmypy inspect LOCATION`` command. The location of the expression should be
+using the ``dmypy inspect LOCATION`` command. The location of the expression should be
 specified in the format ``path/to/file.py:line:column[:end_line:end_column]``.
 Both line and column are 1-based. Both start and end position are inclusive.
 These rules match how mypy prints the error location in error messages.
 
 If a span is given (i.e. all 4 numbers), then only an exactly matching expression
 is inspected. If only a position is given (i.e. 2 numbers, line and column), mypy
-will inspect all *expressions*, that include this position, starting from the
+will inspect all expressions that include this position, starting from the
 innermost one.
 
 Consider this Python code snippet:

docs/source/stubtest.rst

@@ -99,8 +99,75 @@ to mypy build errors". In this case, you will need to mitigate those errors
 before stubtest will run. Despite potential overlap in errors here, stubtest is
 not intended as a substitute for running mypy directly.
 
+Allowlist
+*********
+
 If you wish to ignore some of stubtest's complaints, stubtest supports a
-pretty handy allowlist system.
+pretty handy :option:`--allowlist` system.
+
+Let's say that you have this python module called ``ex``:
+
+.. code-block:: python
+
+   try:
+       import optional_expensive_dep
+   except ImportError:
+       optional_expensive_dep = None
+
+   first = 1
+   if optional_expensive_dep:
+       second = 2
+
+Let's say that you can't install ``optional_expensive_dep`` in CI for some reason,
+but you still want to include ``second: int`` in the stub file:
+
+.. code-block:: python
+
+    first: int
+    second: int
+
+In this case stubtest will correctly complain:
+
+.. code-block:: shell
+
+   error: ex.second is not present at runtime
+   Stub: in file /.../ex.pyi:2
+   builtins.int
+   Runtime:
+   MISSING
+
+   Found 1 error (checked 1 module)
+
+To fix this, you can add an ``allowlist`` entry:
+
+.. code-block:: ini
+
+   # Allowlist entries in `allowlist.txt` file:
+
+   # Does not exist if `optional_expensive_dep` is not installed:
+   ex.second
+
+And now when running stubtest with ``--allowlist=allowlist.txt``,
+no errors will be generated anymore.
+
+Allowlists also support regular expressions,
+which can be useful to ignore many similar errors at once.
+They can also be useful for suppressing stubtest errors that occur sometimes,
+but not on every CI run. For example, if some CI workers have
+``optional_expensive_dep`` installed, stubtest might complain with this message
+on those workers if you had the ``ex.second`` allowlist entry:
+
+.. code-block:: ini
+
+   note: unused allowlist entry ex.second
+   Found 1 error (checked 1 module)
+
+Changing ``ex.second`` to be ``(ex\.second)?`` will make this error optional,
+meaning that stubtest will pass whether or not a CI runner
+has``optional_expensive_dep`` installed.
+
+CLI
+***
 
 The rest of this section documents the command line interface of stubtest.
 
@@ -119,15 +186,15 @@ The rest of this section documents the command line interface of stubtest.
 .. option:: --allowlist FILE
 
     Use file as an allowlist. Can be passed multiple times to combine multiple
-    allowlists. Allowlists can be created with --generate-allowlist. Allowlists
-    support regular expressions.
+    allowlists. Allowlists can be created with :option:`--generate-allowlist`.
+    Allowlists support regular expressions.
 
     The presence of an entry in the allowlist means stubtest will not generate
     any errors for the corresponding definition.
 
 .. option:: --generate-allowlist
 
-    Print an allowlist (to stdout) to be used with --allowlist
+    Print an allowlist (to stdout) to be used with :option:`--allowlist`.
 
     When introducing stubtest to an existing project, this is an easy way to
     silence all existing errors.
@@ -141,17 +208,17 @@ The rest of this section documents the command line interface of stubtest.
 
     Note if an allowlist entry is a regex that matches the empty string,
     stubtest will never consider it unused. For example, to get
-    `--ignore-unused-allowlist` behaviour for a single allowlist entry like
+    ``--ignore-unused-allowlist`` behaviour for a single allowlist entry like
     ``foo.bar`` you could add an allowlist entry ``(foo\.bar)?``.
     This can be useful when an error only occurs on a specific platform.
 
 .. option:: --mypy-config-file FILE
 
-    Use specified mypy config file to determine mypy plugins and mypy path
+    Use specified mypy config *file* to determine mypy plugins and mypy path
 
 .. option:: --custom-typeshed-dir DIR
 
-    Use the custom typeshed in DIR
+    Use the custom typeshed in *DIR*
 
 .. option:: --check-typeshed
 

misc/analyze_cache.py

@@ -41,7 +41,7 @@ def extract(chunks: Iterable[JsonDict]) -> Iterable[JsonDict]:
             if isinstance(chunk, dict):
                 yield chunk
                 yield from extract(chunk.values())
-            elif isinstance(chunk, list):
+            elif isinstance(chunk, list):  # type: ignore[unreachable] #TODO: is this actually unreachable, or are our types wrong?
                 yield from extract(chunk)
 
     yield from extract([chunk.data for chunk in chunks])
@@ -93,7 +93,7 @@ def compress(chunk: JsonDict) -> JsonDict:
     def helper(chunk: JsonDict) -> JsonDict:
         nonlocal counter
         if not isinstance(chunk, dict):
-            return chunk
+            return chunk  # type: ignore[unreachable] #TODO: is this actually unreachable, or are our types wrong?
 
         if len(chunk) <= 2:
             return chunk
@@ -124,7 +124,7 @@ def decompress(chunk: JsonDict) -> JsonDict:
 
     def helper(chunk: JsonDict) -> JsonDict:
         if not isinstance(chunk, dict):
-            return chunk
+            return chunk  # type: ignore[unreachable] #TODO: is this actually unreachable, or are our types wrong?
         if ".id" in chunk:
             return cache[chunk[".id"]]
 

misc/profile_check.py

@@ -78,22 +78,22 @@ def check_requirements() -> None:
     if sys.platform != "linux":
         # TODO: How to make this work on other platforms?
         sys.exit("error: Only Linux is supported")
-
-    try:
-        subprocess.run(["perf", "-h"], capture_output=True)
-    except (subprocess.CalledProcessError, FileNotFoundError):
-        print("error: The 'perf' profiler is not installed")
-        sys.exit(1)
-
-    try:
-        subprocess.run(["clang", "--version"], capture_output=True)
-    except (subprocess.CalledProcessError, FileNotFoundError):
-        print("error: The clang compiler is not installed")
-        sys.exit(1)
-
-    if not os.path.isfile("mypy_self_check.ini"):
-        print("error: Run this in the mypy repository root")
-        sys.exit(1)
+    else:  # fun fact/todo: we have to use else here, because of https://github.com/python/mypy/issues/10773
+        try:
+            subprocess.run(["perf", "-h"], capture_output=True)
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            print("error: The 'perf' profiler is not installed")
+            sys.exit(1)
+
+        try:
+            subprocess.run(["clang", "--version"], capture_output=True)
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            print("error: The clang compiler is not installed")
+            sys.exit(1)
+
+        if not os.path.isfile("mypy_self_check.ini"):
+            print("error: Run this in the mypy repository root")
+            sys.exit(1)
 
 
 def main() -> None: