The docs of shelve mention that

Shelf objects support all methods supported by dictionaries. This eases the transition from dictionary based scripts to those requiring persistent storage.

However the |= operator is not implemented, preventing a seamless transition from dict to shelve. So should this be implemented for Shelf as well? | on the other hand doesn't make much sense.

Otherwise the docs could be updated.

The comment is outdated. Shelf objects also do not support methods copy and fromkey. Creating a new Shelve object without specifying a new underlying database object does not make much sense.

Maybe say that they implement the MutableMapping interface?

>>> sorted(set(dir(dict)) - set(dir(shelve.Shelf)))
['__ior__', '__or__', '__ror__', 'copy', 'fromkeys']
>>> sorted(set(dir(collections.abc.MutableMapping)) - set(dir(shelve.Shelf)))
[]

Right, that seems like a good idea. But __ior__ could be implemented nevertheless?

Maybe say that they implement the MutableMapping interface?

Yes, that's a good idea (also add link to the MutableMapping docs).

Right, that seems like a good idea. But __ior__ could
be implemented nevertheless?

Off-hand, I don't see why not.

Adding Brandt to the nosy list to see what he thinks.

One other thought. While __ior__() could be used as a short-cut for update(), the related __or__() method is more problematic because it would need to create a new underlying DB. So maybe this is a can worms that we should not open. It would be weird to have __ior__() but not __or__().

+1 for the MutableMapping comment.

We purposely omitted shelve when determining what classes should grow the new operators. Guido's thoughts:

I definitely think we should leave Shelf alone, it's a toy class from a different era.

(https://bugs.python.org/msg364196)

I personally have no experience with shelve, so I'd rather defer to the judgement of others here.

It's true, having __ior__ but not __or__ would probably be weird. In the end it's just "nice to have", but I'm not even sure that this applies. Calling db.update(...) is still more explicit than db |= .... The docs mention that

This eases the transition from dictionary based scripts to those requiring persistent storage.

For my use cases, however, I always knew right from the beginning that I want object persistence between different runs of a script (e.g. for data analysis, caching the expensive results), so it was always clear that I'm working with a Shelf object and not a dict (i.e. no expectations on the availability of |=).

Primarily, this issue was meant to point out the mismatch of docs/implementation and not to get |= implemented for Shelf. In the end, I think updating the docs is all that is needed.

New changeset c97c2a0 by Serhiy Storchaka in branch 'main':
bpo-43443: Clarify difference between shelve objects and dicts (GH-27004)
c97c2a0

New changeset 563e057 by Miss Islington (bot) in branch '3.10':
bpo-43443: Clarify difference between shelve objects and dicts (GH-27004) (GH-27369)
563e057

New changeset 7482fff by Miss Islington (bot) in branch '3.9':
bpo-43443: Clarify difference between shelve objects and dicts (GH-27004) (GH-27370)
7482fff