help(dict.pop) was correct in 3.7:

    pop(...)
        D.pop(k[,d]) -> v

and incorrect for 3.8:

     pop(self, key, default=None, /)

This happened in:
9e4f2f3
#12792

We've long known that the Argument Clinic was not applicable to all functions and methods, including this one in particular. The issue is that the one argument form does not set the default to None; rather, it triggers a KeyError when the key is missing. In other words, there is an important and long-standing semantic difference between d.pop(k) and d.pop(k,None).

When reverting this change, please add a note about why the ArgumentClinic is not being applied to this function until its capabilities have been built-out to handle functions that have different behaviors depending on the number of arguments.

Also, we should review other recent applications of the ArgumentClinic to make sure they didn't make the same mistake.

The code generated by Argument Clinic is correct.

>>> {}.pop(1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 1
>>> {}.pop(1, None)

It is just a signature wrong. Some earlier versions of Argument Clinic allowed you to write "default=undefined" to specify an optional argument without default value, but this feature was lost a long time ago. So now signatures of some functions with optional arguments are false.

It is just a signature wrong.

Yes, that is the part that needs to be fixed. The information it provides is incorrect. That is why this function wasn't converted long ago.

I am working on this issue and almost done.

The questions is what inspect.Signature() and inspect.getfullargspec() should do with such functions.

1. Raise an exception as they did in old Python versions and as they do with builtin functions not converted to Argument Clinic.

2. Return a value where a special placeholder is used as a default value for optional parameters which cannot have a default value. In this case there are other questions: what is better name for it (I considered "unspecified" and "unrepresentable") and should it be a single object used for all parameters or a separate object created for every parameter?

I would think that the best course of action is to revert the dict.pop() check-in for Python3.8, then reapply in 3.9 once a plan is worked out to expand the capabilities of the argument clinic and the expressiveness of signatures. The latter seem more like enhancements that need time to mature rather than putting them in to 3.8b2.

There's no real downside to reverting the dict.pop() checkin. It's only effects were to generate an incorrect signature and to make help() misleading.

The patch is too extensive for backporting to 3.8 and 3.7.

PR 13933 implements the first option. It fixes similar issues with other functions so it should be backported to 3.7.

The second option is considered as a new feature and can go only in 3.9.

As I noted on the PR: "I'm not going to get into whether this PR is appropriate for 3.8 but, assuming it were, I would be very concerned about making a change of this size and complexity in 3.7 at this stage in its lifecycle."

I agree that this is a bug in many API docstrings, and PR 13933 is the right approach to fix all bugs in the future.

But in case of dict.pop(), this is not only a bug, but a regression.
May I merge PR-13935 to fix the regression in 3.7b2?

I think you mean 3.8b2 so that would be Łukasz's call.

New changeset 279f446 by Serhiy Storchaka in branch 'master':
bpo-37206: Unrepresentable default values no longer represented as None. (GH-13933)
279f446

New changeset d322abb by Serhiy Storchaka in branch '3.8':
[3.8] bpo-37206: Unrepresentable default values no longer represented as None. (GH-13933) (GH-16141)
d322abb