-
-
Notifications
You must be signed in to change notification settings - Fork 33.9k
bpo-36540: Documentation for PEP570 - Python positional only arguments #13202
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
|
CC: @pganssle @mariocj89 |
pganssle
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Grammar and style looks pretty much fine. Mainly the refcounts.dat file needs to be updated.
I will say that in the example of the four functions, I would probably group the "explanation of the function" parts a bit differently, because the explanation of the syntax is separated from the demonstration of the syntax, which means you have to either remember it perfectly or scroll up.
I'd rather see something like:
"A standard function definition does not restrict how arguments are passed, so they can be passed either by position or keyword:
>>> def standard_arg(arg):
... print(arg)
>>> standard_arg(2)
2
>>> standard_arg(arg=2)
2If an argument is specified to be positional only, it is an error to pass it by keyword:
>>> def pos_only_arg(arg, /):
... print(arg)
>>> pos_only_arg(2)
2
>>> pos_only_arg(arg=2)
Traceback (most recent call last):
..."
I understand that it's a trade-off, though. In your version, the contrast between the different syntaxes is highlighted, since all the definitions are right next to each other, whereas in my version the syntax is kept close to the explanation.
mariocj89
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looking great, some small optional nitpicks though I am not a native speaker :).
|
@pganssle I think I prefer to highlight the contrast between the different syntaxes (and having the definition all together) more than how they are used (although is a very fine-grained detail). But I would like more opinions on this. @mariocj89 @willingc What do you think? |
Doc/tutorial/controlflow.rst
Outdated
|
|
||
| Looking at this in a bit more detail, it is possible to mark certain parameters | ||
| as *positional-only*. If *positional-only*, the parameters' order matters, and | ||
| the parameters cannot be passed by keyword. Positional-only parameters would |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think change "would be" to "are".
|
|
||
| * Use positional-only if you want the name of the parameters to not be | ||
| available to the user. This is useful when parameter names have no real | ||
| meaning, if you want to enforce the order of the arguments when the function |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Or if you believe the name of the parameter may change in the future, and a change of parameter name can be considered a change in API ?
I've seen a couple of time def foo(filename) -> def foo(filename_or_buffer), which people don't realise is an api change.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps at end of these bullets, add a bullet. For an API, use positional only to prevent breaking API changes if the parameter's name changes.
|
What is the status of this PR? Is it ready to be merged? |
willingc
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A few minor corrections/comments. Thanks @pablogsal 👍
|
|
||
| * Use positional-only if you want the name of the parameters to not be | ||
| available to the user. This is useful when parameter names have no real | ||
| meaning, if you want to enforce the order of the arguments when the function |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps at end of these bullets, add a bullet. For an API, use positional only to prevent breaking API changes if the parameter's name changes.
|
What is this waiting for? It's documentation -- it's easy to iterate on. |
Co-Authored-By: Carol Willing <carolcode@willingconsulting.com>
Co-Authored-By: Carol Willing <carolcode@willingconsulting.com>
|
@willingc: Please replace |
|
Thanks all for moving this forward. If there are additional doc changes, please file another PR. 🎉 |
|
Thank you all for the review and the helpful comments and insights! ❤️ |
python#13202) * bpo-36540: Documentation for PEP570 - Python positional only arguments * fixup! bpo-36540: Documentation for PEP570 - Python positional only arguments * Update reference for compound statements * Apply suggestions from Carol Co-Authored-By: Carol Willing <carolcode@willingconsulting.com> * Update Doc/tutorial/controlflow.rst Co-Authored-By: Carol Willing <carolcode@willingconsulting.com> * Add extra bullet point and minor edits
https://bugs.python.org/issue36540