Abstract

This PEP proposes a change to the way that function arguments areassigned to named parameter slots. In particular, it enables thedeclaration of “keyword-only” arguments: arguments that can onlybe supplied by keyword and which will never be automaticallyfilled in by a positional argument.

Rationale

The current Python function-calling paradigm allows arguments tobe specified either by position or by keyword. An argument can befilled in either explicitly by name, or implicitly by position.

There are often cases where it is desirable for a function to takea variable number of arguments. The Python language supports thisusing the ‘varargs’ syntax (*name), which specifies that any‘left over’ arguments be passed into the varargs parameter as atuple.

One limitation on this is that currently, all of the regularargument slots must be filled before the vararg slot can be.

This is not always desirable. One can easily envision a functionwhich takes a variable number of arguments, but also takes oneor more ‘options’ in the form of keyword arguments. Currently,the only way to do this is to define both a varargs argument,and a ‘keywords’ argument (**kwargs), and then manually extractthe desired keywords from the dictionary.

Specification

Syntactically, the proposed changes are fairly simple. The firstchange is to allow regular arguments to appear after a varargsargument:

defsortwords(*wordlist,case_sensitive=False):...

This function accepts any number of positional arguments, and italso accepts a keyword option called ‘case_sensitive’. Thisoption will never be filled in by a positional argument, butmust be explicitly specified by name.

Keyword-only arguments are not required to have a default value.Since Python requires that all arguments be bound to a value,and since the only way to bind a value to a keyword-only argumentis via keyword, such arguments are therefore ‘required keyword’arguments. Such arguments must be supplied by the caller, andthey must be supplied via keyword.

The second syntactical change is to allow the argument name tobe omitted for a varargs argument. The meaning of this is toallow for keyword-only arguments for functions that would nototherwise take a varargs argument:

defcompare(a,b,*,key=None):...

The reasoning behind this change is as follows. Imagine for amoment a function which takes several positional arguments, aswell as a keyword argument:

defcompare(a,b,key=None):...

Now, suppose you wanted to have ‘key’ be a keyword-only argument.Under the above syntax, you could accomplish this by adding avarargs argument immediately before the keyword argument:

defcompare(a,b,*ignore,key=None):...

Unfortunately, the ‘ignore’ argument will also suck up anyerroneous positional arguments that may have been supplied by thecaller. Given that we’d prefer any unwanted arguments to raise anerror, we could do this:

defcompare(a,b,*ignore,key=None):ifignore:# If ignore is not emptyraiseTypeError

As a convenient shortcut, we can simply omit the ‘ignore’ name,meaning ‘don’t allow any positional arguments beyond this point’.

(Note: After much discussion of alternative syntax proposals, theBDFL has pronounced in favor of this ‘single star’ syntax forindicating the end of positional parameters.)

Function Calling Behavior

The previous section describes the difference between the oldbehavior and the new. However, it is also useful to have adescription of the new behavior that stands by itself, withoutreference to the previous model. So this next section willattempt to provide such a description.

When a function is called, the input arguments are assigned toformal parameters as follows:

• For each formal parameter, there is a slot which will be usedto contain the value of the argument assigned to thatparameter.
• Slots which have had values assigned to them are marked as‘filled’. Slots which have no value assigned to them yet areconsidered ‘empty’.
• Initially, all slots are marked as empty.
• Positional arguments are assigned first, followed by keywordarguments.
• For each positional argument:
  • Attempt to bind the argument to the first unfilledparameter slot. If the slot is not a vararg slot, thenmark the slot as ‘filled’.
  • If the next unfilled slot is a vararg slot, and it doesnot have a name, then it is an error.
  • Otherwise, if the next unfilled slot is a vararg slot thenall remaining non-keyword arguments are placed into thevararg slot.
• For each keyword argument:
  • If there is a parameter with the same name as the keyword,then the argument value is assigned to that parameter slot.However, if the parameter slot is already filled, then thatis an error.
  • Otherwise, if there is a ‘keyword dictionary’ argument,the argument is added to the dictionary using the keywordname as the dictionary key, unless there is already anentry with that key, in which case it is an error.
  • Otherwise, if there is no keyword dictionary, and nomatching named parameter, then it is an error.
• Finally:
  • If the vararg slot is not yet filled, assign an empty tupleas its value.
  • For each remaining empty slot: if there is a default valuefor that slot, then fill the slot with the default value.If there is no default value, then it is an error.

In accordance with the current Python implementation, any errorsencountered will be signaled by raisingTypeError. (If you wantsomething different, that’s a subject for a different PEP.)

Backwards Compatibility

The function calling behavior specified in this PEP is a supersetof the existing behavior - that is, it is expected that anyexisting programs will continue to work.

Copyright

This document has been placed in the public domain.