GeezerVison is showing github.com — typing docs: Use soft deprecation · Issue #132941 · python/cpython
typing docs: Use soft deprecation #132941DescriptionA 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)
TextHashable and SizedTypeAlias
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.
Linked PRs
Reacted by Sebastian Rittau, Avasam, Semyon Moroz, Bartosz Sławecki and Brian Schubert ActivityAA-Turner commented on Apr 26, 2025
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 commented on Apr 26, 2025 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. srittau commented on Apr 28, 2025 I'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 deprecate NoReturn in this case, especially as I find it more readable. I don't have a very strong opinion on this, though. sobolevn commented on Apr 28, 2025 I would like to soft deprecate NoReturn, because right now it is easy for me to explain the difference like: "NoReturn is just an old deprecated name for Never". It would be much harder to explain if there are any nuances. Reacted by Carl Meyer, Avasam, Brian Schubert and decorator-factory AlexWaygood commented on Apr 28, 2025 I have no strong opinion on NoReturn. To me it reads slightly better than Never in 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 no return statements in them "never return", not realising that None is 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 typing have 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 Schubert carljm commented on Apr 28, 2025 FWIW I agree with soft-deprecating NoReturn and recommending Never in all cases. I don't think NoReturn has 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-factory Reacted by sobolevn srittau commented on Jul 22, 2026 Linking a few related issues and PRs for posterity:
cdce8p commented on Aug 3, 2026 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: ...
...
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|