There’s a few things being brought up in this thread.
(A) The documentation issue: Yes I think it is worthwhile making it more clear what type of “deprecation” something is. Right now the term is overloaded with a lot of meanings, so adding clarity to differentiate between “no longer recommended” (APIs we don’t recommend people to use for many possible reasons, but don’t believe it is worth planning to remove) and “stable, but we’ll never remove it and are unlikely to fix bugs or enhance it in the future” (getopt, optparse) and “actual” deprecations where we’ve got a scheduled version in which we intend to make the thing go away (ala PEP-594).
(B) The (f)utility of PendingDeprecationWarning - this topic has come up before: PendingDeprecationWarning is really useful? - our current “wisdom” is basically “don’t bother using that warning, pretend it doesn’t exist”. (hat tip to the lets soft-deprecate PendingDeprecationWarning comment above, we effectively have).
A warning being emitted should always have a justifyable reason for the action it suggests taking to avoid future breakage becoming someones priority to fix in their code.
Having code in place to emit warnings at runtime about things we already know we’ll never break does a disservice to everyone and just cries :deprecated-wolf: when there is no reason for code to be changed. That erodes trust in warnings being meaningful.
So lets not promote the addition of warnings on soft deprecations. Just guide that any form of warning should only be emitted if acting on it clearly improves the future health and longevity of the code triggering it.
For example: We’ll never warn about getopt and optparse. Those are effectively long term stable/stale modules. It isn’t even clear that they should even be called “soft-deprecated”, more that “hey, there’s a fancier thing over here in argparse - but use whichever floats your boat”.
We obviously warn about specific planned date API removals (good riddance asynchat). And we may choose to warn on APIs that “work” but we consider harmful because they’re too easy to use wrong, especially where we have an alternate API with less sharp edges. We may never remove them, thus soft-deprecation, but peoples code is healthier by not using them.