gh-116938: Clarify documentation of dict and dict.update regarding the positional argument they accept

[Viicos]

• Issue: dict and dict.update treat the first argument as a mapping when it has attribute keys without attribute __getitem__ #116938

---

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

[Viicos]

Wording can be tweaked of course. The creator of the issue also suggested mentioning a keys attribute, not necessarily a method.

I'm also wondering what will happen to the typeshed definitions, currently it expects _typeshed.SupportsKeysAndGetitem.

[AlexWaygood]

Thanks! This seems reasonable to me: it doesn't make the docs significantly more verbose, but it does make them more precise.

It feels a bit unfortunate that the implementation detail of how CPython determines what constitutes a "mapping" is leaking out a bit here. But I think that probably just reflects the fact that people are having to take account of the exact details of this kind of thing in their own code, so it deserves to be documented, I think

[AlexWaygood]

Oh, we don't usually add NEWS entries for changes that only update docs; could you remove this?

[Viicos]

Ah sorry I got confused with the blurb Documentation entry

[AlexWaygood]

I'm also wondering what will happen to the typeshed definitions, currently it expects _typeshed.SupportsKeysAndGetitem.

The typeshed definition already tries to take account of this detail... Curious if you have any specific examples where type checkers have false positives or false negatives as a result of typeshed's current definitions :-) but that's a better discussion for the typeshed issue tracker than here!

[Viicos]

As per #116938 (comment)

[Viicos]

The typeshed definition already tries to take account of this detail... Curious if you have any specific examples where type checkers have false positives or false negatives as a result of typeshed's current definitions :-) but that's a better discussion for the typeshed issue tracker than here!

Turns out I got confused here: having a .keys() method is the only requirement for dict() to consider the argument as a mapping, but __getitem__ must be defined or it will crash at runtime. So the current definition is good!

[AlexWaygood]

Thanks!

[miss-islington-app]

Thanks @Viicos for the PR, and @AlexWaygood for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[bedevere-app]

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

[bedevere-app]

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

[Prometheus3375]

I am a bit late to the party, but here is some issues I would like to address.

[Prometheus3375]

What is the point of using double spaces after periods? I see this is also present in the original .rst. Is there a special meaning for this?

[AlexWaygood]

There used to be a convention to put two spaces after a period. It's been slowly dying out for a long time now, but you still see it a lot in older pieces of writing. (This article in the Python docs is very old.) The most important thing is to stay consistent in whatever article you're editing at any one point in time; consistency between articles on this point is not a goal for CPython's docs.

[Prometheus3375]

I see. There was two spaces after period on line 4673 (4675 right now), but after this PR it is gone, should it be added back?

[AlexWaygood]

I really wouldn't worry about it too much :-)

[Prometheus3375]

There is a premature period on line 4674 after closing brace.

[AlexWaygood]

Good catch! Want to file a PR to fix it?

[Prometheus3375]

#125421

[Prometheus3375]

Here I would like it to be more specific:

Suggested change

	If E present and has a .keys() method, does: for k in E.keys(): D[k] = E[k]
	If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v
	In either case, this is followed by: for k, v in F.items(): D[k] = v
	If E present and has keys attribute, does: for k in E.keys(): D[k] = E[k]
	If E present and lacks keys attribute, does: for (k, v) in E: D[k] = v
	In either case, this is followed by: for k, v in F.items(): D[k] = v

In the web docs the requirements are strict:

• dict: If a positional argument is given and it defines a keys() method, <...>. Otherwise, the positional argument must be an iterable object.
• update: Accepts either another object with a keys() method <...> or <...>.

Usage of words must and accept indicate that any object with non-callable keys is not a valid argument. But phrase If E present and lacks .keys() method does not eliminate cases with non-callable keys.
For example:

class Object:
    keys = []
    def __iter__(self, /):
        return iter(self.keys)

This class clearly lacks .keys() method because keys is a list, but passing it to dict.update results in TypeError: 'list' object is not callable.

[AlexWaygood]

This is fine IMO. It's much less important for docstrings to be completely precise than it is for the ReST documentation. The most important thing for the docstrings is for them to be concise and easily readable in a terminal or editor.

[Prometheus3375]

I see. Any particular reason why is there no a before .keys() method in the second sentence? It is present in 3.12, but looks like it was removed prior this PR.

[AlexWaygood]

You're calling help(dict.update) there, which has a different docstring to collections.abc.Mapping.update (the one being edited here).

[Prometheus3375]

Oh, my bad. In that case dict.update should also be updated as it works the same way (i.e. it calls keys attribute).

[AlexWaygood]

Right, but the docstring for dict.update already appears to be correct, unless I'm misunderstanding.

[Prometheus3375]

In this PR the first sentence was updated from for k in E: D[k] = E[k] to for k in E.keys(): D[k] = E[k] for MutableMapping. dict.update has the same behavior and its docstring has the same flaw, so it would be correct to fix it too.

cpython/Objects/dictobject.c

Lines 4521 to 4525 in 2982bdb

	PyDoc_STRVAR(update__doc__,
	"D.update([E, ]**F) -> None. Update D from dict/iterable E and F.\n\
	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]\n\
	If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v\n\
	In either case, this is followed by: for k in F: D[k] = F[k]");

Consider:

class Object:
    def keys(self):
        return [1, 2]
    def __iter__(self):
        return [3, 4]
    def __getitem__(self, item):
        match item:
            case 1: return 'one'
            case 2: return 'two'
            case 3: return 'three'
            case 4: return 'four'
        
        return item


print(dict(Object()))
d = {}
d.update(Object())
print(d)

Both times the result is {1: 'one', 2: 'two'}, i.e., both times keys() is called, the object is not iterated.

[AlexWaygood]

Sorry, I see what you mean now. Yes, I suppose that could also be clarified.