gh-132941: Soft deprecate various typing classes

Doc/deprecations/soft-deprecations.rst

@@ -19,3 +19,22 @@ There are no plans to remove :term:`soft deprecated` APIs.
 
   (Contributed by Gregory P. Smith in :gh:`86519` and
   Hugo van Kemenade in :gh:`148100`.)
+
+* The following typing-related items are :term:`soft deprecated`:
+
+  * :class:`typing.Optional` in favor of the dedicated union syntax
+    (``X | None``)
+  * :class:`types.UnionType` in favor of :class:`typing.Union` (but see below)
+  * :class:`typing.NoReturn` in favor of :class:`typing.Never`
+
+  Creating :class:`typing.Union` instances using the constructor is also
+  deprecated. Use the dedicated union syntax (``X | Y``) instead.
+
+  Explicitly inheriting from :class:`typing.Generic` is also deprecated.
+  Use the dedicated syntax for :ref:`generic functions <generic-functions>`,
+  :ref:`generic classes <generic-classes>`, and
+  :ref:`generic type aliases <generic-type-aliases>` instead.
+
+* The following typing-related alias is :term:`soft deprecated`:
+
+  * :class:`typing.ForwardRef` in favor of :class:`annotationlib.ForwardRef`

Doc/library/types.rst

@@ -318,6 +318,10 @@ Standard names are defined for the following types:
 
       This is now an alias for :class:`typing.Union`.
 
+   .. soft-deprecated:: 3.16
+
+      Use the ``X | Y`` syntax to create ``Union`` instances and :class:typing.Union for all other purposes.
+
 .. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)
 
    The type of traceback objects such as found in ``sys.exception().__traceback__``.