The data model and built-in types references disagree regarding ``sort()``

[AA-Turner]

Documentation

The data model and built-in types reference are inconsistent regarding whether sort() should be an expected mutable sequence method. This was noted by @serhiy-storchaka during review of #138474.

The data model, in 'Emulating container types' states:

Mutable sequences should provide methods [...] and sort(), like Python standard list objects.

The built-in types reference, in 'Mutable Sequence Types' stated¹:

The operations in the following table are defined on mutable sequence types

with sort() not included. Indeed, in stdtypes.rst, list.sort() is documented as an 'additional method', beyond the mutable sequence interface.

---

Relevant history:

• sort() was added to the datamodel in 83b2f8a (23/7/1998), and with the text effectively unchanged since.
• sort() was removed from the table in stdtypes.rst in 273069c (20/8/2012).
• A note that bytes (now bytearray) objects do not support sort() was added to the table in 226878c (31/8/2007). Before this, support for sort() was unqualified in stdtypes.rst.

---

Of the standard library sequence types, the only ones that implement a sort() method are list, collections.UserList, and multiprocessing.managers.BaseListProxy.

Given all of this, I propose that we update the data model to remove the reference to sort() as an expected sequence method. I think that this is the most pragmatic solution.

Linked PRs

• GH-138562: Remove sort() from the common sequence methods in the data model #138563
• [3.14] GH-138562: Remove sort() from the common sequence methods in the data model (GH-138563) #138760
• [3.13] GH-138562: Remove sort() from the common sequence methods in the data model (GH-138563) #140676

Footnotes

1. before the recent PR ↩

[AA-Turner]

@serhiy-storchaka reminds me in the linked PR that clear() is missing from the list of methods in the data model. I'm on mobile currently so can't check, but assuming that all the stdlib sequence types define it, I support adding clear() to that list in the data model.

A