Skip to content

Commit afa830d

Browse files
Ige-kunIge-kun
authored
Improve documentation for consider-alternative-union-syntax / R6003 (#10044)
1 parent 2e0c41f commit afa830d

File tree

8 files changed

+66
-47
lines changed

8 files changed

+66
-47
lines changed

‎doc/data/messages/c/consider-alternative-union-syntax/bad.py‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1-
from typing import Union
1+
from typing import Optional, Union
22

3-
cats: Union[int, str] # [consider-alternative-union-syntax]
3+
4+
def forecast(
5+
temp: Union[int, float], # [consider-alternative-union-syntax]
6+
unit: Optional[str], # [consider-alternative-union-syntax]
7+
) -> None:
8+
print(f'Temperature: {temp}{unit or ""}')

‎doc/data/messages/c/consider-alternative-union-syntax/details.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Using the shorthand syntax for union types is |recommended over the typing module|__. This is consistent with the broader recommendation to prefer built-in types over imports (for example, using ``list`` instead of the now-deprecated ``typing.List``).
2+
3+
``typing.Optional`` can also cause confusion in annotated function arguments, since an argument annotated as ``Optional`` is still a *required* argument when a default value is not set. Explicitly annotating such arguments with ``type | None`` makes the intention clear.
4+
5+
.. |recommended over the typing module| replace:: recommended over the ``typing`` module
6+
__ https://docs.python.org/3/library/typing.html#typing.Union

‎doc/data/messages/c/consider-alternative-union-syntax/good.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
cats: int | str
1+
def forecast(temp: int | float, unit: str | None) -> None:
2+
print(f'Temperature: {temp}{unit or ""}')

‎doc/user_guide/checkers/extensions.rst‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -685,9 +685,12 @@ Typing checker Messages
685685
:consider-using-alias (R6002): *'%s' will be deprecated with PY39, consider using '%s' instead%s*
686686
Only emitted if 'runtime-typing=no' and a deprecated typing alias is used in
687687
a type annotation context in Python 3.7 or 3.8.
688-
:consider-alternative-union-syntax (R6003): *Consider using alternative Union syntax instead of '%s'%s*
689-
Emitted when 'typing.Union' or 'typing.Optional' is used instead of the
690-
alternative Union syntax 'int | None'.
688+
:consider-alternative-union-syntax (R6003): *Consider using alternative union syntax instead of '%s'%s*
689+
Emitted when ``typing.Union`` or ``typing.Optional`` is used instead of the
690+
shorthand union syntax. For example, ``Union[int, float]`` instead of ``int |
691+
float``. Using the shorthand for unions aligns with Python typing
692+
recommendations, removes the need for imports, and avoids confusion in
693+
function signatures.
691694
:unnecessary-default-type-args (R6007): *Type `%s` has unnecessary default type args. Change it to `%s`.*
692695
Emitted when types have default type args which can be omitted. Mainly used
693696
for `typing.Generator` and `typing.AsyncGenerator`.

‎pylint/extensions/typing.py‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -104,10 +104,14 @@ class TypingChecker(BaseChecker):
104104
"Python 3.7 or 3.8.",
105105
),
106106
"R6003": (
107-
"Consider using alternative Union syntax instead of '%s'%s",
107+
"Consider using alternative union syntax instead of '%s'%s",
108108
"consider-alternative-union-syntax",
109-
"Emitted when 'typing.Union' or 'typing.Optional' is used "
110-
"instead of the alternative Union syntax 'int | None'.",
109+
"Emitted when ``typing.Union`` or ``typing.Optional`` is used "
110+
"instead of the shorthand union syntax. For example, "
111+
"``Union[int, float]`` instead of ``int | float``. Using "
112+
"the shorthand for unions aligns with Python typing "
113+
"recommendations, removes the need for imports, and avoids "
114+
"confusion in function signatures.",
111115
),
112116
"E6004": (
113117
"'NoReturn' inside compound types is broken in 3.7.0 / 3.7.1",

‎tests/functional/ext/typing/typing_consider_using_union.txt‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
consider-alternative-union-syntax:19:6:19:11::Consider using alternative Union syntax instead of 'Union':INFERENCE
2-
consider-alternative-union-syntax:20:11:20:16::Consider using alternative Union syntax instead of 'Union':INFERENCE
3-
consider-alternative-union-syntax:21:16:21:28::Consider using alternative Union syntax instead of 'Union':INFERENCE
4-
consider-alternative-union-syntax:22:6:22:14::Consider using alternative Union syntax instead of 'Optional':INFERENCE
5-
consider-alternative-union-syntax:30:10:30:18:func1:Consider using alternative Union syntax instead of 'Optional':INFERENCE
6-
consider-alternative-union-syntax:31:24:31:29:func1:Consider using alternative Union syntax instead of 'Union':INFERENCE
7-
consider-alternative-union-syntax:32:5:32:10:func1:Consider using alternative Union syntax instead of 'Union':INFERENCE
8-
consider-alternative-union-syntax:44:12:44:17:CustomNamedTuple:Consider using alternative Union syntax instead of 'Union':INFERENCE
9-
consider-alternative-union-syntax:49:27:49:32:CustomTypedDict2:Consider using alternative Union syntax instead of 'Union':INFERENCE
10-
consider-alternative-union-syntax:53:12:53:20:CustomDataClass:Consider using alternative Union syntax instead of 'Optional':INFERENCE
1+
consider-alternative-union-syntax:19:6:19:11::Consider using alternative union syntax instead of 'Union':INFERENCE
2+
consider-alternative-union-syntax:20:11:20:16::Consider using alternative union syntax instead of 'Union':INFERENCE
3+
consider-alternative-union-syntax:21:16:21:28::Consider using alternative union syntax instead of 'Union':INFERENCE
4+
consider-alternative-union-syntax:22:6:22:14::Consider using alternative union syntax instead of 'Optional':INFERENCE
5+
consider-alternative-union-syntax:30:10:30:18:func1:Consider using alternative union syntax instead of 'Optional':INFERENCE
6+
consider-alternative-union-syntax:31:24:31:29:func1:Consider using alternative union syntax instead of 'Union':INFERENCE
7+
consider-alternative-union-syntax:32:5:32:10:func1:Consider using alternative union syntax instead of 'Union':INFERENCE
8+
consider-alternative-union-syntax:44:12:44:17:CustomNamedTuple:Consider using alternative union syntax instead of 'Union':INFERENCE
9+
consider-alternative-union-syntax:49:27:49:32:CustomTypedDict2:Consider using alternative union syntax instead of 'Union':INFERENCE
10+
consider-alternative-union-syntax:53:12:53:20:CustomDataClass:Consider using alternative union syntax instead of 'Optional':INFERENCE

‎tests/functional/ext/typing/typing_consider_using_union_py310.txt‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
1-
consider-alternative-union-syntax:11:6:11:11::Consider using alternative Union syntax instead of 'Union':INFERENCE
2-
consider-alternative-union-syntax:12:11:12:16::Consider using alternative Union syntax instead of 'Union':INFERENCE
3-
consider-alternative-union-syntax:13:16:13:28::Consider using alternative Union syntax instead of 'Union':INFERENCE
4-
consider-alternative-union-syntax:14:6:14:14::Consider using alternative Union syntax instead of 'Optional':INFERENCE
5-
consider-alternative-union-syntax:16:9:16:14::Consider using alternative Union syntax instead of 'Union':INFERENCE
6-
consider-alternative-union-syntax:17:14:17:19::Consider using alternative Union syntax instead of 'Union':INFERENCE
7-
consider-alternative-union-syntax:18:19:18:31::Consider using alternative Union syntax instead of 'Union':INFERENCE
8-
consider-alternative-union-syntax:19:9:19:17::Consider using alternative Union syntax instead of 'Optional':INFERENCE
9-
consider-alternative-union-syntax:22:10:22:18:func1:Consider using alternative Union syntax instead of 'Optional':INFERENCE
10-
consider-alternative-union-syntax:23:24:23:29:func1:Consider using alternative Union syntax instead of 'Union':INFERENCE
11-
consider-alternative-union-syntax:24:5:24:10:func1:Consider using alternative Union syntax instead of 'Union':INFERENCE
12-
consider-alternative-union-syntax:27:19:27:24:Custom1:Consider using alternative Union syntax instead of 'Union':INFERENCE
13-
consider-alternative-union-syntax:31:28:31:33::Consider using alternative Union syntax instead of 'Union':INFERENCE
14-
consider-alternative-union-syntax:33:14:33:22::Consider using alternative Union syntax instead of 'Optional':INFERENCE
15-
consider-alternative-union-syntax:36:12:36:17:CustomNamedTuple:Consider using alternative Union syntax instead of 'Union':INFERENCE
16-
consider-alternative-union-syntax:38:56:38:64::Consider using alternative Union syntax instead of 'Optional':INFERENCE
17-
consider-alternative-union-syntax:41:27:41:32:CustomTypedDict2:Consider using alternative Union syntax instead of 'Union':INFERENCE
18-
consider-alternative-union-syntax:45:12:45:20:CustomDataClass:Consider using alternative Union syntax instead of 'Optional':INFERENCE
1+
consider-alternative-union-syntax:11:6:11:11::Consider using alternative union syntax instead of 'Union':INFERENCE
2+
consider-alternative-union-syntax:12:11:12:16::Consider using alternative union syntax instead of 'Union':INFERENCE
3+
consider-alternative-union-syntax:13:16:13:28::Consider using alternative union syntax instead of 'Union':INFERENCE
4+
consider-alternative-union-syntax:14:6:14:14::Consider using alternative union syntax instead of 'Optional':INFERENCE
5+
consider-alternative-union-syntax:16:9:16:14::Consider using alternative union syntax instead of 'Union':INFERENCE
6+
consider-alternative-union-syntax:17:14:17:19::Consider using alternative union syntax instead of 'Union':INFERENCE
7+
consider-alternative-union-syntax:18:19:18:31::Consider using alternative union syntax instead of 'Union':INFERENCE
8+
consider-alternative-union-syntax:19:9:19:17::Consider using alternative union syntax instead of 'Optional':INFERENCE
9+
consider-alternative-union-syntax:22:10:22:18:func1:Consider using alternative union syntax instead of 'Optional':INFERENCE
10+
consider-alternative-union-syntax:23:24:23:29:func1:Consider using alternative union syntax instead of 'Union':INFERENCE
11+
consider-alternative-union-syntax:24:5:24:10:func1:Consider using alternative union syntax instead of 'Union':INFERENCE
12+
consider-alternative-union-syntax:27:19:27:24:Custom1:Consider using alternative union syntax instead of 'Union':INFERENCE
13+
consider-alternative-union-syntax:31:28:31:33::Consider using alternative union syntax instead of 'Union':INFERENCE
14+
consider-alternative-union-syntax:33:14:33:22::Consider using alternative union syntax instead of 'Optional':INFERENCE
15+
consider-alternative-union-syntax:36:12:36:17:CustomNamedTuple:Consider using alternative union syntax instead of 'Union':INFERENCE
16+
consider-alternative-union-syntax:38:56:38:64::Consider using alternative union syntax instead of 'Optional':INFERENCE
17+
consider-alternative-union-syntax:41:27:41:32:CustomTypedDict2:Consider using alternative union syntax instead of 'Union':INFERENCE
18+
consider-alternative-union-syntax:45:12:45:20:CustomDataClass:Consider using alternative union syntax instead of 'Optional':INFERENCE

‎tests/functional/ext/typing/typing_consider_using_union_without_future.txt‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
consider-alternative-union-syntax:17:6:17:11::Consider using alternative Union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
2-
consider-alternative-union-syntax:18:11:18:16::Consider using alternative Union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
3-
consider-alternative-union-syntax:19:16:19:28::Consider using alternative Union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
4-
consider-alternative-union-syntax:20:6:20:14::Consider using alternative Union syntax instead of 'Optional'. Add 'from __future__ import annotations' as well:INFERENCE
5-
consider-alternative-union-syntax:28:10:28:18:func1:Consider using alternative Union syntax instead of 'Optional'. Add 'from __future__ import annotations' as well:INFERENCE
6-
consider-alternative-union-syntax:29:24:29:29:func1:Consider using alternative Union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
7-
consider-alternative-union-syntax:30:5:30:10:func1:Consider using alternative Union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
8-
consider-alternative-union-syntax:42:12:42:17:CustomNamedTuple:Consider using alternative Union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
9-
consider-alternative-union-syntax:47:27:47:32:CustomTypedDict2:Consider using alternative Union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
10-
consider-alternative-union-syntax:51:12:51:20:CustomDataClass:Consider using alternative Union syntax instead of 'Optional'. Add 'from __future__ import annotations' as well:INFERENCE
1+
consider-alternative-union-syntax:17:6:17:11::Consider using alternative union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
2+
consider-alternative-union-syntax:18:11:18:16::Consider using alternative union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
3+
consider-alternative-union-syntax:19:16:19:28::Consider using alternative union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
4+
consider-alternative-union-syntax:20:6:20:14::Consider using alternative union syntax instead of 'Optional'. Add 'from __future__ import annotations' as well:INFERENCE
5+
consider-alternative-union-syntax:28:10:28:18:func1:Consider using alternative union syntax instead of 'Optional'. Add 'from __future__ import annotations' as well:INFERENCE
6+
consider-alternative-union-syntax:29:24:29:29:func1:Consider using alternative union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
7+
consider-alternative-union-syntax:30:5:30:10:func1:Consider using alternative union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
8+
consider-alternative-union-syntax:42:12:42:17:CustomNamedTuple:Consider using alternative union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
9+
consider-alternative-union-syntax:47:27:47:32:CustomTypedDict2:Consider using alternative union syntax instead of 'Union'. Add 'from __future__ import annotations' as well:INFERENCE
10+
consider-alternative-union-syntax:51:12:51:20:CustomDataClass:Consider using alternative union syntax instead of 'Optional'. Add 'from __future__ import annotations' as well:INFERENCE

0 commit comments

Comments
 (0)