From d069166ca9b2cbc6b62efe38e5a2db89d8d51f0d Mon Sep 17 00:00:00 2001
From: Rebecca Chen <rchen152@gmail.com>
Date: Wed, 31 Jul 2024 00:39:21 -0700
Subject: [PATCH] Move some more stub author guidance from Type Stubs to
 Writing Stubs.

See https://github.com/python/typing/pull/1815 for context.
---
 docs/guides/writing_stubs.rst | 67 +++++++++++++++++++++++++++++++++++
 docs/reference/stubs.rst      | 59 ++----------------------------
 2 files changed, 69 insertions(+), 57 deletions(-)

diff --git a/docs/guides/writing_stubs.rst b/docs/guides/writing_stubs.rst
index 08760c8d..1d1af917 100644
--- a/docs/guides/writing_stubs.rst
+++ b/docs/guides/writing_stubs.rst
@@ -337,6 +337,46 @@ No::
     DAY_FLAG: int
     NIGHT_FLAG: int
 
+Overloads
+---------
+
+All variants of overloaded functions and methods must have an ``@overload``
+decorator. Do not include the implementation's final non-`@overload`-decorated
+definition.
+
+Yes::
+
+  @overload
+  def foo(x: str) -> str: ...
+  @overload
+  def foo(x: float) -> int: ...
+
+No::
+
+  @overload
+  def foo(x: str) -> str: ...
+  @overload
+  def foo(x: float) -> int: ...
+  def foo(x: str | float) -> Any: ...
+
+Decorators
+----------
+
+Include only the decorators listed :ref:`here <stub-decorators>`, whose effects
+are understood by all of the major type checkers. The behavior of other
+decorators should instead be incorporated into the types. For example, for the
+following function::
+
+  import contextlib
+  @contextlib.contextmanager
+  def f():
+      yield 42
+
+the stub definition should be::
+
+  from contextlib import AbstractContextManager
+  def f() -> AbstractContextManager[int]: ...
+
 Documentation or Implementation
 -------------------------------
 
@@ -581,3 +621,30 @@ No::
     from typing import NamedTuple, TypedDict
     Point = NamedTuple("Point", [('x', float), ('y', float)])
     Thing = TypedDict("Thing", {'stuff': str, 'index': int})
+
+Built-in Generics
+-----------------
+
+:pep:`585` built-in generics are supported and should be used instead
+of the corresponding types from ``typing``::
+
+    from collections import defaultdict
+
+    def foo(t: type[MyClass]) -> list[int]: ...
+    x: defaultdict[int]
+
+Using imports from ``collections.abc`` instead of ``typing`` is
+generally possible and recommended::
+
+    from collections.abc import Iterable
+
+    def foo(iter: Iterable[int]) -> None: ...
+
+Unions
+------
+
+Declaring unions with the shorthand `|` syntax is recommended and supported by
+all type checkers::
+
+  def foo(x: int | str) -> int | None: ...  # recommended
+  def foo(x: Union[int, str]) -> Optional[int]: ...  # ok
diff --git a/docs/reference/stubs.rst b/docs/reference/stubs.rst
index a3a456a0..aac21f98 100644
--- a/docs/reference/stubs.rst
+++ b/docs/reference/stubs.rst
@@ -165,33 +165,6 @@ specified in ``__all__`` are imported::
 
 Type checkers support cyclic imports in stub files.
 
-Built-in Generics
------------------
-
-:pep:`585` built-in generics are supported and should be used instead
-of the corresponding types from ``typing``::
-
-    from collections import defaultdict
-
-    def foo(t: type[MyClass]) -> list[int]: ...
-    x: defaultdict[int]
-
-Using imports from ``collections.abc`` instead of ``typing`` is
-generally possible and recommended::
-
-    from collections.abc import Iterable
-
-    def foo(iter: Iterable[int]) -> None: ...
-
-Unions
-------
-
-Declaring unions with the shorthand syntax or ``Union`` and ``Optional`` is
-supported by all type checkers::
-
-    def foo(x: int | str) -> int | None: ...  # recommended
-    def foo(x: Union[int, str]) -> Optional[int]: ...  # ok
-
 Module Level Attributes
 -----------------------
 
@@ -325,23 +298,6 @@ individual type checkers how to interpret them::
     def foo(): ...  # compatible
     def bar(): pass  # behavior undefined
 
-All variants of overloaded functions and methods must have an ``@overload``
-decorator::
-
-    @overload
-    def foo(x: str) -> str: ...
-    @overload
-    def foo(x: float) -> int: ...
-
-The following (which would be used in the implementation) is wrong in
-type stubs::
-
-    @overload
-    def foo(x: str) -> str: ...
-    @overload
-    def foo(x: float) -> int: ...
-    def foo(x: str | float) -> Any: ...
-
 Aliases and NewType
 -------------------
 
@@ -378,6 +334,8 @@ generic class definitions.
 
 ``typing.NewType`` is also supported in stubs.
 
+.. _stub-decorators:
+
 Decorators
 ----------
 
@@ -391,19 +349,6 @@ fixed set of additional ones:
 * ``dataclasses.dataclass``
 * ``asyncio.coroutine`` (although ``async`` should be used instead)
 
-The behavior of other decorators should instead be incorporated into the types.
-For example, for the following function::
-
-  import contextlib
-  @contextlib.contextmanager
-  def f():
-      yield 42
-
-the stub definition should be::
-
-  from contextlib import AbstractContextManager
-  def f() -> AbstractContextManager[int]: ...
-
 Version and Platform Checks
 ---------------------------