Raymond Hettinger added the comment: There isn't much defense against an overly literal reading of the docs. Both ``s.pop([i])`` and ``s.pop(i=-1)`` fail (the latter because pop doesn't take key word arguments and the docstring calls it "index". Also, you would have to define *s* and *i*.
FWIW, there is already a note to the effect, "The optional argument i defaults to -1, so that by default the last item is removed and returned." The [optional_arg] notation is used in a number of places in the docs and docstrings. It is also common with other languages as well and it is used in third-party Python references as well. Eric's initial suggestion of ``s.pop(i)`` is simply wrong and would make the docs worse. As a starting point, realize that the docs have worked well for a lot of people for a long time so there should be a reluctance to change them on a single misreading. The tutorial also includes the same notation, (see https://docs.python.org/3/tutorial/datastructures.html#more-on-lists ) and as far as I can tell, this has never been an issue. One other thought, the most common way to call pop() is without an argument (usually, if you use an argument, it is a performance bug). We want to make sure the docs don't suggest otherwise. Unless there is some strong objection, I recommend leaving the docs as-is. ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue24323> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
