JelleZijlstra · May 22, 2026 · May 18, 2026 · May 18, 2026 · May 18, 2026 · May 18, 2026
@@ -5,7 +5,7 @@
 * Generic, Protocol, and internal machinery to support generic aliases.
   All subscripted types like X[int], Union[int, str] are generic aliases.
 * Various "special forms" that have unique meanings in type annotations:
-  NoReturn, Never, ClassVar, Self, Concatenate, Unpack, and others.
+  Any, Never, ClassVar, Self, Concatenate, Unpack, and others.
 * Classes whose instances can be type arguments to generic classes and functions:
   TypeVar, ParamSpec, TypeVarTuple.
 * Public helper functions: get_type_hints, overload, cast, final, and others.
@@ -591,12 +591,12 @@ def __repr__(self):
 class Any(metaclass=_AnyMeta):
     """Special type indicating an unconstrained type.
 
-    - Any is compatible with every type.
-    - Any assumed to have all methods.
-    - All values assumed to be instances of Any.
+    - Any is assignable to every type.
+    - Any assumed to have all methods and attributes.
+    - All values are assignable to Any.
 
     Note that all the above statements are true from the point of view of
-    static type checkers. At runtime, Any should not be used with instance
+    static type checkers. At runtime, Any cannot be used with instance
     checks.
     """
 
@@ -715,7 +715,7 @@ class Starship:
 
     ClassVar accepts only types and cannot be further subscribed.
 
-    Note that ClassVar is not a class itself, and should not
+    Note that ClassVar is not a class itself, and cannot
     be used with isinstance() or issubclass().
     """
     item = _type_check(parameters, f'{self} accepts only single type.', allow_special_forms=True)
@@ -745,7 +745,7 @@ class FastConnector(Connection):
 
 @_SpecialForm
 def Optional(self, parameters):
-    """Optional[X] is equivalent to Union[X, None]."""
+    """Optional[X] is equivalent to X | None."""
     arg = _type_check(parameters, f"{self} requires a single type.")
     return Union[arg, type(None)]
 
@@ -788,7 +788,7 @@ def open_helper(file: str, mode: MODE) -> str:
 def TypeAlias(self, parameters):
     """Special form for marking type aliases.
 
-    Use TypeAlias to indicate that an assignment should
+    TypeAlias can be used to indicate that an assignment should
     be recognized as a proper type alias definition by type
     checkers.
 
@@ -1796,7 +1796,7 @@ class Movie(TypedDict):
         def foo(**kwargs: Unpack[Movie]): ...
 
     Note that there is only some runtime checking of this operator. Not
-    everything the runtime allows may be accepted by static type checkers.
+    everything the runtime allows is accepted by static type checkers.
 
     For more information, see PEPs 646 and 692.
     """
@@ -2307,7 +2307,7 @@ def runtime_checkable(cls):
     Such protocol can be used with isinstance() and issubclass().
     Raise TypeError if applied to a non-protocol class.
     This allows a simple-minded structural check very similar to
-    one trick ponies in collections.abc such as Iterable.
+    one-trick ponies in collections.abc such as Iterable.
 
     For example::
 
@@ -2377,8 +2377,8 @@ def get_type_hints(obj, globalns=None, localns=None, include_extras=False,
                    *, format=None):
     """Return type hints for an object.
 
-    This is often the same as obj.__annotations__, but it handles
-    forward references encoded as string literals and recursively replaces all
+    This is often the same as obj.__annotations__ and annotationlib.get_annotations(obj),
+    but it handles forward references encoded as string literals and recursively replaces all
     'Annotated[T, ...]' with 'T' (unless 'include_extras=True').
 
     The argument may be a module, class, method, or function. The annotations
@@ -2590,7 +2590,7 @@ def get_args(tp):
 
 
 def is_typeddict(tp):
-    """Check if an annotation is a TypedDict class.
+    """Check if an object is a TypedDict class.
 
     For example::
 
@@ -2688,29 +2688,29 @@ def overload(func):
     """Decorator for overloaded functions/methods.
 
     In a stub file, place two or more stub definitions for the same
-    function in a row, each decorated with @overload.
-
-    For example::
+    function in a row, each decorated with @overload, followed
+    with an implementation.  The implementation should *not*
+    be decorated with @overload::
 
         @overload
         def utf8(value: None) -> None: ...
         @overload
         def utf8(value: bytes) -> bytes: ...
         @overload
         def utf8(value: str) -> bytes: ...
+        def utf8(value):
+            ...  # implementation goes here
 
-    In a non-stub file (i.e. a regular .py file), do the same but
-    follow it with an implementation.  The implementation should *not*
-    be decorated with @overload::
+    In a stub file or in a Protocol definition, the implementation
+    should be omitted::
 
         @overload
         def utf8(value: None) -> None: ...
         @overload
         def utf8(value: bytes) -> bytes: ...
         @overload
         def utf8(value: str) -> bytes: ...
-        def utf8(value):
-            ...  # implementation goes here
+
 
     The overloads for a function can be retrieved at runtime using the
     get_overloads() function.
@@ -2746,7 +2746,7 @@ def final(f):
     """Decorator to indicate final methods and final classes.
 
     Use this decorator to indicate to type checkers that the decorated
-    method cannot be overridden, and decorated class cannot be subclassed.
+    method cannot be overridden, and the decorated class cannot be subclassed.
 
     For example::
 
@@ -2899,7 +2899,7 @@ class TeamUser(User): ...
     And a function that takes a class argument that's a subclass of
     User and returns an instance of the corresponding class::
 
-        def new_user[U](user_class: Type[U]) -> U:
+        def new_user[U](user_class: type[U]) -> U:
             user = user_class()
             # (Here we could write the user object to a database)
             return user
@@ -2912,7 +2912,7 @@ def new_user[U](user_class: Type[U]) -> U:
 
 @runtime_checkable
 class SupportsInt(Protocol):
-    """An ABC with one abstract method __int__."""
+    """A protocol with one abstract method __int__."""
 
     __slots__ = ()
 
@@ -2923,7 +2923,7 @@ def __int__(self) -> int:
 
 @runtime_checkable
 class SupportsFloat(Protocol):
-    """An ABC with one abstract method __float__."""
+    """A protocol with one abstract method __float__."""
 
     __slots__ = ()
 
@@ -2934,7 +2934,7 @@ def __float__(self) -> float:
 
 @runtime_checkable
 class SupportsComplex(Protocol):
-    """An ABC with one abstract method __complex__."""
+    """A protocol with one abstract method __complex__."""
 
     __slots__ = ()
 
@@ -2945,7 +2945,7 @@ def __complex__(self) -> complex:
 
 @runtime_checkable
 class SupportsBytes(Protocol):
-    """An ABC with one abstract method __bytes__."""
+    """A protocol with one abstract method __bytes__."""
 
     __slots__ = ()
 
@@ -2956,7 +2956,7 @@ def __bytes__(self) -> bytes:
 
 @runtime_checkable
 class SupportsIndex(Protocol):
-    """An ABC with one abstract method __index__."""
+    """A protocol with one abstract method __index__."""
 
     __slots__ = ()
 
@@ -2967,7 +2967,7 @@ def __index__(self) -> int:
 
 @runtime_checkable
 class SupportsAbs[T](Protocol):
-    """An ABC with one abstract method __abs__ that is covariant in its return type."""
+    """A protocol with one abstract method __abs__ that is covariant in its return type."""
 
     __slots__ = ()
 
@@ -2978,7 +2978,7 @@ def __abs__(self) -> T:
 
 @runtime_checkable
 class SupportsRound[T](Protocol):
-    """An ABC with one abstract method __round__ that is covariant in its return type."""
+    """A protocol with one abstract method __round__ that is covariant in its return type."""
 
     __slots__ = ()
 
@@ -3095,7 +3095,7 @@ def annotate(format):
 
 
 def NamedTuple(typename, fields, /):
-    """Typed version of namedtuple.
+    """Typed version of collections.namedtuple.
 
     Usage::
 
@@ -3107,8 +3107,8 @@ class Employee(NamedTuple):
 
         Employee = collections.namedtuple('Employee', ['name', 'id'])
 
-    The resulting class has an extra __annotations__ attribute, giving a
-    dict that maps field names to types.  (The field names are also in
+    The types for each field name can be retrieved by calling
+    annotationlib.get_annotations(Employee).  (The field names are also in
     the _fields attribute, which is part of the namedtuple API.)
     An alternative equivalent functional syntax is also accepted::
 
@@ -3161,7 +3161,7 @@ def __new__(cls, name, bases, ns, total=True, closed=None,
 
         This method is called when TypedDict is subclassed,
         or when TypedDict is instantiated. This way
-        TypedDict supports all three syntax forms described in its docstring.
+        TypedDict classes can be created through both class-based and functional syntax.
         Subclasses and instances of TypedDict return actual dictionaries.
         """
         for base in bases:
@@ -3315,14 +3315,22 @@ def TypedDict(typename, fields, /, *, total=True, closed=None,
         >>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
         True
 
-    The type info can be accessed via the Point2D.__annotations__ dict, and
-    the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
+    The type info can be accessed by calling annotationlib.get_annotations(Point2D), and
+    via the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
     TypedDict supports an additional equivalent form::
 
         Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
 
     By default, all keys must be present in a TypedDict. It is possible
-    to override this by specifying totality::
+    to override this by using the NotRequired and Required special forms::
+
+        class Point2D(TypedDict):
+            x: int               # the "x" key must always be present (Required is the default)
+            y: NotRequired[int]  # the "y" key can be omitted
+
+    This means that a Point2D TypedDict can have the "y" key omitted, but the "x" key must be present.
+    Items are required by default, so the Required special form is not necessary in this example.
+    In addition, the total argument to the TypedDict function can be used to make all items not required::
 
         class Point2D(TypedDict, total=False):
             x: int
@@ -3331,16 +3339,8 @@ class Point2D(TypedDict, total=False):
     This means that a Point2D TypedDict can have any of the keys omitted. A type
     checker is only expected to support a literal False or True as the value of
     the total argument. True is the default, and makes all items defined in the
-    class body be required.
-
-    The Required and NotRequired special forms can also be used to mark
-    individual keys as being required or not required::
-
-        class Point2D(TypedDict):
-            x: int               # the "x" key must always be present (Required is the default)
-            y: NotRequired[int]  # the "y" key can be omitted
-
-    See PEP 655 for more details on Required and NotRequired.
+    class body be required. The Required special form can be used to mark individual
+    keys as required in a total=False TypedDict.
 
     The ReadOnly special form can be used
     to mark individual keys as immutable for type checkers::
@@ -3374,7 +3374,7 @@ class Point3D(Point2D):
     by default, and it may not be used with the closed argument at the same
     time.
 
-    See PEP 728 for more information about closed and extra_items.
+    See PEPs 589, 655, 705, and 728 for more information.
     """
     ns = {'__annotations__': dict(fields)}
     module = _caller()
@@ -3533,8 +3533,8 @@ class IO(Generic[AnyStr]):
     classes (text vs. binary, read vs. write vs. read/write,
     append-only, unbuffered).  The TextIO and BinaryIO subclasses
     below capture the distinctions between text vs. binary, which is
-    pervasive in the interface; however we currently do not offer a
-    way to track the other distinctions in the type system.
+    pervasive in the interface. For more precise types, define a custom
+    Protocol.
     """
 
     __slots__ = ()
@@ -3624,7 +3624,7 @@ def __exit__(self, type, value, traceback, /) -> None:
 
 
 class BinaryIO(IO[bytes]):
-    """Typed version of the return of open() in binary mode."""
+    """Typed approximation of the return of open() in binary mode."""
 
     __slots__ = ()
 
@@ -3638,7 +3638,7 @@ def __enter__(self) -> BinaryIO:
 
 
 class TextIO(IO[str]):
-    """Typed version of the return of open() in text mode."""
+    """Typed approximation of the return of open() in text mode."""
 
     __slots__ = ()
 
@@ -3705,7 +3705,7 @@ def dataclass_transform(
     field_specifiers: tuple[type[Any] | Callable[..., Any], ...] = (),
     **kwargs: Any,
 ) -> _IdentityCallable:
-    """Decorator to mark an object as providing dataclass-like behaviour.
+    """Decorator to mark an object as providing dataclass-like behavior.
 
     The decorator can be applied to a function, class, or metaclass.
 

diff --git a/Misc/NEWS.d/next/Library/2026-05-18-07-44-46.gh-issue-149995.vvtFHn.rst b/Misc/NEWS.d/next/Library/2026-05-18-07-44-46.gh-issue-149995.vvtFHn.rst
@@ -0,0 +1 @@
+Update various docstrings in :mod:`typing`.