Repository navigation
typing docs: Use soft deprecation #132941
Description
Activity
types.UnionType (deprecated alias for typing.Union)
I had assumed that merging the two types would mean the
typesname 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
In general I see
typesas the place for interpreter types that don't have a better home. Other typing-related interpreter types (TypeVar, ParamSpec, TypeVarTuple, TypeAliasType) also live intypingnottypes.Reacted by Adam TurnerI'm generally in favor, except for blanket deprecating
NoReturn. This should stay non-deprecated for return types, similar to what is currently suggested by the Modernizing Superseded Typing Features document (written by me, so not a third opinion). I see no reason to deprecateNoReturnin this case, especially as I find it more readable. I don't have a very strong opinion on this, though.I would like to soft deprecate
NoReturn, because right now it is easy for me to explain the difference like: "NoReturnis just an old deprecated name forNever". It would be much harder to explain if there are any nuances.Reacted by Carl Meyer, Avasam, Brian Schubert and decorator-factoryI have no strong opinion on
NoReturn. To me it reads slightly better thanNeverin return annotations. But I can also see the arguments that it's better to have only one preferred way of doing things. I also understand the argument that it's confusing to beginners who think that functions which have noreturnstatements in them "never return", not realising thatNoneis a more appropriate annotation for these functions.The other proposed soft deprecations all sound reasonable to me. I'm not wild about using the term "soft deprecation" in documentation, as I don't think it's self-evident to users what it means for something to be "soft-deprecated": you almost always need some explanation of what some specific soft deprecation actually means, practically, if you want users to have clarity about what API is good to use and what isn't. (The existing soft deprecations in
typinghave slightly different policies laid out in the docs to other soft deprecations in the stdlib!)But that's just about how we describe the soft deprecations in the docs, not about whether we do them or not.
Reacted by Shantanu, Avasam, Adam Turner and Brian SchubertFWIW I agree with soft-deprecating
NoReturnand recommendingNeverin all cases. I don't thinkNoReturnhas any advantage in readability that justifies two aliases for the same thing.Reacted by Jelle Zijlstra, Semyon Moroz, Avasam, Bartosz Sławecki, Brian Schubert and decorator-factoryReacted by sobolevnLinking a few related issues and PRs for posterity:
While I think that the soft-deprecations are helpful, I'd like to suggest to exclude the explicit constructor calls for TypeVar, etc and inheriting from Generic at least for now. AFAIK PEP 695 is not a full replacement for these. I've come across at least one case which isn't possible to express with 695 due to the automatic variance inference. If the generic isn't referenced in any method but should be invariant, the TypeVar needs to be constructed using the "old" style. An example from Home Assistant: https://github.com/home-assistant/core/blob/2026.7.4/homeassistant/util/hass_dict.pyi#L12
_T = TypeVar("_T") # needs to be invariant class _Key(Generic[_T]): # noqa: UP046 """Base class for Hass key types. At runtime delegated to str.""" def __init__(self, value: str, /) -> None: ... ...
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):
List)TextHashableandSizedTypeAliasI'd like to also soft-deprecate the following:
Optional(obviated by PEP-604)NoReturn(preferNever)typing.ForwardRef(deprecated alias forannotationlib.ForwardRef)types.UnionType(deprecated alias fortyping.Union)Unionusing subscripting (Union[A, B]instead ofA | B) (PEP-604)TypeVar,ParamSpec, orTypeVarTupleusing the constructor directly (PEP-695)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.
Linked PRs