This is not accurate in Python 3.7+, since DeprecationWarning is not ignored by default in __main__ any more.

Is it really much different?
I didn't say any different.

In PEP 565, you used async keyword example. It is really nice example to demonstrate what difference PEP 565 introduces.

On the other hand, most reader of this document will not want to add new keyword. Most of them just want to deprecate their APIs that are not in __main__.
And, as you know, calling deprecated APIs from __main__ doesn't show warning by default.

So there are no much difference.

Calling deprecated APIs from __main__ does show the warning as long as the stack level on the warning is correctly set to refer to the API caller's frame - async becoming a keyword was just our motivation for finally doing something about the behaviour.

For example: all of Serhiy's new warnings about parameters that are going to become positional only? Those will display if the caller is __main__, as they set stacklevel=2 in the warning call, so the filtering ends up being based on the caller's frame, not the frame making the call to the warnings module API.

I was wrong, I used Python 3.6 for testing it.

I still think it's not "much" difference. But if you don't like this phrase, how about this?

See :pep:`565` for current difference between PendingDeprecationWarning and
DeprecationWarning.  DeprecationWarning is recommended in general.

I'd drop the attention getting "Note" markup entirely, and simply reword the existing description with a comparison to DeprecationWarning:

Base class for warnings about features which are expected to be deprecated in the
future. For most deprecations, :exc:DeprecationWarning is preferred (as it's rare to
need to emit a warning about a possible upcoming deprecation in advance of the
deprecation itself).

I think it is still confusing for people doesn't know Python history.

Base class for warnings about features which are expected to be deprecated in the
future.

It's still difficult to imagine what "expected to be deprecated".

For most deprecations, :exc:DeprecationWarning is preferred (as it's rare to
need to emit a warning about a possible upcoming deprecation in advance of the
deprecation itself).

I think DeprecationWarning is preferred for all deprecations. How about:

Base class for warnings about features which are obsolete and
expected to be deprecated in the future, but are not deprecated
at the moment.

This class is rarely used because it's rare to need warning about
a possible upcoming deprecation.

The direct cross-reference to DeprecationWarning is probably worth keeping, so I'd amend the second paragraph a bit to add that back:

Base class for warnings about features which are obsolete and
expected to be deprecated in the future, but are not deprecated
at the moment.

This class is rarely used as emitting a warning about a possible
upcoming deprecation is unusual, and :exc:`DeprecationWarning`
is preferred for already active deprecations.