This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author ezio.melotti
Recipients cvrebert, docs@python, ezio.melotti, rhettinger, terry.reedy
Date 2011-05-27.08:52:52
SpamBayes Score 1.8741209e-09
Marked as misclassified No
Message-id <1306486373.26.0.5159698283.issue12192@psf.upfronthosting.co.za>
In-reply-to
Content
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?
History
Date User Action Args
2011-05-27 08:52:53ezio.melottisetrecipients: + ezio.melotti, rhettinger, terry.reedy, cvrebert, docs@python
2011-05-27 08:52:53ezio.melottisetmessageid: <1306486373.26.0.5159698283.issue12192@psf.upfronthosting.co.za>
2011-05-27 08:52:52ezio.melottilinkissue12192 messages
2011-05-27 08:52:52ezio.melotticreate