gh-114648: Add IndexError exception to tutorial datastructures list.pop entry #114681
Conversation
To be consistent with the other two `list` methods (`remove` and `insert`) which have documented exceptions.
Misc/NEWS.d/next/Documentation/2024-01-28-14-31-53.gh-issue-114648.LkD8IM.rst
Outdated
Show resolved
Hide resolved
Doc/tutorial/datastructures.rst
Outdated
| will see this notation frequently in the Python Library Reference.) | ||
| is specified, ``a.pop()`` removes and returns the last item in the list. | ||
| It raises an :exc:`IndexError` if the list is empty or the index is | ||
| outside the list range. (The square brackets around the *i* in the method |
There was a problem hiding this comment.
I also think that we can remove this note. Since the [arg] notation is used all over the docs, here is not the right place for it.
There was a problem hiding this comment.
I agree--didn't want to do that on my own accord, but yes.
There was a problem hiding this comment.
If you think something should be removed, you can ask in a comment.
There was a problem hiding this comment.
Sorry to comment after merge!
Re:
(The square brackets around the i in the method signature denote that the parameter is optional, not that you should type square brackets at that position. You will see this notation frequently in the Python Library Reference.)
It's in the tutorial, which is introducing people to Python, and at the top of the page where this notation first appears.
Diátaxis says of tutorials:
A tutorial is an experience that takes place under the guidance of a tutor. A tutorial is always learning-oriented.
People do read through the tutorial from start to finish, and I think this is a good place to introduce and teach this notation.
terryjreedy
changed the title
terryjreedy
added
needs backport to 3.11
|
Thanks @ShivnarenSrinivasan for the PR, and @terryjreedy for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. |
…list.pop entry (pythonGH-114681) Remove redundant explanation of optional argument. (cherry picked from commit 57c3e77) Co-authored-by: srinivasan <shivnaren@gmail.com>
…list.pop entry (pythonGH-114681) Remove redundant explanation of optional argument. (cherry picked from commit 57c3e77) Co-authored-by: srinivasan <shivnaren@gmail.com>
|
GH-114841 is a backport of this pull request to the 3.12 branch. |
|
GH-114842 is a backport of this pull request to the 3.11 branch. |
…list.pop entry (python#114681) Remove redundant explanation of optional argument.
5 participants
To be consistent with the other two methods which have documented exceptions.
📚 Documentation preview 📚: https://cpython-previews--114681.org.readthedocs.build/