gh-110383: Update dict get, fromkeys, and setdefault signatures in docs

[johnlandonwood]

Small update to address "list of errata: 2" in #110383, by updating the signature of dict methods get, pop, fromkeys, and setdefault in the docs.

• Issue: Issues from docs@python.org #110383

---

📚 Documentation preview 📚: https://cpython-previews--119330.org.readthedocs.build/

[ghost]

All commit authors signed the Contributor License Agreement.

[encukou]

Thank you!

Please also remove the square brackets: those are another way of saying that the argument is optional, they aren't needed if the default value is given.

This change makes the get docs inconsistent with fromkeys, pop, and setdefault. Do you want to update those as well?

[erlend-aasland]

Thanks for the PR! Changes like this are ... controversial. There's a group of core devs who prefer the (a[, b]) signatures, and there's a groupe of core devs who prefer the (a, b=None) signatures. The problem with the former is that they do not work well with inspect, so a lot of people want to change inspect instead.

Moreover, this PR introduces an inconsistency when we compare get() to the surrounding documented methods. The "bracket-without-default" notation is predominantly used, so iff this should be changed, one would have to take this whole section into account.

So, sorry, I think we have to reject this particular change for now. IMO, it should not be in the TODO list in the issue; changes like this are controversial, and thus no good match as a beginner PR/issue :(

[johnlandonwood]

@encukou and @erlend-aasland - thank you for the feedback! No worries, I wasn't aware of the controversy around those notations. I just saw it in that issue and it looked like a layup, but things are often more complex than they seem. I appreciate the context :)

[erlend-aasland]

I just had a talk with Petr, and I see now that this particular change is not in the controversial camp :) It does make sense to align the docs with the docstring; so let's land this!

[johnlandonwood]

I just had a talk with Petr, and I see now that this particular change is not in the controversial camp :) It does make sense to align the docs with the docstring; so let's land this!

Great to hear! I just updated get and the other surrounding methods (fromkeys, pop, and setdefault) for consistency. Let me know if anything looks off.

[johnlandonwood]

Wait, one point of confusion - should the dosctring for pop be updated too, to mention that None is the default? Or does the raising of the KeyError cover that?

[erlend-aasland]

Wait, one point of confusion - should the dosctring for pop be updated too, to mention that None is the default? Or does the raising of the KeyError cover that?

Well, it is not that easy; you'd have to change the Argument Clinic input and regenerate the parsing code:

cpython/Objects/dictobject.c

Lines 4377 to 4395 in b7f45a9

	/*[clinic input]
	dict.pop
	key: object
	default: object = NULL
	/
	D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
	If the key is not found, return the default if given; otherwise,
	raise a KeyError.
	[clinic start generated code]*/
	staticPyObject*
	dict_pop_impl(PyDictObject*self, PyObject*key, PyObject*default_value)
	/*[clinic end generated code: output=3abb47b89f24c21c input=e221baa01044c44c]*/
	{
	return_PyDict_Pop((PyObject*)self, key, default_value);
	}

So, that change would look like this¹:

diff --git a/Objects/dictobject.c b/Objects/dictobject.c
index 985a326a176..c976a0c868f 100644
--- a/Objects/dictobject.c+++ b/Objects/dictobject.c@@ -4378,7 +4378,7 @@ dict_clear_impl(PyDictObject *self)
dict.pop
key: object
- default: object = NULL+ default: object = None
/
D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

Footnotes

1. combined with make clinic↩

[erlend-aasland]

I think we should consider leaving the pop() change out; what do you think, @encukou? Contrary to the other methods, pop() does not actually default to None; in the implementation it defaults to NULL.

[rhettinger]

Except for pop, these look fine to me.

[erlend-aasland]

Thank you, @johnlandonwood, and congrats on landing your first PR :)

[johnlandonwood]

Thank you, @johnlandonwood, and congrats on landing your first PR :)

No, thanks to you and the others for what you do! Feels great!

[rhettinger]

Hmm, I think I remember why these got skipped in all of the past sweeps. The issue was that the bracketless form implied that keyword arguments could be used. Also, there was a decision to avoid use / in signatures in the docs because it tends to confuse users.

Also, it looks like the actual help signatures sometimes look terrible and we don't want that to spill to the main docs:

>>> help(dict.pop)
Help on method_descriptor:
pop(self, key, default=<unrepresentable>, /) unbound builtins.dict method
D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
If the key is not found, return the default if given; otherwise,
raise a KeyError.

Go ahead and do want you want. I don't have an opinion. I just know that these were intentionally not changed during past sweeps.

[bedevere-app]

GH-119370 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-119371 is a backport of this pull request to the 3.12 branch.