The doc of `dict.update()` should show `update(**other)` instead of `update([other])`

[hyperkai]

The doc of dict.update() shows below:

update([other])

Then, according to my experiments below, dict.update() accepts zero or more pairs of a key and value:

v = {'name':'John', 'age':36}

v.update()
v.update(name='David', gender='Male')
v.update({'name':'David', 'gender':'Male'})

print(v)
# {'name': 'David', 'age': 36, 'gender': 'Male'}

So, the doc of dict.update() should show below:

update(**other)

[gvanrossum]

Actually, the [ ] here mean "optional", not "list". However I do agree that it's confusing, and not helpful.

[mpkocher]

Why does d.update() not raise an exception?

Is this trying to semantically/stylistically be consistent with d.update([])? The no arg cases seem fundamentally different to an empty list case.

In [1]: d0 = dict(a=1, b=2)

In [2]: d0.update()

In [3]: d0.update([])

In [4]: d0 |= dict(a=7)

In [5]: d0
Out[5]: {'a': 7, 'b': 2}

Perhaps it's worth mentioning in the docs that .update can be expressed as |=?

[gvanrossum]

Perhaps so that d.update(**x) works even if x is empty?

[gvanrossum]

In any case it’s about 30+ years too late to change…

[terryjreedy]

The docstring says

'D.update([E, ]**F) -> None. Update D from mapping/iterable E and F.\nIf E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k]\nIf E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v\nIn either case, this is followed by: for k in F: D[k] = F[k]'.

Both E and F need to be given because they are passed differently (positionally and by keyword) and handled sequentially and differently. One has to remember that **F represents keywork args collected in a dict. I think a better signature might be given as update([mapiter, /,] **pairs) and say mapping or iterable of pairs E ....

The update(**pairs) case, such as the example v.update(name='David', gender='Male') above, is not covered by the doc signature but is mentioned in its explanation.

In update([]), the empty list is treated as an empty iterable of pairs (mapiter E w/o .keys, as in the docstring).

[AA-Turner]

I'd probably list two signatures here. The alternative is something like dict.update(other=(), /, **kwds) which I think is harder to understand.

A

[skirpichev]

Then, according to my experiments below, dict.update() accepts zero or more pairs of a key and value:

It also accept a mapping or iterable and kwargs:

>>> d
{1: 1, 3: 3}
>>> d.update({4:3}, a=2)
>>> d
{1: 1, 3: 3, 4: 3, 'a': 2}
>>> d.update([(33, 21)], c=3)
>>> d
{1: 1, 3: 3, 4: 3, 'a': 2, 33: 21, 'c': 3}

I'd probably list two signatures here. The alternative is something like dict.update(other=(), /, **kwds) which I think is harder to understand.

Or three, just like the dict constructor. Though, I'm not sure that correct single signature is hard to read. But beware #73498 (we can't convert this to AC).

[skirpichev]

Actually, the [ ] here mean "optional", not "list".

This funny syntax is not explained somewhere in docs. That why people guess and - sometimes - make mistakes.

Shouldn't we replace such signatures with a valid Python function signatures? It's always possible (using multiple signatures, where needed). Else, above syntax must be documented.

[serhiy-storchaka]

Please, do not open separate issue for each function and method. There is #73536 which fixes signatures for all builtin functions and methods (except type() and super()).

[serhiy-storchaka]

I created #137609 for signatures of all builtins.