Improve error messages

pyi.py

@@ -626,8 +626,15 @@ def _check_import_or_attribute(
             error_message = Y024
 
         # Y037 errors
-        elif fullname in ("typing.Optional", "typing.Union"):
-            error_message = Y037.format(old_syntax=fullname)
+        elif fullname == "typing.Optional":
+            error_message = Y037.format(
+                old_syntax=fullname, example='"int | None" instead of "Optional[int]"'
+            )
+
+        elif fullname == "typing.Union":
+            error_message = Y037.format(
+                old_syntax=fullname, example='"int | str" instead of "Union[int, str]"'
+            )
 
         else:
             return
@@ -1484,4 +1491,4 @@ def parse_options(
 Y034 = 'Y034 {methods} usually return "self" at runtime. Consider using "_typeshed.Self" in "{method_name}", e.g. "{suggested_syntax}"'
 Y035 = 'Y035 "__all__" in a stub file must have a value, as it has the same semantics as "__all__" at runtime.'
 Y036 = "Y036 Badly defined {method_name} method: {details}"
-Y037 = "Y037 Use PEP 604 union types instead of {old_syntax}."
+Y037 = "Y037 Use PEP 604 union types instead of {old_syntax} (e.g. {example})."

tests/pep604_union_types.pyi

@@ -1,17 +1,17 @@
 import typing
-from typing import Optional  # Y037 Use PEP 604 union types instead of typing.Optional.
-from typing import Union  # Y037 Use PEP 604 union types instead of typing.Union.
+from typing import Optional  # Y037 Use PEP 604 union types instead of typing.Optional (e.g. "int | None" instead of "Optional[int]").
+from typing import Union  # Y037 Use PEP 604 union types instead of typing.Union (e.g. "int | str" instead of "Union[int, str]").
 
 x1: Optional[str]
 x2: Optional
 x3: Union[str, int]
 x4: Union
 
 
-y1: typing.Optional[str]  # Y037 Use PEP 604 union types instead of typing.Optional.
-y2: typing.Optional  # Y037 Use PEP 604 union types instead of typing.Optional.
-y3: typing.Union[str, int]  # Y037 Use PEP 604 union types instead of typing.Union.
-y4: typing.Union  # Y037 Use PEP 604 union types instead of typing.Union.
+y1: typing.Optional[str]  # Y037 Use PEP 604 union types instead of typing.Optional (e.g. "int | None" instead of "Optional[int]").
+y2: typing.Optional  # Y037 Use PEP 604 union types instead of typing.Optional (e.g. "int | None" instead of "Optional[int]").
+y3: typing.Union[str, int]  # Y037 Use PEP 604 union types instead of typing.Union (e.g. "int | str" instead of "Union[int, str]").
+y4: typing.Union  # Y037 Use PEP 604 union types instead of typing.Union (e.g. "int | str" instead of "Union[int, str]").
 
 
 def f1(x: Optional[str] = ...) -> None: ...
@@ -22,9 +22,9 @@ def f5(x: Optional) -> None: ...
 def f6(x: Union) -> None: ...
 
 
-def g1(x: typing.Optional[str] = ...) -> None: ...  # Y037 Use PEP 604 union types instead of typing.Optional.
-def g2() -> typing.Optional[str]: ...  # Y037 Use PEP 604 union types instead of typing.Optional.
-def g3() -> typing.Union[str, int]: ...  # Y037 Use PEP 604 union types instead of typing.Union.
-def g4(x: typing.Union[str, int] = ...) -> None: ...  # Y037 Use PEP 604 union types instead of typing.Union.
-def g5(x: typing.Optional) -> None: ...  # Y037 Use PEP 604 union types instead of typing.Optional.
-def g6(x: typing.Union) -> None: ...  # Y037 Use PEP 604 union types instead of typing.Union.
+def g1(x: typing.Optional[str] = ...) -> None: ...  # Y037 Use PEP 604 union types instead of typing.Optional (e.g. "int | None" instead of "Optional[int]").
+def g2() -> typing.Optional[str]: ...  # Y037 Use PEP 604 union types instead of typing.Optional (e.g. "int | None" instead of "Optional[int]").
+def g3() -> typing.Union[str, int]: ...  # Y037 Use PEP 604 union types instead of typing.Union (e.g. "int | str" instead of "Union[int, str]").
+def g4(x: typing.Union[str, int] = ...) -> None: ...  # Y037 Use PEP 604 union types instead of typing.Union (e.g. "int | str" instead of "Union[int, str]").
+def g5(x: typing.Optional) -> None: ...  # Y037 Use PEP 604 union types instead of typing.Optional (e.g. "int | None" instead of "Optional[int]").
+def g6(x: typing.Union) -> None: ...  # Y037 Use PEP 604 union types instead of typing.Union (e.g. "int | str" instead of "Union[int, str]").