typing docs: Use soft deprecation

[JelleZijlstra]

A while ago we introduced the concept of "soft deprecation" in PEP 387 (https://peps.python.org/pep-0387/#soft-deprecation): for things that we no longer recommend using, but which we aren't planning to remove in the near future.

The typing docs already list four classes of objects that are deprecated without a scheduled removal (https://docs.python.org/3.14/library/typing.html#deprecation-timeline-of-major-features):

• Pre-PEP-585 generic aliases (e.g. List)
• Text
• Hashable and Sized
• TypeAlias

I'd like to also soft-deprecate the following:

• Optional (obviated by PEP-604)
• NoReturn (prefer Never)
• typing.ForwardRef (deprecated alias for annotationlib.ForwardRef)
• types.UnionType (deprecated alias for typing.Union)
• Creating a Union using subscripting (Union[A, B] instead of A | B) (PEP-604)
• Creating a TypeVar, ParamSpec, or TypeVarTuple using the constructor directly (PEP-695)
• Directly inheriting from Generic (PEP-695)

None of those will be removable for many years if ever, but I think it's useful to have a clear statement in the docs that the newer syntax is preferred.

[AA-Turner]

types.UnionType (deprecated alias for typing.Union)

I had assumed that merging the two types would mean the types name becomes preferred (as it's an interpreter type). I agree it would be useful to clarify which (or both) of the names to use. I've very likely missed prior discussion on this, though!

A

[JelleZijlstra]

In general I see types as the place for interpreter types that don't have a better home. Other typing-related interpreter types (TypeVar, ParamSpec, TypeVarTuple, TypeAliasType) also live in typing not types.