Ezio Melotti <ezio.melo...@gmail.com> added the comment: I find this wording a little confusing: "For lists, sets, and dicts, methods that change the contents or order never return the instance. Instead, they return an item from the instance or, more commonly, None.". I would suggest to drop the second part because we don't care about those methods now and because some of them return None too, and simply use "Methods that mutate the object never return the instance.", possibly adding something like "to remind you that no new objects have been created.". The same wording can be used in both the Tutorial and the Library Manual (if readers happen to read it twice, it's even more likely that they will remember it).
FWIW the glossary has entries for "mutable" and "immutable", adding a note about this convention in the "mutable" entry might be a good idea too. Adding the '-> None' in the docstring is fine too, I'm not sure about the footnote. Terry, do you want to work on a patch? ---------- keywords: +easy nosy: +ezio.melotti stage: -> needs patch _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue12192> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
