Raymond Hettinger wrote:
[Kristján Valur Jónsson]
In particular, append(), pop() and insert() modify the list length, which might confuse some subclasses.
These are all part of the most basic functions of list.
I have to chuckle a bit at that statement. When I posted the proposal to add .pop() (before there were formal 'PEP's), a couple of people accused my of trying to ruin Python. So agree, even if they did not, and I am glad you think so too ;-)
A subclasser should know that. They are different from swap() which is an optimization hack that breaks encapsulation and is not a basic function of lists. The docs are fine as-is.
Adding esoterica to the docs tends to make the docs harder to digest and less useful to people trying to learn the language.
As someone who hopes to be introducing Python to new people, I appreciate that you keep digestibility in mind, even if I occasionally forget in the quest for technical accuracy (which is also important). Terry Jan Reedy