I suspect I've missed the boat on this one (certainly for 3.3.0), but
here goes. The new TypeError reporting for bad function calls is a
huge improvement (thanks Benjamin!), but I have one small nitpick:
what *is* a positional argument? For example:
I think it's confusing to describe 'x' as a positional argument. It's
a required formal parameter, certainly. But a caller of 'f' could
pass 'x' either by position or by 'keyword'.
When running training (generally Python 2.6 or 2.7 based), I
frequently have to devote some time to unravelling student confusion
between 'arguments passed by keyword' on one hand and 'optional formal
parameters' on the other. The outline of the explanation goes
something like:
(0) Preamble: be careful to separate out details of function calling
from those of function definition; distinguish formal parameters from
actual arguments.
(1) On the function *definition* side, formal parameters may be either
*required* or *optional*.
(2) On the function *calling* side, actual arguments may be passed
either positionally or by keyword.
(3) The notions in (1) and (2) are entirely orthogonal!
(3a) (Although in practice, callers tend to use pass-by-keyword for
optional formal parameters.)
That's all for Python 2; Python 3, of course, requires a bit more
explanation related to the keyword-only arguments.
There already seems to be a fair amount of confusion in the Python
world about point (3); I've seen professional Python training slides
that show how to define optional formal parameters under the heading
"keyword arguments".
I submit that the word 'positional' in the TypeError message
exacerbates this confusion, and that little would be lost by simply
dropping it from the exception message.
On Thu, Sep 20, 2012 at 9:56 PM, Mark Dickinson <dicki...@gmail.com> wrote:
> I submit that the word 'positional' in the TypeError message
> exacerbates this confusion, and that little would be lost by simply
> dropping it from the exception message.
+1 for using the unqualified "argument" in these error messages to
mean "positional or keyword argument" (inspect.Parameter spells it out
as POSITIONAL_OR_KEYWORD, but the full phrase is far too verbose for
an error message).
On Thu, Sep 20, 2012 at 1:21 PM, Nick Coghlan <ncogh...@gmail.com> wrote:
> +1 for using the unqualified "argument" in these error messages to
> mean "positional or keyword argument" (inspect.Parameter spells it out
> as POSITIONAL_OR_KEYWORD, but the full phrase is far too verbose for
> an error message).
Ah yes; I see that 'positional or keyword' is a more accurate term
(but agree it's unwieldy for an error message). I also see that I was
naive to think that the 'fix' is as simple as dropping the word
'positional':
On Thu, Sep 20, 2012 at 10:59 PM, Mark Dickinson <dicki...@gmail.com> wrote:
> Perhaps this simply isn't worth worrying about, especially since the
> current error messages are all but certain to make it into the 3.3
> release.
No "all but" about it at this point - the earliest they could change
again is 3.3.1. Hopefully the new signature inspection support will
help explain some of the intricacies of binding argument values to
parameter names :)
I tried to define the error messages in terms of the callee's
signature. I call the formals that are not variadic, keyword variadic,
or keyword-only, positional. For example, in
def f(a, b, c, *args, d):
pass
a, b, and c are positional. Hence the "positional" in error messages.
As you noted in your next message, keyword-only arguments need to be
distinguished from these "positional" arguments somehow. Maybe it
helps to think of "positional" to mean "the only formals you can pass
to with position" (excepting variadic ones).
On Thu, Sep 20, 2012 at 7:12 AM, Benjamin Peterson <benja...@python.org> wrote:
> def f(a, b, c, *args, d):
> pass
> a, b, and c are positional. Hence the "positional" in error messages.
> As you noted in your next message, keyword-only arguments need to be
> distinguished from these "positional" arguments somehow. Maybe it
> helps to think of "positional" to mean "the only formals you can pass
> to with position" (excepting variadic ones).
That is how I think of "positional".
However, the other wrinkle is that some arguments really are
"position-only," for example:
I think it is a defect of our documentation that we don't have a way
to distinguish between "positional" and "position-only" arguments in
the function signature notation we use in our documentation, leading
to issues like this one:
"accept keyword arguments on most base type methods and builtins":
Benjamin Peterson <benja...@python.org> wrote:
> 2012/9/20 Mark Dickinson <dicki...@gmail.com>:
> > Thoughts?
> I tried to define the error messages in terms of the callee's
> signature. I call the formals that are not variadic, keyword variadic,
> or keyword-only, positional. For example, in
> def f(a, b, c, *args, d):
> pass
> a, b, and c are positional. Hence the "positional" in error messages.
But since the error message gives the name of the parameter, there
doesn't seem to be a point to add that it's "positional": it can be
trivially deduced from the function signature.
On Thu, Sep 20, 2012 at 3:12 PM, Benjamin Peterson <benja...@python.org> wrote:
> As you noted in your next message, keyword-only arguments need to be
> distinguished from these "positional" arguments somehow. Maybe it
> helps to think of "positional" to mean "the only formals you can pass
> to with position" (excepting variadic ones).
And excepting optional ones, too, right? E.g., the c in
def foo(a, b, c=1, *args, d):
pass
can be passed to by position, but isn't "positional".
> I'm certainly open to suggestions.
Yes, I don't have a good alternative suggestion. If we could find a
suitable word and bless it in the documentation, it might make it
easier to make clear and accurate statements about Python's function
calling.
On Thu, Sep 20, 2012 at 4:14 PM, Benjamin Peterson <benja...@python.org> wrote:
> 2012/9/20 Mark Dickinson <dicki...@gmail.com>:
>> And excepting optional ones, too, right? E.g., the c in
>> def foo(a, b, c=1, *args, d):
>> pass
>> can be passed to by position, but isn't "positional".
> Why not?
Ah, okay; I was assuming (wrongly) that your definition of
'positional' was intended to exclude these. My bad.
On Thu, Sep 20, 2012 at 7:12 AM, Benjamin Peterson <benja...@python.org> wrote:
> 2012/9/20 Mark Dickinson <dicki...@gmail.com>:
>> Thoughts?
> I tried to define the error messages in terms of the callee's
> signature. I call the formals that are not variadic, keyword variadic,
> or keyword-only, positional. For example, in
> def f(a, b, c, *args, d):
> pass
> a, b, and c are positional. Hence the "positional" in error messages.
No -- Mark's point is that (even given this syntax) you *could* pass
them using keywords.
I think Brett's got it right and we should just refer to a and b as
'arguments'. For d, we should use keyword arguments (or, in full,
keyword-only arguments). That's enough of a distinction.
Of course, in a specific call, we can continue to refer to positional
and keyword arguments based on the actual syntax used in the call.
Maybe this is also a good time to start distinguishing between
arguments (what you pass, call syntax) and parameters (what the
function receives, function definition syntax)?
> As you noted in your next message, keyword-only arguments need to be
> distinguished from these "positional" arguments somehow. Maybe it
> helps to think of "positional" to mean "the only formals you can pass
> to with position" (excepting variadic ones).
> 2012/9/20 Mark Dickinson <dicki...@gmail.com>:
> > And excepting optional ones, too, right? E.g., the c in
> > def foo(a, b, c=1, *args, d):
> > pass
> > can be passed to by position, but isn't "positional".
> Why not?
> >>> def f(a, b, c=3): pass
> ...
> >>> f()
> Traceback (most recent call last):
> File "<stdin>", line 1, in <module>
> TypeError: f() missing 2 required positional arguments: 'a' and 'b'
> >>> f(1, 2, 3, 4)
> Traceback (most recent call last):
> File "<stdin>", line 1, in <module>
> TypeError: f() takes from 2 to 3 positional arguments but 4 were given
The difference between c and a,b is that c is optional, whereas a and b are
required.
In Python 2.x there are named arguments and variadic arguments. There are
two types of named arguments: required and optional. There are also two
types of variadic arguments: positional and keyword. i.e.:
named
required
not-required
variadic
positional
keyword
In Python 2.x all named parameters can be passed by position or by keyword,
so it doesn't make sense to use those concepts to distinguish them. On the
other hand, for variadic parameters that distinction is crucial.
In Python 3.x there are two orthogonal properties for each named parameter.
The parameter can be required or optional as before, and then the parameter
can be keyword-only or positional. There are 4 combinations of these two
properties:
def f(a, b=1, *, c, d=3): pass
| required | optional
positional | a | b
kwonly | c | d
Since there are two orthogonal properties of a parameter (requiredness and
positionness) it makes perfect sense to use two adjectives to describe each
parameter as is the case for the error message shown at the start of this
thread:
Mark Dickinson wrote:
>>>> def f(x): pass
>...
>>>> f()
>Traceback (most recent call last):
> File "<stdin>", line 1, in <module>
>TypeError: f() missing 1 required positional argument: 'x'
I would say that the only problem with this terminology is that it would be
good to think of a word to replace "keyword-only" (positionless?).
> I suspect I've missed the boat on this one (certainly for 3.3.0), but
> here goes. The new TypeError reporting for bad function calls is a
> huge improvement (thanks Benjamin!), but I have one small nitpick:
> what *is* a positional argument? For example:
> I think it's confusing to describe 'x' as a positional argument. It's
> a required formal parameter, certainly. But a caller of 'f' could
> pass 'x' either by position or by 'keyword'.
> When running training (generally Python 2.6 or 2.7 based), I
> frequently have to devote some time to unravelling student confusion
> between 'arguments passed by keyword' on one hand and 'optional formal
> parameters' on the other. The outline of the explanation goes
> something like:
> (0) Preamble: be careful to separate out details of function calling
> from those of function definition; distinguish formal parameters from
> actual arguments.
> (1) On the function *definition* side, formal parameters may be either
> *required* or *optional*.
and optional params may or may not have an overt default object
> (2) On the function *calling* side, actual arguments may be passed
> either positionally or by keyword.
Sometimes position is required, sometimes keyword is required, and usually both are allowed.
> (3) The notions in (1) and (2) are entirely orthogonal!
Moreover, all six combinations of passing mode and requirement are possible, although for Python functions, some combinations require setup code in addition to the header. Built-in print accepts an indefinite number of optional no-default position-only args followed by up to three optional defaulted keyword-only args. print() emits the default end='\n'.
> (3a) (Although in practice, callers tend to use pass-by-keyword for
> optional formal parameters.)
> That's all for Python 2; Python 3, of course, requires a bit more
> explanation related to the keyword-only arguments.
> There already seems to be a fair amount of confusion in the Python
> world about point (3);
I have strongly suggested that the docs not adds to the confusion in at least one tracker discussion.
> I've seen professional Python training slides
> that show how to define optional formal parameters under the heading
> "keyword arguments".
> I submit that the word 'positional' in the TypeError message
> exacerbates this confusion, and that little would be lost by simply
> dropping it from the exception message.
For this example that would be sufficient, but your later message shows that we need a one-word abbreviations for positional-or-keyword: either something indicating that its default nature -- 'normal', 'standard', 'flexible', 'usual', 'typical' -- or something indicating its dual nature (possibly coined or metaphorical -- 'pos-key', 'bi-mode', 'dual-mode', 'Janus-like'.
> 2012/9/20 Mark Dickinson <dicki...@gmail.com>:
>> Thoughts?
> I tried to define the error messages in terms of the callee's
> signature. I call the formals that are not variadic, keyword variadic,
> or keyword-only, positional. For example, in
> def f(a, b, c, *args, d):
> pass
> a, b, and c are positional. Hence the "positional" in error messages.
They are positional-or-keyword without defaults.
> As you noted in your next message, keyword-only arguments need to be
> distinguished from these "positional" arguments somehow.
Positional-or-keyword and positional-only also need to be distinguished.
'Positional' is ambiguous. One problem for standardized error messages is the the header info does not always tell the complete story.
> I'm certainly open to suggestions.
I gave several suggestions for 'positional-or-keyword' in my response to Mark.
On Thu, Sep 20, 2012 at 8:52 AM, Guido van Rossum <gu...@python.org> wrote:
> On Thu, Sep 20, 2012 at 7:12 AM, Benjamin Peterson <benja...@python.org> wrote:
>> I tried to define the error messages in terms of the callee's
>> signature. I call the formals that are not variadic, keyword variadic,
>> or keyword-only, positional. For example, in
> Maybe this is also a good time to start distinguishing between
> arguments (what you pass, call syntax) and parameters (what the
> function receives, function definition syntax)?
The glossary is one place to start making this distinction. It
currently has entries for "argument," "positional argument," and
"keyword argument" that could perhaps use a review from this
discussion. For example:
The entries currently blur the distinction between the calling and
definition perspectives. Ideally, the glossary definitions of these
terms would match and be consistent with their usage in error
messages.
> Maybe this is also a good time to start distinguishing between
> arguments (what you pass, call syntax) and parameters (what the
> function receives, function definition syntax)?
One standard usage (and mine) is that parameters are the (local) names that arguments get bound to. I *believe* that Knuth used this also, but I cannot find a reference. Here is the CS part of
https://en.wikipedia.org/wiki/Parameters See the last sentence.
"Computer science
Main article: Parameter (computer science)
When the terms formal parameter and actual parameter are used, they generally correspond with the definitions used in computer science. In the definition of a function such as
f(x) = x + 2,
x is a formal parameter. When the function is used as in
y = f(3) + 5 or just the value of f(3),
3 is the actual parameter value that is substituted for the formal parameter in the function definition. These concepts are discussed in a more precise way in functional programming and its foundational disciplines, lambda calculus and combinatory logic.
In computing, parameters are often called arguments, and the two words are used interchangeably. However, some computer languages such as C define argument to mean actual parameter (i.e., the value), and parameter to mean formal parameter."
> On Thu, Sep 20, 2012 at 1:21 PM, Nick Coghlan<ncogh...@gmail.com> wrote:
>> +1 for using the unqualified "argument" in these error messages to
>> mean "positional or keyword argument" (inspect.Parameter spells it out
>> as POSITIONAL_OR_KEYWORD, but the full phrase is far too verbose for
>> an error message).
> Ah yes; I see that 'positional or keyword' is a more accurate term
> (but agree it's unwieldy for an error message). I also see that I was
> naive to think that the 'fix' is as simple as dropping the word
> 'positional':
> If the word 'positional' were dropped here, it would give the
> incorrect impression that f only requires one argument.
I don't expect error messages to give a complete catalog of every
problem with a specific function call. If f() reports that required
argument 'a' is missing, that does not imply that no other required
arguments are also missing. I think it is perfectly acceptable to
not report the missing 'b' until the missing 'a' is resolved.
But I do expect error messages to be accurate. +1 to remove the
word "positional" from the message.
> On Thu, 20 Sep 2012 10:12:04 -0400
> Benjamin Peterson<benja...@python.org> wrote:
>> 2012/9/20 Mark Dickinson<dicki...@gmail.com>:
>>> Thoughts?
>> I tried to define the error messages in terms of the callee's
>> signature. I call the formals that are not variadic, keyword variadic,
>> or keyword-only, positional. For example, in
>> def f(a, b, c, *args, d):
>> pass
>> a, b, and c are positional. Hence the "positional" in error messages.
> But since the error message gives the name of the parameter, there
> doesn't seem to be a point to add that it's "positional": it can be
> trivially deduced from the function signature.
Furthermore, since the parameter has a name, it can be given as a
keyword argument. Describing positional-or-keyword as "positional"
is misleading, although I admit that I often do that too. I think that
"positional or keyword argument" is too wordy, and is ambiguous as to
whether the argument can be given as either positional or keyword, or
we're unsure which of the two it is.
"Named positional argument" is more accurate, but also too wordy, and
it relies on the reader knowing enough about Python's calling semantics
to infer that therefore it can be given as positional or keyword style.
Since this is way too complicated to encapsulate in a short error
message, I'm with Nick and Mark that "positional" should be dropped
unless the argument is positional-only.
> I would say that the only problem with this terminology is that it would be
> good to think of a word to replace "keyword-only" (positionless?).
I disagree completely. I think keyword-only is the right terminology to
use for arguments which can only be passed by keyword. It is *positional*
that is questionable, since named positional arguments can be given by
keyword.
I would like to see error messages reserve the terms:
1) "positional" for explicitly positional-only parameters;
2) "keyword" for explicitly keyword-only parameters;
(I don't mind whether or not they use "-only" as a suffix)
For normal, named-positional-or-keyword arguments, just use an unqualified
"argument".
<chris.jerdo...@gmail.com> wrote:
> On Thu, Sep 20, 2012 at 8:52 AM, Guido van Rossum <gu...@python.org> wrote:
>> On Thu, Sep 20, 2012 at 7:12 AM, Benjamin Peterson <benja...@python.org> wrote:
>>> I tried to define the error messages in terms of the callee's
>>> signature. I call the formals that are not variadic, keyword variadic,
>>> or keyword-only, positional. For example, in
>> Maybe this is also a good time to start distinguishing between
>> arguments (what you pass, call syntax) and parameters (what the
>> function receives, function definition syntax)?
> The glossary is one place to start making this distinction. It
> currently has entries for "argument," "positional argument," and
> "keyword argument" that could perhaps use a review from this
> discussion. For example:
> The entries currently blur the distinction between the calling and
> definition perspectives. Ideally, the glossary definitions of these
> terms would match and be consistent with their usage in error
> messages.
I took the liberty to create an issue in the tracker to settle on and
document preferred terminology in the area of positional/keyword
arguments/parameters, etc. The issue is here:
Steven D'Aprano wrote:
> On 20/09/12 22:59, Mark Dickinson wrote:
>> On Thu, Sep 20, 2012 at 1:21 PM, Nick Coghlan<ncogh...@gmail.com> wrote:
>>> +1 for using the unqualified "argument" in these error messages to
>>> mean "positional or keyword argument" (inspect.Parameter spells it out
>>> as POSITIONAL_OR_KEYWORD, but the full phrase is far too verbose for
>>> an error message).
>> Ah yes; I see that 'positional or keyword' is a more accurate term
>> (but agree it's unwieldy for an error message). I also see that I was
>> naive to think that the 'fix' is as simple as dropping the word
>> 'positional':
>> If the word 'positional' were dropped here, it would give the
>> incorrect impression that f only requires one argument.
> I don't expect error messages to give a complete catalog of every
> problem with a specific function call. If f() reports that required
> argument 'a' is missing, that does not imply that no other required
> arguments are also missing. I think it is perfectly acceptable to
> not report the missing 'b' until the missing 'a' is resolved.
I disagree. There is no reason (that I'm aware of ;) that the missing 'b' cannot be noticed and reported at the same time as the missing 'a'.
> But I do expect error messages to be accurate. +1 to remove the
> word "positional" from the message.
And then it's still not accurate as 'b' is also a required argument that is missing. Unless and until all error messages adopt your proposed 'positional argument', 'argument', 'keyword argument' *and* describe _all_ the problems with the call confusion will reign supreme.
>> I don't expect error messages to give a complete catalog of every
>> problem with a specific function call. If f() reports that required
>> argument 'a' is missing, that does not imply that no other required
>> arguments are also missing. I think it is perfectly acceptable to
>> not report the missing 'b' until the missing 'a' is resolved.
> I disagree. There is no reason (that I'm aware of ;) that the missing
>'b' cannot be noticed and reported at the same time as the missing 'a'.
Listing every missing argument does not scale well as the number of
arguments increases.
We've already had this terminology discussion and documented the results in
PEP 362. The rest of the docs may require updates to be brought in line
with that.
Cheers,
Nick.
--
Sent from my phone, thus the relative brevity :)
