From 48957aa91634f08171e873b64f128311e98d9733 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Wed, 27 Apr 2022 14:58:45 +0100 Subject: [PATCH] Various documentation updates (mostly about error codes) (#12680) Document some additional error codes and some general doc updates for the 0.950 release. --- docs/source/command_line.rst | 10 ++++---- docs/source/error_code_list.rst | 37 +++++++++++++++++++++++++++++ docs/source/error_code_list2.rst | 38 ++++++++++++++++++++++++++---- docs/source/error_codes.rst | 21 ++++++++++++----- docs/source/installed_packages.rst | 8 +++++++ 5 files changed, 100 insertions(+), 14 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_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..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 - # 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 - # mypy: enable-error-code truthy-bool + # Use "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 + # Use "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 + # Use "mypy --enable-error-code ignore-without-code ..." class Foo: def __init__(self, name: str) -> None: @@ -288,3 +289,32 @@ 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 defines ``__await__``. + +Example: + +.. code-block:: python + + # Use "mypy --enable-error-code unused-awaitable ..." + + import asyncio + + async def f() -> int: ... + + async def g() -> None: + # 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 + + 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 08d56c59fba2..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 @@ -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. 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) ********************************************