Puzzled by list-appending behavior

[Terry Reedy]

On 5/26/2011 11:58 AM, MRAB wrote:
> On 26/05/2011 06:17, Chris Rebert wrote:
>> list.remove(), list.sort(), and list.extend() similarly return None
>> rather than the now-modified list.

> I'd just like to point out that it's a convention, not a rigid rule.
> Sometimes it's not followed, for example, dict.setdefault.

The rule for builtin collections is that mutation methods do not return 
the collection. If there is a member of the collection to return, they 
return that. Otherwise they return None.

list/set.pop and dict.popitem are other mutation methods that have a 
(former) member to return.

The rule applies to special methods like __getitem__ (returns an item) 
and __setitem__ (returns None). Since a.append(item) is *conceptually* 
equivalent to a.__setitem(len(a), item) (I know, it raises) and 
*actually* defined as a.__setitem(len(a):len(a), item), it should not be 
surprising that all three return None.

I think the above should be better documented.
http://bugs.python.org/issue12192
has some proposals. Comments there welcome.

In another post
On 5/26/2011 4:09 AM, Chris Rebert wrote:
 > I'm just surprised that the docstring doesn't explicitly state
 > "Returns None." by this point, given that this is such a common point
 > of newbie confusion.

I never noticed. After reading the above, I added this to the proposal 
above.



-- 
Terry Jan Reedy