Formatting of positional-only parameters in signatures
There is one more, hopefully last, open urgent question with the signature object. At the time we were working on the PEP 362, PEP 457 didn’t exist. Nor did we have any function with real positonal-only parameters, since there was no Argument Clinic yet. However, I implemented rudimentary support for them: “Parameter.POSITIONAL_ONLY” constant; “Signature.bind” and “Signature.bind_partial” fully support functions with positional-only parameters; “Signature.__str__” renders them distinctively from other kinds. The last point is the troublesome now. "Signature.__str__” renders positional-only parameters in ‘<>’ brackets, so in: foo(<ham>, <spam>, baz) “ham” and “spam” are positional-only. The choice of angle brackets was unfortunate, as, first of all, this wasn’t really discussed on python-dev, and second, it’s easy to think that those parameters are optional. Now, with the AC landing in 3.4, we need to decide how positional-only parameters will look like. Without starting a new discussion similar to what we had prior to PEP 457, I think we have three options: 1. Leave it as is. Obviously, the downside is the potential confusion with “optional” notation. 2. Adopt PEP 457 style: using “/“ to separate positional-only parameters from the rest. 3. Don’t use any notation, just render them as plain arguments: "foo(ham, spam, baz)". The downside here is that the users will be confused, and might try passing those parameters with keywords, or binding them with keywords. Thoughts? Yury
On 1/21/2014 10:59 AM, Yury Selivanov wrote:
There is one more, hopefully last, open urgent question with the signature object. At the time we were working on the PEP 362, PEP 457 didn’t exist. Nor did we have any function with real positonal-only parameters, since there was no Argument Clinic yet. However, I implemented rudimentary support for them:
“Parameter.POSITIONAL_ONLY” constant;
“Signature.bind” and “Signature.bind_partial” fully support functions with positional-only parameters;
“Signature.__str__” renders them distinctively from other kinds.
The last point is the troublesome now. "Signature.__str__” renders positional-only parameters in ‘<>’ brackets, so in:
foo(<ham>, <spam>, baz)
This amounts to a hidden new API.
“ham” and “spam” are positional-only. The choice of angle brackets was unfortunate, as, first of all, this wasn’t really discussed on python-dev, and second, it’s easy to think that those parameters are optional.
Now, with the AC landing in 3.4, we need to decide how positional-only parameters will look like.
Without starting a new discussion similar to what we had prior to PEP 457, I think we have three options:
1. Leave it as is. Obviously, the downside is the potential confusion with “optional” notation.
I think this this is bad, as it has not been discussed and agreed on, and might be changed. It is a plausible alternative to '/', but might possibly even have been rejected. I do not remember.
2. Adopt PEP 457 style: using “/“ to separate positional-only parameters from the rest.
I think this is what Larry proposed, but Nick opposed as a post-beta new feature.
3. Don’t use any notation, just render them as plain arguments: "foo(ham, spam, baz)". The downside here is that the users will be confused, and might try passing those parameters with keywords, or binding them with keywords.
This is the status quo for the docs (both notation and occasional confusion). I think signature should match until we agree on a new convention (and I think one is needed). The first thing to decide is whether to mark each position-only parameter or to put one marker after all of them. -- Terry Jan Reedy
Terry, On January 21, 2014 at 12:23:31 PM, Terry Reedy (tjreedy@udel.edu) wrote:
On 1/21/2014 10:59 AM, Yury Selivanov wrote: There is one more, hopefully last, open urgent question with the signature object. At the time we were working on the PEP 362, PEP 457 didn’t exist. Nor did we have any function with real positonal-only parameters, since there was no Argument Clinic yet. However, I implemented rudimentary support for them:
“Parameter.POSITIONAL_ONLY” constant;
“Signature.bind” and “Signature.bind_partial” fully support functions with positional-only parameters;
“Signature.__str__” renders them distinctively from other kinds.
The last point is the troublesome now. "Signature.__str__” renders positional-only parameters in ‘<>’ brackets, so in:
foo(, , baz)
This amounts to a hidden new API.
Yes, and no. This wasn’t documented and until 3.4 we had no real-world positonal-only parameters. So I think it’s OK to fix this now. Yury
On 22 Jan 2014 03:24, "Terry Reedy" <tjreedy@udel.edu> wrote:
On 1/21/2014 10:59 AM, Yury Selivanov wrote:
There is one more, hopefully last, open urgent question with the
signature
object. At the time we were working on the PEP 362, PEP 457 didn’t exist. Nor did we have any function with real positonal-only parameters, since there was no Argument Clinic yet. However, I implemented rudimentary support for them:
“Parameter.POSITIONAL_ONLY” constant;
“Signature.bind” and “Signature.bind_partial” fully support functions with positional-only parameters;
“Signature.__str__” renders them distinctively from other kinds.
The last point is the troublesome now. "Signature.__str__” renders positional-only parameters in ‘<>’ brackets, so in:
foo(<ham>, <spam>, baz)
This amounts to a hidden new API.
“ham” and “spam” are positional-only. The choice of angle brackets was unfortunate, as, first of all, this wasn’t really discussed on python-dev, and second, it’s easy to think that those parameters are optional.
Now, with the AC landing in 3.4, we need to decide how positional-only parameters will look like.
Without starting a new discussion similar to what we had prior to PEP 457, I think we have three options:
1. Leave it as is. Obviously, the downside is the potential confusion with “optional” notation.
I think this this is bad, as it has not been discussed and agreed on, and might be changed. It is a plausible alternative to '/', but might possibly even have been rejected. I do not remember.
It was the "we have to do something about this" short term fix we implemented for 3.3, that hasn't caused major problems due to the difficulties of creating such signatures in the first place. Argument Clinic changes that, since a variety of C level callables with this kind of signature will know be handled by the inspect module. I think it's actually tolerable to leave this in place for 3.4 as well, although I'd prefer to instead bring it into line with Argument Clinic.
2. Adopt PEP 457 style: using “/“ to separate positional-only parameters from the rest.
I think this is what Larry proposed, but Nick opposed as a post-beta new feature.
No, I think this is a good idea. It matches previous discussions with Guido and is more consistent with Argument Clinic. The exchange between me and Larry was about the more exotic signatures like range() that inspect.Signature currently can't even represent internally - handling *those* requires changes to the data model and public API of inspect.Signature, not just the string representation. By contrast, positional only parameter support is already there, it's just that the notation used in the string representation is inconsistent with Argument Clinic's notation.
3. Don’t use any notation, just render them as plain arguments: "foo(ham, spam, baz)". The downside here is that the users will be confused, and might try passing those parameters with keywords, or binding them with keywords.
This is the status quo for the docs (both notation and occasional confusion). I think signature should match until we agree on a new convention
We already rejected this option when inspect.Signature was first added. I don't see a good reason to reverse that decision now.
(and I think one is needed). The first thing to decide is whether to mark each position-only parameter or to put one marker after all of them.
That's (at least in part) what PEP 457 was about - documenting the format Guido had already given lukewarm approval to. It's the basis of Argument Clinic's syntax, and currently illegal Python syntax. Cheers, Nick.
-- Terry Jan Reedy
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe:
https://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com
participants (4)
-
Ethan Furman -
Nick Coghlan -
Terry Reedy -
Yury Selivanov