Hello. I hope that’s the right place to report this. I just noticed a simple typo at: 5. Data Structures — Python 3.14.3 documentation
list.pop([i]) has to be list.pop(i).
I think the [i] notation is to indicate that the argument i is optional. If absent the last element is popped or an error is raised if the list is empty.
1 Like
Optional arguments weren’t mentioned up until this point (or maybe I missed them) so I was confused. Thanks for the clarification.
I’d say it’s not really ideal… using POSIX-style-command-line syntax with brackets for optional in function signatures (a very long-standing Python docs tradition) is okay if it’s unambiguous, as it is later for list.index(). But in this particular case it follows an example in list.append() where brackets have been used for actual Python syntax, meaning list-containing-x. I don’t have a better suggestion, just kind of unlucky that we see the use of a single optional argument before (alphabetical) we see other samples of optional that might set the pattern in the brain.
1 Like
Thanks @BerkeYalci for reporting this! It’s not very helpful for the tutorial to suddenly use notation that’s not been introduced and isn’t familiar to everyone, especially in a tutorial.
On the docs Discord, @encukou suggested a quick fix of showing two signatures, list.pop() and list.pop(i) . And then three for the other one: index(x), index(x, start) and index(x, start, end).
@BerkeYalci, would you like to open a PR to fix this? This is the file to edit, and if I remember the syntax correctly, we want to change:
.. method:: list.pop([i])
to:
.. method:: list.pop()
.. method:: list.pop(i)
And similarly for the other one.
2 Likes
Would it be better to explain that notation in the previous section where functions were introduced? If this notation is used commonly in Python documentation, it would be better to explain it rather than change that particular section. (Unless it’s explained later in the tutorial. I haven’t progressed much so far).
1 Like
It should be:
.. method:: list.pop()
list.pop(i)
2 Likes
A big +1 to the proposal for multiple signatures instead of hoping that someone read an introductory description of what [] means. We have a very wide range of reader capabilities for these docs, particularly for the builtins.
6 Likes
We could also split the difference and have the optionals in brackets, but include the default:
list.pop([i = -1])
That’s closer to what you’d see if you checked the type signature of the function, and will cause anyone thinking it’s normal python bracket syntax to pause for a second since there’s an assignment operator there.
1 Like
A digression into optionality can become its own fraught topic. It’s difficult to summarize Python argument rules to anyone’s satisfaction and providing details seems to subvert the purpose of a tutorial.
2 Likes
In Doc/library/stdtypes.rst, it is documented as
.. method:: bytearray.pop(index=-1, /)
list.pop(index=-1, /)
:no-contents-entry:
:no-index-entry:
:no-typesetting:
.. method:: sequence.pop(index=-1, /)
It is a bug if it is documented in other way in other places.
1 Like
1 Like
I disagree: the tutorial’s goal is to explain to new learners. The reference’s goal is to be complete. Adding , /) to the tutorial will confuse more than it will enlighten. We already have a problem: it’s difficult to discover the meaning of that that compact notation in the reference guide. We shouldn’t add it to the tutorial.
3 Likes
But it’s already there, isn’t it? In the previous section that @BerkeYalci also already mentioned.
The pull request Serhiy linked to adds the slash to the tutorial. For example: gh-144837: Improve documentation for more collection methods by serhiy-storchaka · Pull Request #144841 · python/cpython · GitHub
But that seems to be exactly the right thing. After all, the tutorial already taught:
If there is no / in the function definition, there are no positional-only parameters.
So for example deque’s extend(iterable) should be extend(iterable, /). Otherwise it would claim that iterable isn’t positional-only, which it is.
I see your point, but tbh I’m not sure that syntax belongs in the tutorial. It’s little-used in real code, and there are many things not covered by the tutorial. It could be moved to a notation explanation in the reference guide.
I’d feel better about the whole thing if there was a better way to explain the notation where is appears. We have a “tool tip” (or whatever they are really called now), but it can’t provide a link to the section explaining it. Even the text isn’t great yet, it says “PEP 570” which is not a great way to explain it. Perhaps this is a controversial view, but I don’t think we should ever send people to PEPs to get explanations.
I don’t even understand how the tool tip is meant to work. The HTML is:
<abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr>
The cursor turns into a question mark when you hover, but if you click, nothing happens. You have to hover and do nothin, just wait, before the text appears. This is not a good way to explain it.
I know, I am getting off the main point here. Can people come up with better ways to help people understand this notation? Compact syntax is notoriously hard to search for, and we don’t have much flexibility in the HTML.
1 Like
This notation is the standard in typing stubs (and the language as a whole), which I feel most newer people are much more likely to actually look at with the widespread adoption of language servers.
If you’re using a modern text editor or IDE, you can usually ctrl+click a function to go to the source/type stub for it where this is the notation you see. If there is a lack of explanation of this syntax, I feel like it should probably be disambiguated or made very clear in the Tutorial root.
It seems like the current documentation format was chosen to match the EBNF format. Which I don’t think most people will interact with, whereas they will see func(pos, /, arg=<default>, *, kwarg_only=<default>) all over the standard library and common packages.