[issue43996] Doc for mutable sequence pop() method implies argument is a slice or sequence.
New submission from Mark Sapiro <mark@msapiro.net>: In several places in the documentation including: ``` grep -rn 'pop.\[i\]' Lib/pydoc_data/topics.py:13184: '| "s.pop([i])" | retrieves the item at *i* ' Lib/pydoc_data/topics.py:13647: '| "s.pop([i])" | retrieves the item at ' Doc/tutorial/datastructures.rst:47:.. method:: list.pop([i]) Doc/library/array.rst:193:.. method:: array.pop([i]) Doc/library/stdtypes.rst:1116:| ``s.pop([i])`` | retrieves the item at *i* and | \(2) | ``` the mutable sequence and array `pop()` method is documented as shown above in a way that implies the argument to `pop()` is a slice or sequence when it is actually just an integer. All those references should be `pop(i)` rather than `pop([i])`. ---------- assignee: docs@python components: Documentation messages: 392551 nosy: docs@python, msapiro priority: normal severity: normal status: open title: Doc for mutable sequence pop() method implies argument is a slice or sequence. type: behavior versions: Python 3.10, Python 3.11, Python 3.8, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43996> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: In function signatures, the square brackets do not mean that there is a list. Instead, it is a convention used throughout the docs to mean that an argument is optional. In this case, s.pop([i]) means that both of these are valid calls: # retrieve and remove the value at a specific position somelist.pop(10) # retrieve and remove the rightmost value somelist.pop() Thank you for the report, but the documentation is correct. ---------- nosy: +rhettinger resolution: -> not a bug stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43996> _______________________________________
Mark Sapiro <mark@msapiro.net> added the comment: Thank you for the explanation which I understand and accept. I also fully (or maybe not quite fully) understand the use of square brackets to indicate optional arguments. It's just that in the context of the table at https://docs.python.org/3/library/stdtypes.html#mutable-sequence-types every other use of square brackets indicates a list or a slice and that's what confused me. Granted, all the other square bracket usage was not around a method argument, and I accept that the doc is correct, but I still found it confusing. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43996> _______________________________________
participants (2)
-
Mark Sapiro -
Raymond Hettinger