This PEP proposes to introduce syntactic sugar f(x=) for the common pattern where a keyword argument has the same name as that of the variable corresponding to its value f(x=x).
Keyword argument syntax can become needlessly repetitive and verbose.
Consider the following call:
my_function( my_first_variable=my_first_variable, my_second_variable=my_second_variable, my_third_variable=my_third_variable, )
The case of a keyword argument name matching the variable name of its value is prevalent among Python libraries. This redundancy discourages use of named arguments and reduces readability by increasing visual noise.
RationaleThere are two ways to invoke a function with arguments: by position and by keyword. By being explicit, keyword arguments increase readability and minimise the risk of inadvertent transposition. On the flipside, positional arguments are often preferred simply to minimise verbosity and visual noise.
We contend that a simple syntactic sugar used to simplify this common pattern would confer numerous benefits:
Encourages use of named argumentsBy reducing the visual noise that established keyword argument syntax can cause, this syntax would encourage the use of named arguments, thereby increasing readability and reducing bugs from argument transposition.
Reduces verbosityBy minimising visual noise and in some cases lines of code, we can increase readability.
Encourages consistent variable namesA common problem is that semantically identical variables have different names depending on their contexts. This syntax would encourage authors to use the same variable name when calling a function as the argument name, which would increase consistency of variable names used and hence improve readability.
Highlights arguments not following this patternWith the current syntax, function calls where many arguments are forwarded from the local context can make other argument values easy to miss due to the visual noise. For example:
add_middleware(
excluded_urls=excluded_urls,
server_request=server_request,
client_request=client_request,
client_response=client_response,
span_details=_get_span_details(),
tracer=tracer,
meter=meter,
)
With this syntax, the exceptional arguments become easier to identify:
add_middleware(
excluded_urls=,
server_request=,
client_request=,
client_response=,
span_details=_get_span_details(),
tracer=,
meter=,
)
Applicability to dictionary construction
This syntax can be applied to dictionary construction where a similar pattern frequently occurs (where dictionary keys are identical the names of the variables assigned as their values), {"x": x, "y": y} or dict(x=x, y=y). With this feature, this can now also be trivially written as dict(x=, y=). Whether to further support similar syntax in dictionary literals is an open question beyond the scope of this PEP.
We propose to introduce syntactic sugar such that, if the value of a keyword argument is omitted from a function invocation, the argument’s value is inferred to be the variable matching that name at the invocation scope.
For example, the function invocation:
my_function(my_first_variable=, my_second_variable=, my_third_variable=)
Will be interpreted exactly equivalently to following in existing syntax:
my_function( my_first_variable=my_first_variable, my_second_variable=my_second_variable, my_third_variable=my_third_variable, )
If no variable matches that name in the invocation scope, a NameError is raised in an identical manner as would be with the established expanded syntax.
This proposal only pertains to function invocations; function definitions are unaffected by the syntax change. All existing valid syntax is unchanged.
Backwards CompatibilityOnly new syntax is added which was previously syntactically erroneous. No existing valid syntax is modified. As such, the changes proposed are fully backwards compatible.
Security ImplicationsThere are no security implications for this change.
Prior ArtPython already possesses a very similar feature in f-string interpolation where f'{x=}' is effectively expanded to f'x={x}' (see related GitHub issue).
Several modern languages provide similar features during function invocation, sometimes referred to as ‘punning’. For example:
f(x:, y:) is syntactic sugar for f(x: x, y: y). See the Ruby 3.1.0 release notes (search for “keyword arguments”).f(~x, ~y) is syntactic sugar for f(~x=x, ~y=y). See the ReasonML function documentation (search for “punning”).(.mult, .mop1, .data); is syntactic sugar for (.mult(mult), .mop1(mop1), .data(data));. See SystemVerilog Implicit Port Connections.f(x, y) is syntactic sugar for f(x: x, y: y). See The Jakt programming language.Beyond function invocation specifically, more languages offer similar features:
let+ x in … is syntactic sugar for let+ x = x in …. See OCaml: Short notation for variable bindings (let-punning).{ x, y } is syntactic sugar for {x: x, y: y}. See JavaScript: Object Initializer.User { x, y } is shorthand for User {x: x, y: y}. See Rust: Using the Field Init Shorthand.We analysed popular Python libraries from the last few years using this script to compute:
f(x=x) at invocation.f(x=x) at invocation.The purpose of this exercise was to compute statistics about the prevalence of this pattern and should not be interpreted as a recommendation that the proposed syntactic sugar should be applied universally.
Statistic Polars FastAPI Rich HTTPX Number of keyword arguments of the formf(x=x) at invocation 1,654 1,408 566 759 Percentage of keyword arguments of the form f(x=x) at invocation 15.83% 28.11% 15.74% 45.13% Lines saved 170 35 62 117
Based on this, we note that the f(x=x) keyword argument pattern is widespread, accounting for anywhere from 15% to just below half of all keyword argument uses depending on the codebase.
While this feature has been proposed on numerous occasions with several different forms [1] [2] [3] [4] [5], [6] we have opted to advocate for the f(x=) form for the following reasons:
f(x=) or f(=x) being by far the most commonly suggested syntax [1] [2] [6]. This strongly indicates that it is the most obvious notation.f'{var=}' syntax (established Pythonic style) and serves an almost identical purpose.To ease the communication of and search for this feature, it may also be valuable to provide this feature with a name, such as ‘keyword argument shorthand’.
Keen Python developers will likely hear about this feature through typical information channels, such as newsboards, social media, mailing lists, online forums, or word of mouth. Many more will encounter this feature while reading code and noting the omission of the value in a keyword argument at invocation, violating their expectations. We should ensure such developers have easy access to documentation that explains the semantics of this feature and that this documentation is easy to find when searching. For example, the Python Glossary and Tutorial may be updated accordingly and reasonable keywords may be used to help with search discoverability. A StackOverflow question could be written to help explain this feature to those searching for an explanation.
A teacher may explain this feature to new Python programmers as, “where you see an argument followed only by an equals sign, such as f(x=), this represents a keyword argument where the name of the argument and its value are the same. This can be written equivalently in the expanded notation, f(x=x).” Depending on a student’s background, a teacher might further compare this to equivalent syntax in other languages or to Python’s f-string syntax f"{x=}".
To understand this, a student of Python would need to be familiar with the basics of functions in addition to the existing keyword argument syntax. Given that this feature is a relatively straightforward syntactic sugar, it is reasonable that a student who possesses a grasp of keyword arguments will be able to absorb this concept quickly. This is evidenced by the success of the f-string syntax as well as similar features in other languages (see Prior Art).
Rejected IdeasMany alternative syntaxes have been proposed however no form other than f(=x) or f(x=) has garnered significant support. We here enumerate some of the most popular proposed alternatives and why we ultimately reject them.
f(a, b, *, x)
On a few occasions the idea has been floated to borrow the syntax from keyword-only function definitions.
In favour of this proposal:
However, we object that:
* could easily be missed in a long argument list and named arguments may be read as positional or vice versa.*. If so, then their relative position will be confusingly arbitrary, but if not, then an arbitrary grouping is enforced between different types of keyword arguments and reordering of arguments would be necessary if only one name (the argument or its value) was changed.* in function calls is well established and this proposal would introduce a new effect which could cause confusion. For example, f(a, *x, y) would mean something different than f(a, *, x, y).f(=x)
In favour of this form:
*args and **kwargs syntax for function calls.On the contrary:
= it is clear that the value is filled in automatically just as the value is clear in the typical keyword argument case.f(=a + b), since such expressions are acceptable after the equals sign in the current keyword argument syntax but not before it.f(%x) or f(:x) or f(.x)
Several flavours of this syntax have been proposed with the prefix form substituting another character for =. However, no such form has gained traction and the choice of symbol seems arbitrary compared to =. Additionally, there is less precedent in terms of existing language features (such as f-string) or other languages (such as Ruby).
There are only a few hard objections to the introduction of this syntactic sugar. Most of those not in favour of this feature are in the camp of ‘I wouldn’t use it’. However, over the extensive conversations about this feature, the following objections were the most common:
The syntax is uglyThis objection is the most common. On the contrary, we argue that:
We argue that:
f'{x=}' syntax.x= to x=x is a trivial feature and inherently significantly less complex than the popular *arg and **kwarg expansions.We recognise that, in an obvious sense, the argument value is ‘implicit’ in this proposed syntax. However, we do not think that this is what the Zen of Python is aiming to discourage.
In the sense that we take the Zen to be referring to, keyword arguments (for example) are more explicit than positional arguments where the argument name is omitted and impossible to tell from the local context. Conversely, the syntactic sugar for integers x += 1 is not more implicit than x = x + 1 in this sense, even though the variable is omitted from the right hand side, because it is immediately obvious from the local context what it is.
The syntax proposed in this PEP is much more closely analogous to the x += 1 example (although simpler since we do not propose to introduce a new operation). Moreover, by removing the barrier of visual noise introduced by the existing keyword argument syntax, this syntactic sugar will encourage the use of keyword arguments over positional ones, making typical Python codebases more explicit in general.
The same argument can be made against all syntax changes. This is a simple syntactic sugar, much as x += 1 is sugar for x = x + 1 when x is an integer. This isn’t tantamount to a ‘new way’ of passing arguments but a more readable notation for the same way.
A NameError would make the mistake clear in the large majority cases. There may be confusion if a variable from a broader scope has the same name as the original variable, so no NameError would be raised. However, this issue can also occur with keyword arguments using the current syntax (although arguably, this syntactic sugar could make it harder to spot). Moreover, having variables with the same name in different scopes is broadly considered to be bad practice and is discouraged by linters.
Code editors could highlight the issue based on static analysis – f(x=) is exactly equivalent to writing f(x=x). If x does not exist, modern editors have no problem highlighting the issue.
We recognise that, as ever, all syntax has the potential for misuse and so should be applied judiciously to improve codebases. In this case, if a parameter and its value have the same semantics in both contexts, that suggests that using this syntax is appropriate and will help ameliorate the risk of unintentional desynchronisation which harms readability.
However, if the two variables have different semantics, that suggests that this feature should not be used (since it encourages consistency) or perhaps that one or both of the variables should be renamed.
Recommendations for Using This SyntaxAs with any other language feature, the programmer should exercise their own judgement about whether it is prudent to use it in any given context. We do not recommend enforcing a rule to use the feature in all cases where it may be applicable, such as via lint rules or style guides.
As described in This syntax increases coupling, we propose that a reasonable rule of thumb would be to use this in cases where a parameter and its argument have the same semantics in order to reduce unintentional desynchronisation without causing inappropriate coupling.
Impact on Editing Using a plain text editorEditing with a plain text editor should generally be unaffected.
When renaming a variable using a ‘Find-Replace’ method, where this syntax is used the developer will come across the function argument at invocation (as they would if this syntax was not used). At that point, they can, as usual, decide whether to update the argument as well or expand to the full f(x=x) syntax.
As with the current syntax, a ‘Find-Replace All’ method would fail since the keyword argument would not exist at function definition, in the vast majority of cases.
If the developer leaves the argument name unchanged and forgets to update its value, a NameError will typically be raised as described in Renaming the variable in the calling context will break the code.
In response to community feedback, we include some suggestions regarding how IDEs could handle this syntax. However, we defer to the domain experts developing IDEs to use their discretion.
Most considerations are made simple by recognising that f(x=) is just syntactic sugar for f(x=x) and should be treated the same as at present.
IDEs typically offer a feature to highlight code that may cause a NameError. We recommend that this syntax be treated similarly to the expanded form f(x=x) to identify and highlight cases where the elided variable may not exist. What visual cue may be used to highlight these cases may be the same or different from that which would be used with the current syntax, depending on the IDE.
There are a few possible ways that a ‘jump to definition’ feature could be implemented depending on the caret/cursor position.
One option is to:
= in our proposed syntaxAnother, potentially complementary, option would be to expand the syntax visually on mouseover and enable a Ctrl+Click (or Cmd+Click) to the definition of the variable.
IDEs frequently highlight matching code references to the value at the current caret/cursor position. With this shorthand syntax, when the caret/cursor is on the argument name it may be valuable to either:
There are a few ways that IDEs may wish to support a ‘Rename symbol’ feature for this syntax. For example, if the argument is being renamed, the IDE may:
The last option seems to be the most preferable to reduce unintentional desynchronisation of names while highlighting the changes to the programmer.
Reference ImplementationA proposed implementation for CPython has been provided by @Hels15. We will extend this implementation to add an AST node attribute indicating for keywords whether the value was elided. Otherwise the AST will remain unchanged.
References CopyrightThis document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4