From f025da8f83bdfae0a0de6039044fa773b7458669 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Wed, 27 Apr 2022 13:49:04 +0100 Subject: [PATCH 1/3] Updates to error code documentation --- docs/source/error_code_list.rst | 37 ++++++++++++++++++++++++++++++++ docs/source/error_code_list2.rst | 35 ++++++++++++++++++++++++++---- docs/source/error_codes.rst | 19 +++++++++++----- 3 files changed, 82 insertions(+), 9 deletions(-) diff --git a/docs/source/error_code_list.rst b/docs/source/error_code_list.rst index e655cae3c45d..5c1f0bedb980 100644 --- a/docs/source/error_code_list.rst +++ b/docs/source/error_code_list.rst @@ -679,6 +679,43 @@ implementation. def func(value): pass # actual implementation +Check that coroutine return value is used [unused-coroutine] +------------------------------------------------------------ + +Mypy ensures that return values of async def functions are not +ignored, as this is usually a programming error, as the coroutine +won't be executed at the call site. + +.. code-block:: python + + async def f() -> None: + ... + + async def g() -> None: + f() # Error: missing await + await f() # OK + +You can work around this error by assigning the result to a temporary, +otherwise unused variable: + +.. code-block:: python + + _ = f() # No error + +Check types in assert_type [assert-type] +---------------------------------------- + +The inferred type for an expression passed to ``assert_type`` must match +the provided type. + +.. code-block:: python + + from typing_extensions import assert_type + + assert_type([1], list[int]) # OK + + assert_type([1], list[str]) # Error + Report syntax errors [syntax] ----------------------------- diff --git a/docs/source/error_code_list2.rst b/docs/source/error_code_list2.rst index c55643ad6181..0df36c18df0c 100644 --- a/docs/source/error_code_list2.rst +++ b/docs/source/error_code_list2.rst @@ -200,7 +200,7 @@ mypy generates an error if it thinks that an expression is redundant. .. code-block:: python - # mypy: enable-error-code redundant-expr + # Run as "mypy --enable-error-code redundant-expr ..." def example(x: int) -> None: # Error: Left operand of "and" is always true [redundant-expr] @@ -222,7 +222,7 @@ since unless implemented by a sub-type, the expression will always evaluate to t .. code-block:: python - # mypy: enable-error-code truthy-bool + # Run as "mypy --enable-error-code truthy-bool ..." class Foo: pass @@ -237,7 +237,8 @@ This check might falsely imply an error. For example, ``Iterable`` does not impl .. code-block:: python - # mypy: enable-error-code truthy-bool + # Run as "mypy -enable-error-code truthy-bool ..." + from typing import Iterable def transform(items: Iterable[int]) -> Iterable[int]: @@ -270,7 +271,7 @@ Example: .. code-block:: python - # mypy: enable-error-code ignore-without-code + # Run as "mypy --enable-error-code ignore-without-code ..." class Foo: def __init__(self, name: str) -> None: @@ -288,3 +289,29 @@ Example: # 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] + +Check that awaitable return value is used [unused-awaitable] +------------------------------------------------------------ + +If you use :option:`--enable-error-code unused-awaitable `, +mypy generates an error if you don't use a returned value that defined ``__await__``. + +Example: + +.. code-block:: python + + # Run as "mypy --enable-error-code unused-awaitable ..." + + import asyncio + + async def f() -> int: ... + + async def g() -> None: + asyncio.create_task(f()) # Error: Unused awaitable + +You can assign the value to a temporary, otherwise unused to variable to +silence the error: + +.. code-block:: python + + _ = asyncio.create_task(f()) # No error diff --git a/docs/source/error_codes.rst b/docs/source/error_codes.rst index 08d56c59fba2..608e03993877 100644 --- a/docs/source/error_codes.rst +++ b/docs/source/error_codes.rst @@ -46,11 +46,8 @@ line. This can be used even if you have not configured mypy to show error codes. Currently it's only possible to disable arbitrary error codes on individual lines using this comment. -.. note:: - - There are command-line flags and config file settings for enabling - certain optional error codes, such as :option:`--disallow-untyped-defs `, - which enables the ``no-untyped-def`` error code. +You can also use :option:`--disable-error-code ` +to disable specific error codes globally. This example shows how to ignore an error about an imported name mypy thinks is undefined: @@ -60,3 +57,15 @@ thinks is undefined: # 'foo' is defined in 'foolib', even though mypy can't see the # definition. from foolib import foo # type: ignore[attr-defined] + + +Enabling specific error codes +----------------------------- + +There are command-line flags and config file settings for enabling +certain optional error codes, such as :option:`--disallow-untyped-defs `, +which enables the ``no-untyped-def`` error code. + +You can use :option:`--enable-error-code ` to +enable specific error codes that don't have a dedicated command-line +flag or config file setting. From 0358ef86b763231b0e50c4b710f76b0d22de97a9 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Wed, 27 Apr 2022 14:13:09 +0100 Subject: [PATCH 2/3] Add note about pinning stub package dependencies --- docs/source/installed_packages.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/source/installed_packages.rst b/docs/source/installed_packages.rst index 8db113e4ba9e..8e5bff04ea72 100644 --- a/docs/source/installed_packages.rst +++ b/docs/source/installed_packages.rst @@ -25,6 +25,14 @@ you can create such packages. :pep:`561` specifies how a package can declare that it supports type checking. +.. note:: + + New versions of stub packages often use type system features not + supported by older, and even fairly recent mypy versions. If you + pin to an older version of mypy (using ``requirements.txt``, for + example), it is recommended that you also pin the versions of all + your stub package dependencies. + Using installed packages with mypy (PEP 561) ******************************************** From 7bbb8a19d0474d70e32652f63cbb01df3a7c27b0 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Wed, 27 Apr 2022 14:27:34 +0100 Subject: [PATCH 3/3] Various tweaks --- docs/source/command_line.rst | 10 ++++++---- docs/source/error_code_list2.rst | 19 +++++++++++-------- docs/source/error_codes.rst | 2 +- 3 files changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 36c13910c21a..43c5444ed7be 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -616,6 +616,7 @@ of the above sections. .. option:: --disable-error-code This flag allows disabling one or multiple error codes globally. + See :ref:`error-codes` for more information. .. code-block:: python @@ -623,20 +624,21 @@ of the above sections. x = 'a string' x.trim() # error: "str" has no attribute "trim" [attr-defined] - # --disable-error-code attr-defined + # When using --disable-error-code attr-defined x = 'a string' x.trim() .. option:: --enable-error-code This flag allows enabling one or multiple error codes globally. + See :ref:`error-codes` for more information. - Note: This flag will override disabled error codes from the --disable-error-code - flag + Note: This flag will override disabled error codes from the + :option:`--disable-error-code ` flag. .. code-block:: python - # --disable-error-code attr-defined + # When using --disable-error-code attr-defined x = 'a string' x.trim() diff --git a/docs/source/error_code_list2.rst b/docs/source/error_code_list2.rst index 0df36c18df0c..3938669edafc 100644 --- a/docs/source/error_code_list2.rst +++ b/docs/source/error_code_list2.rst @@ -200,7 +200,7 @@ mypy generates an error if it thinks that an expression is redundant. .. code-block:: python - # Run as "mypy --enable-error-code redundant-expr ..." + # Use "mypy --enable-error-code redundant-expr ..." def example(x: int) -> None: # Error: Left operand of "and" is always true [redundant-expr] @@ -222,7 +222,7 @@ since unless implemented by a sub-type, the expression will always evaluate to t .. code-block:: python - # Run as "mypy --enable-error-code truthy-bool ..." + # Use "mypy --enable-error-code truthy-bool ..." class Foo: pass @@ -237,7 +237,7 @@ This check might falsely imply an error. For example, ``Iterable`` does not impl .. code-block:: python - # Run as "mypy -enable-error-code truthy-bool ..." + # Use "mypy -enable-error-code truthy-bool ..." from typing import Iterable @@ -271,7 +271,7 @@ Example: .. code-block:: python - # Run as "mypy --enable-error-code ignore-without-code ..." + # Use "mypy --enable-error-code ignore-without-code ..." class Foo: def __init__(self, name: str) -> None: @@ -294,24 +294,27 @@ Check that awaitable return value is used [unused-awaitable] ------------------------------------------------------------ If you use :option:`--enable-error-code unused-awaitable `, -mypy generates an error if you don't use a returned value that defined ``__await__``. +mypy generates an error if you don't use a returned value that defines ``__await__``. Example: .. code-block:: python - # Run as "mypy --enable-error-code unused-awaitable ..." + # Use "mypy --enable-error-code unused-awaitable ..." import asyncio async def f() -> int: ... async def g() -> None: - asyncio.create_task(f()) # Error: Unused awaitable + # Error: Value of type "Task[int]" must be used + # Are you missing an await? + asyncio.create_task(f()) You can assign the value to a temporary, otherwise unused to variable to silence the error: .. code-block:: python - _ = asyncio.create_task(f()) # No error + async def g() -> None: + _ = asyncio.create_task(f()) # No error diff --git a/docs/source/error_codes.rst b/docs/source/error_codes.rst index 608e03993877..bed73abc379f 100644 --- a/docs/source/error_codes.rst +++ b/docs/source/error_codes.rst @@ -24,7 +24,7 @@ Displaying error codes ---------------------- Error codes are not displayed by default. Use :option:`--show-error-codes ` -or config `show_error_codes = True` to display error codes. Error codes are shown inside square brackets: +or config ``show_error_codes = True`` to display error codes. Error codes are shown inside square brackets: .. code-block:: text