CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 570 – Python Positional-Only Parameters | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0570/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 570 – Python Positional-Only Parameters | peps.python.org'> <meta property="og:description" content="This PEP proposes to introduce a new syntax, /, for specifying positional-only parameters in Python function definitions."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0570/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP proposes to introduce a new syntax, /, for specifying positional-only parameters in Python function definitions."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 570</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 570 – Python Positional-Only Parameters</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Larry Hastings <larry at hastings.org>, Pablo Galindo <pablogsal at python.org>, Mario Corchero <mariocj89 at gmail.com>, Eric N. Vander Weele <ericvw at gmail.com></dd> <dt class="field-even">BDFL-Delegate:</dt> <dd class="field-even">Guido van Rossum <guido at python.org></dd> <dt class="field-odd">Discussions-To:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-570-python-positional-only-parameters/1078">Discourse thread</a></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">20-Jan-2018</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.8</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a><ul> <li><a class="reference internal" href="#history-of-positional-only-parameter-semantics-in-python">History of Positional-Only Parameter Semantics in Python</a></li> <li><a class="reference internal" href="#problems-without-positional-only-parameters">Problems Without Positional-Only Parameters</a><ul> <li><a class="reference internal" href="#challenges-for-library-authors">Challenges for Library Authors</a></li> <li><a class="reference internal" href="#challenges-for-users-of-an-api">Challenges for Users of an API</a></li> </ul> </li> <li><a class="reference internal" href="#benefits-of-positional-only-parameters">Benefits of Positional-Only Parameters</a><ul> <li><a class="reference internal" href="#empowering-library-authors">Empowering Library Authors</a></li> <li><a class="reference internal" href="#improving-language-consistency">Improving Language Consistency</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#performance">Performance</a></li> <li><a class="reference internal" href="#maintainability">Maintainability</a></li> <li><a class="reference internal" href="#logical-ordering">Logical ordering</a></li> <li><a class="reference internal" href="#compatibility-for-pure-python-and-c-modules">Compatibility for Pure Python and C Modules</a></li> <li><a class="reference internal" href="#consistency-in-subclasses">Consistency in Subclasses</a></li> <li><a class="reference internal" href="#optimizations">Optimizations</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#syntax-and-semantics">Syntax and Semantics</a></li> <li><a class="reference internal" href="#full-grammar-specification">Full Grammar Specification</a></li> <li><a class="reference internal" href="#semantic-corner-case">Semantic Corner Case</a></li> <li><a class="reference internal" href="#origin-of-as-a-separator">Origin of “/” as a Separator</a></li> </ul> </li> <li><a class="reference internal" href="#how-to-teach-this">How To Teach This</a><ul> <li><a class="reference internal" href="#positional-or-keyword-arguments">Positional-or-Keyword Arguments</a></li> <li><a class="reference internal" href="#positional-only-parameters">Positional-Only Parameters</a></li> <li><a class="reference internal" href="#keyword-only-arguments">Keyword-Only Arguments</a></li> <li><a class="reference internal" href="#function-examples">Function Examples</a></li> <li><a class="reference internal" href="#recap">Recap</a></li> </ul> </li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#do-nothing">Do Nothing</a></li> <li><a class="reference internal" href="#decorators">Decorators</a></li> <li><a class="reference internal" href="#per-argument-marker">Per-Argument Marker</a></li> <li><a class="reference internal" href="#using-as-a-per-argument-marker">Using “__” as a Per-Argument Marker</a></li> <li><a class="reference internal" href="#group-positional-only-parameters-with-parentheses">Group Positional-Only Parameters With Parentheses</a></li> <li><a class="reference internal" href="#after-separator-proposal">After Separator Proposal</a></li> </ul> </li> <li><a class="reference internal" href="#thanks">Thanks</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP proposes to introduce a new syntax, <code class="docutils literal notranslate">/</code>, for specifying positional-only parameters in Python function definitions. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. When designing APIs (application programming interfaces), library authors try to ensure correct and intended usage of an API. Without the ability to specify which parameters are positional-only, library authors must be careful when choosing appropriate parameter names. This care must be taken even for required parameters or when the parameters have no external semantic meaning for callers of the API. In this PEP, we discuss: <ul class="simple"> <li>Python’s history and current semantics for positional-only parameters</li> <li>the problems encountered by not having them</li> <li>how these problems are handled without language-intrinsic support for positional-only parameters</li> <li>the benefits of having positional-only parameters</li> </ul> Within context of the motivation, we then: <ul class="simple"> <li>discuss why positional-only parameters should be a feature intrinsic to the language</li> <li>propose the syntax for marking positional-only parameters</li> <li>present how to teach this new feature</li> <li>note rejected ideas in further detail</li> </ul> </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> <section id="history-of-positional-only-parameter-semantics-in-python"> <h3><a class="toc-backref" href="#history-of-positional-only-parameter-semantics-in-python" role="doc-backlink">History of Positional-Only Parameter Semantics in Python</a></h3> Python originally supported positional-only parameters. Early versions of the language lacked the ability to call functions with arguments bound to parameters by name. Around Python 1.0, parameter semantics changed to be positional-or-keyword. Since then, users have been able to provide arguments to a function either positionally or by the keyword name specified in the function’s definition. In current versions of Python, many CPython “builtin” and standard library functions only accept positional-only parameters. The resulting semantics can be easily observed by calling one of these functions using keyword arguments: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> help(pow) ... pow(x, y, z=None, /) ... >>> pow(x=5, y=3) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: pow() takes no keyword arguments </pre></div> </div> <code class="docutils literal notranslate">pow()</code> expresses that its parameters are positional-only via the <code class="docutils literal notranslate">/</code> marker. However, this is only a documentation convention; Python developers cannot use this syntax in code. There are functions with other interesting semantics: <ul class="simple"> <li><code class="docutils literal notranslate">range()</code>, an overloaded function, accepts an optional parameter to the left of its required parameter. <a class="footnote-reference brackets" href="#range" id="id1">[4]</a></li> <li><code class="docutils literal notranslate">dict()</code>, whose mapping/iterator parameter is optional and semantically must be positional-only. Any externally visible name for this parameter would occlude that name going into the <code class="docutils literal notranslate">**kwarg</code> keyword variadic parameter dict. <a class="footnote-reference brackets" href="#dict" id="id2">[3]</a></li> </ul> One can emulate these semantics in Python code by accepting <code class="docutils literal notranslate">(*args, **kwargs)</code> and parsing the arguments manually. However, this results in a disconnect between the function definition and what the function contractually accepts. The function definition does not match the logic of the argument handling. Additionally, the <code class="docutils literal notranslate">/</code> syntax is used beyond CPython for specifying similar semantics (i.e., <a class="footnote-reference brackets" href="#numpy-ufuncs" id="id3">[1]</a> <a class="footnote-reference brackets" href="#scipy-gammaln" id="id4">[2]</a>); thus, indicating that these scenarios are not exclusive to CPython and the standard library. </section> <section id="problems-without-positional-only-parameters"> <h3><a class="toc-backref" href="#problems-without-positional-only-parameters" role="doc-backlink">Problems Without Positional-Only Parameters</a></h3> Without positional-only parameters, there are challenges for library authors and users of APIs. The following subsections outline the problems encountered by each entity. <section id="challenges-for-library-authors"> <h4><a class="toc-backref" href="#challenges-for-library-authors" role="doc-backlink">Challenges for Library Authors</a></h4> With positional-or-keyword parameters, the mix of calling conventions is not always desirable. Authors may want to restrict usage of an API by disallowing calling the API with keyword arguments, which exposes the name of the parameter when part of the public API. This approach is especially useful for required function parameters that already have semantic meaning (e.g, <code class="docutils literal notranslate">namedtuple(typenames, field_names, …)</code> or when the parameter name has no true external meaning (e.g., <code class="docutils literal notranslate">arg1</code>, <code class="docutils literal notranslate">arg2</code>, …, etc for <code class="docutils literal notranslate">min()</code>). If a caller of an API starts using a keyword argument, the library author cannot rename the parameter because it would be a breaking change. Positional-only parameters can be emulated by extracting arguments from <code class="docutils literal notranslate">*args</code> one by one. However, this approach is error-prone and is not synonymous with the function definition, as previously mentioned. The usage of the function is ambiguous and forces users to look at <code class="docutils literal notranslate">help()</code>, the associated auto-generated documentation, or source code to understand what parameters the function contractually accepts. </section> <section id="challenges-for-users-of-an-api"> <h4><a class="toc-backref" href="#challenges-for-users-of-an-api" role="doc-backlink">Challenges for Users of an API</a></h4> Users may be surprised when first encountering positional-only notation. This is expected given that it has only recently been documented <a class="footnote-reference brackets" href="#document-positional-only" id="id5">[13]</a> and it is not possible to use in Python code. For these reasons, this notation is currently an outlier that appears only in CPython APIs developed in C. Documenting the notation and making it possible to use it in Python code would eliminate this disconnect. Furthermore, the current documentation for positional-only parameters is inconsistent: <ul class="simple"> <li>Some functions denote optional groups of positional-only parameters by enclosing them in nested square brackets. <a class="footnote-reference brackets" href="#border" id="id6">[5]</a></li> <li>Some functions denote optional groups of positional-only parameters by presenting multiple prototypes with varying numbers of parameters. <a class="footnote-reference brackets" href="#sendfile" id="id7">[6]</a></li> <li>Some functions use both of the above approaches. <a class="footnote-reference brackets" href="#range" id="id8">[4]</a> <a class="footnote-reference brackets" href="#addch" id="id9">[7]</a></li> </ul> Another point the current documentation does not distinguish is whether a function takes positional-only parameters. <code class="docutils literal notranslate">open()</code> accepts keyword arguments; however, <code class="docutils literal notranslate">ord()</code> does not — there is no way of telling just by reading the existing documentation. </section> </section> <section id="benefits-of-positional-only-parameters"> <h3><a class="toc-backref" href="#benefits-of-positional-only-parameters" role="doc-backlink">Benefits of Positional-Only Parameters</a></h3> Positional-only parameters give more control to library authors to better express the intended usage of an API and allows the API to evolve in a safe, backward-compatible way. Additionally, it makes the Python language more consistent with existing documentation and the behavior of various “builtin” and standard library functions. <section id="empowering-library-authors"> <h4><a class="toc-backref" href="#empowering-library-authors" role="doc-backlink">Empowering Library Authors</a></h4> Library authors would have the flexibility to change the name of positional-only parameters without breaking callers. This flexibility reduces the cognitive burden for choosing an appropriate public-facing name for required parameters or parameters that have no true external semantic meaning. Positional-only parameters are useful in several situations such as: <ul class="simple"> <li>when a function accepts any keyword argument but also can accept a positional one</li> <li>when a parameter has no external semantic meaning</li> <li>when an API’s parameters are required and unambiguous</li> </ul> A key scenario is when a function accepts any keyword argument but can also accepts a positional one. Prominent examples are <code class="docutils literal notranslate">Formatter.format</code> and <code class="docutils literal notranslate">dict.update</code>. For instance, <code class="docutils literal notranslate">dict.update</code> accepts a dictionary (positionally), an iterable of key/value pairs (positionally), or multiple keyword arguments. In this scenario, if the dictionary parameter were not positional-only, the user could not use the name that the function definition uses for the parameter or, conversely, the function could not distinguish easily if the argument received is the dictionary/iterable or a keyword argument for updating the key/value pair. Another scenario where positional-only parameters are useful is when the parameter name has no true external semantic meaning. For example, let’s say we want to create a function that converts from one type to another: <div class="highlight-default notranslate"><div class="highlight"><pre>def as_my_type(x): ... </pre></div> </div> The name of the parameter provides no intrinsic value and forces the API author to maintain its name forever since callers might pass <code class="docutils literal notranslate">x</code> as a keyword argument. Additionally, positional-only parameters are useful when an API’s parameters are required and is unambiguous with respect to function. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>def add_to_queue(item: QueueItem): ... </pre></div> </div> The name of the function makes clear the argument expected. A keyword argument provides minimal benefit and also limits the future evolution of the API. Say at a later time we want this function to be able to take multiple items, while preserving backwards compatibility: <div class="highlight-default notranslate"><div class="highlight"><pre>def add_to_queue(items: Union[QueueItem, List[QueueItem]]): ... </pre></div> </div> or to take them by using argument lists: <div class="highlight-default notranslate"><div class="highlight"><pre>def add_to_queue(*items: QueueItem): ... </pre></div> </div> the author would be forced to always keep the original parameter name to avoid potentially breaking callers. By being able to specify positional-only parameters, an author can change the name of the parameters freely or even change them to <code class="docutils literal notranslate">*args</code>, as seen in the previous example. There are multiple function definitions in the standard library which fall into this category. For example, the required parameter to <code class="docutils literal notranslate">collections.defaultdict</code> (called default_factory in its documentation) can only be passed positionally. One special case of this situation is the self parameter for class methods: it is undesirable that a caller can bind by keyword to the name <code class="docutils literal notranslate">self</code> when calling the method from the class: <div class="highlight-default notranslate"><div class="highlight"><pre>io.FileIO.write(self=f, b=b"data") </pre></div> </div> Indeed, function definitions from the standard library implemented in C usually take <code class="docutils literal notranslate">self</code> as a positional-only parameter: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> help(io.FileIO.write) Help on method_descriptor: write(self, b, /) Write buffer b to file, return number of bytes written. </pre></div> </div> </section> <section id="improving-language-consistency"> <h4><a class="toc-backref" href="#improving-language-consistency" role="doc-backlink">Improving Language Consistency</a></h4> The Python language would be more consistent with positional-only parameters. If the concept is a normal feature of Python rather than a feature exclusive to extension modules, it would reduce confusion for users encountering functions with positional-only parameters. Some major third-party packages are already using the <code class="docutils literal notranslate">/</code> notation in their function definitions <a class="footnote-reference brackets" href="#numpy-ufuncs" id="id10">[1]</a> <a class="footnote-reference brackets" href="#scipy-gammaln" id="id11">[2]</a>. Bridging the gap found between “builtin” functions which specify positional-only parameters and pure Python implementations that lack the positional syntax would improve consistency. The <code class="docutils literal notranslate">/</code> syntax is already exposed in the existing documentation such as when builtins and interfaces are generated by the argument clinic. Another essential aspect to consider is <a class="pep reference internal" href="../pep-0399/" title="PEP 399 – Pure Python/C Accelerator Module Compatibility Requirements">PEP 399</a>, which mandates that pure Python versions of modules in the standard library must have the same interface and semantics that the accelerator modules implemented in C. For example, if <code class="docutils literal notranslate">collections.defaultdict</code> were to have a pure Python implementation it would need to make use of positional-only parameters to match the interface of its C counterpart. </section> </section> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> We propose to introduce positional-only parameters as a new syntax to the Python language. The new syntax will enable library authors to further control how their API can be called. It will allow designating which parameters must be called as positional-only, while preventing them from being called as keyword arguments. Previously, (informational) <a class="pep reference internal" href="../pep-0457/" title="PEP 457 – Notation For Positional-Only Parameters">PEP 457</a> defined the syntax, but with a much more vague scope. This PEP takes the original proposal a step further by justifying the syntax and providing an implementation for the <code class="docutils literal notranslate">/</code> syntax in function definitions. <section id="performance"> <h3><a class="toc-backref" href="#performance" role="doc-backlink">Performance</a></h3> In addition to the aforementioned benefits, the parsing and handling of positional-only arguments is faster. This performance benefit can be demonstrated in this thread about converting keyword arguments to positional: <a class="footnote-reference brackets" href="#thread-keyword-to-positional" id="id12">[11]</a>. Due to this speedup, there has been a recent trend towards moving builtins away from keyword arguments: recently, backwards-incompatible changes were made to disallow keyword arguments to <code class="docutils literal notranslate">bool</code>, <code class="docutils literal notranslate">float</code>, <code class="docutils literal notranslate">list</code>, <code class="docutils literal notranslate">int</code>, <code class="docutils literal notranslate">tuple</code>. </section> <section id="maintainability"> <h3><a class="toc-backref" href="#maintainability" role="doc-backlink">Maintainability</a></h3> Providing a way to specify positional-only parameters in Python will make it easier to maintain pure Python implementations of C modules. Additionally, library authors defining functions will have the choice for choosing positional-only parameters if they determine that passing a keyword argument provides no additional clarity. This is a well discussed, recurring topic on the Python mailing lists: <ul class="simple"> <li>September 2018: <a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2018-September/053233.html">Anders Hovmöller: [Python-ideas] Positional-only parameters</a></li> <li>February 2017: <a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2017-February/044879.html">Victor Stinner: [Python-ideas] Positional-only parameters</a>, <a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2017-March/044956.html">discussion continued in March</a></li> <li>February 2017: <a class="footnote-reference brackets" href="#python-ideas-decorator-based" id="id13">[9]</a></li> <li>March 2012: <a class="footnote-reference brackets" href="#guido" id="id14">[8]</a></li> <li>May 2007: <a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2007-May/000704.html">George Sakkis: [Python-ideas] Positional only arguments</a></li> <li>May 2006: <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2006-May/064790.html">Benji York: [Python-Dev] Positional-only Arguments</a></li> </ul> </section> <section id="logical-ordering"> <h3><a class="toc-backref" href="#logical-ordering" role="doc-backlink">Logical ordering</a></h3> Positional-only parameters also have the (minor) benefit of enforcing some logical order when calling interfaces that make use of them. For example, the <code class="docutils literal notranslate">range</code> function takes all its parameters positionally and disallows forms like: <div class="highlight-default notranslate"><div class="highlight"><pre>range(stop=5, start=0, step=2) range(stop=5, step=2, start=0) range(step=2, start=0, stop=5) range(step=2, stop=5, start=0) </pre></div> </div> at the price of disallowing the use of keyword arguments for the (unique) intended order: <div class="highlight-default notranslate"><div class="highlight"><pre>range(start=0, stop=5, step=2) </pre></div> </div> </section> <section id="compatibility-for-pure-python-and-c-modules"> <h3><a class="toc-backref" href="#compatibility-for-pure-python-and-c-modules" role="doc-backlink">Compatibility for Pure Python and C Modules</a></h3> Another critical motivation for positional-only parameters is <a class="pep reference internal" href="../pep-0399/" title="PEP 399 – Pure Python/C Accelerator Module Compatibility Requirements">PEP 399</a>: Pure Python/C Accelerator Module Compatibility Requirements. This PEP states that: <blockquote> <div>This PEP requires that in these instances that the C code must pass the test suite used for the pure Python code to act as much as a drop-in replacement as reasonably possible</div></blockquote> If the C code is implemented using the existing capabilities to implement positional-only parameters using the argument clinic, and related machinery, it is not possible for the pure Python counterpart to match the provided interface and requirements. This creates a disparity between the interfaces of some functions and classes in the CPython standard library and other Python implementations. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>$ python3 # CPython 3.7.2 >>> import binascii; binascii.crc32(data=b'data') TypeError: crc32() takes no keyword arguments $ pypy3 # PyPy 6.0.0 >>>> import binascii; binascii.crc32(data=b'data') 2918445923 </pre></div> </div> Other Python implementations can reproduce the CPython APIs manually, but this goes against the spirit of <a class="pep reference internal" href="../pep-0399/" title="PEP 399 – Pure Python/C Accelerator Module Compatibility Requirements">PEP 399</a> to avoid duplication of effort by mandating that all modules added to Python’s standard library must have a pure Python implementation with the same interface and semantics. </section> <section id="consistency-in-subclasses"> <h3><a class="toc-backref" href="#consistency-in-subclasses" role="doc-backlink">Consistency in Subclasses</a></h3> Another scenario where positional-only parameters provide benefit occurs when a subclass overrides a method of the base class and changes the name of parameters that are intended to be positional: <div class="highlight-default notranslate"><div class="highlight"><pre>class Base: def meth(self, arg: int) -> str: ... class Sub(Base): def meth(self, other_arg: int) -> str: ... def func(x: Base): x.meth(arg=12) func(Sub()) # Runtime error </pre></div> </div> This situation could be considered a Liskov violation — the subclass cannot be used in a context when an instance of the base class is expected. Renaming arguments when overloading methods can happen when the subclass has reasons to use a different choice for the parameter name that is more appropriate for the specific domain of the subclass (e.g., when subclassing <code class="docutils literal notranslate">Mapping</code> to implement a DNS lookup cache, the derived class may not want to use the generic argument names ‘key’ and ‘value’ but rather ‘host’ and ‘address’). Having this function definition with positional-only parameters can avoid this problem because users will not be able to call the interface using keyword arguments. In general, designing for subclassing usually involves anticipating code that hasn’t been written yet and over which the author has no control. Having measures that can facilitate the evolution of interfaces in a backwards-compatible would be useful for library authors. </section> <section id="optimizations"> <h3><a class="toc-backref" href="#optimizations" role="doc-backlink">Optimizations</a></h3> A final argument in favor of positional-only parameters is that they allow some new optimizations like the ones already present in the argument clinic due to the fact that parameters are expected to be passed in strict order. For example, CPython’s internal <code class="docutils literal notranslate">METH_FASTCALL</code> calling convention has been recently specialized for functions with positional-only parameters to eliminate the cost for handling empty keywords. Similar performance improvements can be applied when creating the evaluation frame of Python functions thanks to positional-only parameters. </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <section id="syntax-and-semantics"> <h3><a class="toc-backref" href="#syntax-and-semantics" role="doc-backlink">Syntax and Semantics</a></h3> From the “ten-thousand foot view”, eliding <code class="docutils literal notranslate">*args</code> and <code class="docutils literal notranslate">**kwargs</code> for illustration, the grammar for a function definition would look like: <div class="highlight-default notranslate"><div class="highlight"><pre>def name(positional_or_keyword_parameters, *, keyword_only_parameters): </pre></div> </div> Building on that example, the new syntax for function definitions would look like: <div class="highlight-default notranslate"><div class="highlight"><pre>def name(positional_only_parameters, /, positional_or_keyword_parameters, *, keyword_only_parameters): </pre></div> </div> The following would apply: <ul class="simple"> <li>All parameters left of the <code class="docutils literal notranslate">/</code> are treated as positional-only.</li> <li>If <code class="docutils literal notranslate">/</code> is not specified in the function definition, that function does not accept any positional-only arguments.</li> <li>The logic around optional values for positional-only parameters remains the same as for positional-or-keyword parameters.</li> <li>Once a positional-only parameter is specified with a default, the following positional-only and positional-or-keyword parameters need to have defaults as well.</li> <li>Positional-only parameters which do not have default values are required positional-only parameters.</li> </ul> Therefore, the following would be valid function definitions: <div class="highlight-default notranslate"><div class="highlight"><pre>def name(p1, p2, /, p_or_kw, *, kw): def name(p1, p2=None, /, p_or_kw=None, *, kw): def name(p1, p2=None, /, *, kw): def name(p1, p2=None, /): def name(p1, p2, /, p_or_kw): def name(p1, p2, /): </pre></div> </div> Just like today, the following would be valid function definitions: <div class="highlight-default notranslate"><div class="highlight"><pre>def name(p_or_kw, *, kw): def name(*, kw): </pre></div> </div> While the following would be invalid: <div class="highlight-default notranslate"><div class="highlight"><pre>def name(p1, p2=None, /, p_or_kw, *, kw): def name(p1=None, p2, /, p_or_kw=None, *, kw): def name(p1=None, p2, /): </pre></div> </div> </section> <section id="full-grammar-specification"> <h3><a class="toc-backref" href="#full-grammar-specification" role="doc-backlink">Full Grammar Specification</a></h3> A simplified view of the proposed grammar specification is: <div class="highlight-default notranslate"><div class="highlight"><pre>typedargslist: tfpdef ['=' test] (',' tfpdef ['=' test])* ',' '/' [',' # and so on varargslist: vfpdef ['=' test] (',' vfpdef ['=' test])* ',' '/' [',' # and so on </pre></div> </div> Based on the reference implementation in this PEP, the new rule for <code class="docutils literal notranslate">typedarglist</code> would be: <div class="highlight-default notranslate"><div class="highlight"><pre>typedargslist: (tfpdef ['=' test] (',' tfpdef ['=' test])* ',' '/' [',' [tfpdef ['=' test] (',' tfpdef ['=' test])* [',' [ '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]] | '**' tfpdef [',']]] | '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]] | '**' tfpdef [',']] ] )| ( tfpdef ['=' test] (',' tfpdef ['=' test])* [',' [ '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]] | '**' tfpdef [',']]] | '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]] | '**' tfpdef [',']) </pre></div> </div> and for <code class="docutils literal notranslate">varargslist</code> would be: <div class="highlight-default notranslate"><div class="highlight"><pre>varargslist: vfpdef ['=' test ](',' vfpdef ['=' test])* ',' '/' [',' [ (vfpdef ['=' test] (',' vfpdef ['=' test])* [',' [ '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]] | '**' vfpdef [',']]] | '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]] | '**' vfpdef [',']) ]] | (vfpdef ['=' test] (',' vfpdef ['=' test])* [',' [ '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]] | '**' vfpdef [',']]] | '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]] | '**' vfpdef [','] ) </pre></div> </div> </section> <section id="semantic-corner-case"> <h3><a class="toc-backref" href="#semantic-corner-case" role="doc-backlink">Semantic Corner Case</a></h3> The following is an interesting corollary of the specification. Consider this function definition: <div class="highlight-default notranslate"><div class="highlight"><pre>def foo(name, **kwds): return 'name' in kwds </pre></div> </div> There is no possible call that will make it return <code class="docutils literal notranslate">True</code>. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> foo(1, **{'name': 2}) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: foo() got multiple values for argument 'name' >>> </pre></div> </div> But using <code class="docutils literal notranslate">/</code> we can support this: <div class="highlight-default notranslate"><div class="highlight"><pre>def foo(name, /, **kwds): return 'name' in kwds </pre></div> </div> Now the above call will return <code class="docutils literal notranslate">True</code>. In other words, the names of positional-only parameters can be used in <code class="docutils literal notranslate">**kwds</code> without ambiguity. (As another example, this benefits the signatures of <code class="docutils literal notranslate">dict()</code> and <code class="docutils literal notranslate">dict.update()</code>.) </section> <section id="origin-of-as-a-separator"> <h3><a class="toc-backref" href="#origin-of-as-a-separator" role="doc-backlink">Origin of “/” as a Separator</a></h3> Using <code class="docutils literal notranslate">/</code> as a separator was initially proposed by Guido van Rossum in 2012 <a class="footnote-reference brackets" href="#guido" id="id15">[8]</a> : <blockquote> <div>Alternative proposal: how about using ‘/’ ? It’s kind of the opposite of ‘*’ which means “keyword argument”, and ‘/’ is not a new character.</div></blockquote> </section> </section> <section id="how-to-teach-this"> <h2><a class="toc-backref" href="#how-to-teach-this" role="doc-backlink">How To Teach This</a></h2> Introducing a dedicated syntax to mark positional-only parameters is closely analogous to existing keyword-only arguments. Teaching these concepts together may simplify how to teach the possible function definitions a user may encounter or design. This PEP recommends adding a new subsection to the Python documentation, in the section <a class="reference external" href="https://docs.python.org/3.7/tutorial/controlflow.html#more-on-defining-functions">“More on Defining Functions”</a>, where the rest of the argument types are discussed. The following paragraphs serve as a draft for these additions. They will introduce the notation for both positional-only and keyword-only parameters. It is not intended to be exhaustive, nor should it be considered the final version to be incorporated into the documentation. <hr class="docutils" /> By default, arguments may be passed to a Python function either by position or explicitly by keyword. For readability and performance, it makes sense to restrict the way arguments can be passed so that a developer need only look at the function definition to determine if items are passed by position, by position or keyword, or by keyword. A function definition may look like: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2): ----------- ---------- ---------- | | | | Positional or keyword | | - Keyword only -- Positional only </pre></div> </div> where <code class="docutils literal notranslate">/</code> and <code class="docutils literal notranslate">*</code> are optional. If used, these symbols indicate the kind of parameter by how the arguments may be passed to the function: positional-only, positional-or-keyword, and keyword-only. Keyword parameters are also referred to as named parameters. <section id="positional-or-keyword-arguments"> <h3><a class="toc-backref" href="#positional-or-keyword-arguments" role="doc-backlink">Positional-or-Keyword Arguments</a></h3> If <code class="docutils literal notranslate">/</code> and <code class="docutils literal notranslate">*</code> are not present in the function definition, arguments may be passed to a function by position or by keyword. </section> <section id="positional-only-parameters"> <h3><a class="toc-backref" href="#positional-only-parameters" role="doc-backlink">Positional-Only Parameters</a></h3> 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 be placed before a <code class="docutils literal notranslate">/</code> (forward-slash). The <code class="docutils literal notranslate">/</code> is used to logically separate the positional-only parameters from the rest of the parameters. If there is no <code class="docutils literal notranslate">/</code> in the function definition, there are no positional-only parameters. Parameters following the <code class="docutils literal notranslate">/</code> may be positional-or-keyword or keyword-only. </section> <section id="keyword-only-arguments"> <h3><a class="toc-backref" href="#keyword-only-arguments" role="doc-backlink">Keyword-Only Arguments</a></h3> To mark parameters as keyword-only, indicating the parameters must be passed by keyword argument, place an <code class="docutils literal notranslate">*</code> in the arguments list just before the first keyword-only parameter. </section> <section id="function-examples"> <h3><a class="toc-backref" href="#function-examples" role="doc-backlink">Function Examples</a></h3> Consider the following example function definitions paying close attention to the markers <code class="docutils literal notranslate">/</code> and <code class="docutils literal notranslate">*</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> def standard_arg(arg): ... print(arg) ... >>> def pos_only_arg(arg, /): ... print(arg) ... >>> def kwd_only_arg(*, arg): ... print(arg) ... >>> def combined_example(pos_only, /, standard, *, kwd_only): ... print(pos_only, standard, kwd_only) </pre></div> </div> The first function definition <code class="docutils literal notranslate">standard_arg</code>, the most familiar form, places no restrictions on the calling convention and arguments may be passed by position or keyword: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> standard_arg(2) 2 >>> standard_arg(arg=2) 2 </pre></div> </div> The second function <code class="docutils literal notranslate">pos_only_arg</code> is restricted to only use positional parameters as there is a <code class="docutils literal notranslate">/</code> in the function definition: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> pos_only_arg(1) 1 >>> pos_only_arg(arg=1) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: pos_only_arg() got an unexpected keyword argument 'arg' </pre></div> </div> The third function <code class="docutils literal notranslate">kwd_only_args</code> only allows keyword arguments as indicated by a <code class="docutils literal notranslate">*</code> in the function definition: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> kwd_only_arg(3) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: kwd_only_arg() takes 0 positional arguments but 1 was given >>> kwd_only_arg(arg=3) 3 </pre></div> </div> And the last uses all three calling conventions in the same function definition: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> combined_example(1, 2, 3) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: combined_example() takes 2 positional arguments but 3 were given >>> combined_example(1, 2, kwd_only=3) 1 2 3 >>> combined_example(1, standard=2, kwd_only=3) 1 2 3 >>> combined_example(pos_only=1, standard=2, kwd_only=3) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: combined_example() got an unexpected keyword argument 'pos_only' </pre></div> </div> </section> <section id="recap"> <h3><a class="toc-backref" href="#recap" role="doc-backlink">Recap</a></h3> The use case will determine which parameters to use in the function definition: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2): </pre></div> </div> As guidance: <ul class="simple"> <li>Use positional-only if names do not matter or have no meaning, and there are only a few arguments which will always be passed in the same order.</li> <li>Use keyword-only when names have meaning and the function definition is more understandable by being explicit with names.</li> </ul> </section> </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2> An initial implementation that passes the CPython test suite is available for evaluation <a class="footnote-reference brackets" href="#posonly-impl" id="id16">[10]</a>. The benefits of this implementations are speed of handling positional-only parameters, consistency with the implementation of keyword-only parameters (PEP 3102), and a simpler implementation of all the tools and modules that would be impacted by this change. </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="do-nothing"> <h3><a class="toc-backref" href="#do-nothing" role="doc-backlink">Do Nothing</a></h3> Always an option — the status quo. While this was considered, the aforementioned benefits are worth the addition to the language. </section> <section id="decorators"> <h3><a class="toc-backref" href="#decorators" role="doc-backlink">Decorators</a></h3> It has been suggested on python-ideas <a class="footnote-reference brackets" href="#python-ideas-decorator-based" id="id17">[9]</a> to provide a decorator written in Python for this feature. This approach has the benefit of not polluting function definition with additional syntax. However, we have decided to reject this idea because: <ul class="simple"> <li>It introduces an asymmetry with how parameter behavior is declared.</li> <li>It makes it difficult for static analyzers and type checkers to safely identify positional-only parameters. They would need to query the AST for the list of decorators and identify the correct one by name or with extra heuristics, while keyword-only parameters are exposed directly in the AST. In order for tools to correctly identify positional-only parameters, they would need to execute the module to access any metadata the decorator is setting.</li> <li>Any error with the declaration will be reported only at runtime.</li> <li>It may be more difficult to identify positional-only parameters in long function definitions, as it forces the user to count them to know which is the last one that is impacted by the decorator.</li> <li>The <code class="docutils literal notranslate">/</code> syntax has already been introduced for C functions. This inconsistency will make it more challenging to implement any tools and modules that deal with this syntax — including but not limited to, the argument clinic, the inspect module and the <code class="docutils literal notranslate">ast</code> module.</li> <li>The decorator implementation would likely impose a runtime performance cost, particularly when compared to adding support directly to the interpreter.</li> </ul> </section> <section id="per-argument-marker"> <h3><a class="toc-backref" href="#per-argument-marker" role="doc-backlink">Per-Argument Marker</a></h3> A per-argument marker is another language-intrinsic option. The approach adds a token to each of the parameters to indicate they are positional-only and requires those parameters to be placed together. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>def (.arg1, .arg2, arg3): </pre></div> </div> Note the dot (i.e., <code class="docutils literal notranslate">.</code>) on <code class="docutils literal notranslate">.arg1</code> and <code class="docutils literal notranslate">.arg2</code>. While this approach may be easier to read, it has been rejected because <code class="docutils literal notranslate">/</code> as an explicit marker is congruent with <code class="docutils literal notranslate">*</code> for keyword-only arguments and is less error-prone. It should be noted that some libraries already use leading underscore <a class="footnote-reference brackets" href="#leading-underscore" id="id18">[12]</a> to conventionally indicate parameters as positional-only. </section> <section id="using-as-a-per-argument-marker"> <h3><a class="toc-backref" href="#using-as-a-per-argument-marker" role="doc-backlink">Using “__” as a Per-Argument Marker</a></h3> Some libraries and applications (like <code class="docutils literal notranslate">mypy</code> or <code class="docutils literal notranslate">jinja</code>) use names prepended with a double underscore (i.e., <code class="docutils literal notranslate">__</code>) as a convention to indicate positional-only parameters. We have rejected the idea of introducing <code class="docutils literal notranslate">__</code> as a new syntax because: <ul class="simple"> <li>It is a backwards-incompatible change.</li> <li>It is not symmetric with how the keyword-only parameters are currently declared.</li> <li>Querying the AST for positional-only parameters would require checking the normal arguments and inspecting their names, whereas keyword-only parameters have a property associated with them (<code class="docutils literal notranslate">FunctionDef.args.kwonlyargs</code>).</li> <li>Every parameter would need to be inspected to know when positional-only arguments end.</li> <li>The marker is more verbose, forcing marking every positional-only parameter.</li> <li>It clashes with other uses of the double underscore prefix like invoking name mangling in classes.</li> </ul> </section> <section id="group-positional-only-parameters-with-parentheses"> <h3><a class="toc-backref" href="#group-positional-only-parameters-with-parentheses" role="doc-backlink">Group Positional-Only Parameters With Parentheses</a></h3> Tuple parameter unpacking is a Python 2 feature which allows the use of a tuple as a parameter in a function definition. It allows a sequence argument to be unpacked automatically. An example is: <div class="highlight-default notranslate"><div class="highlight"><pre>def fxn(a, (b, c), d): pass </pre></div> </div> Tuple argument unpacking was removed in Python 3 (<a class="pep reference internal" href="../pep-3113/" title="PEP 3113 – Removal of Tuple Parameter Unpacking">PEP 3113</a>). There has been a proposition to reuse this syntax to implement positional-only parameters. We have rejected this syntax for indicating positional only parameters for several reasons: <ul class="simple"> <li>The syntax is asymmetric with respect to how keyword-only parameters are declared.</li> <li>Python 2 uses this syntax which could raise confusion regarding the behavior of this syntax. This would be surprising to users porting Python 2 codebases that were using this feature.</li> <li>This syntax is very similar to tuple literals. This can raise additional confusion because it can be confused with a tuple declaration.</li> </ul> </section> <section id="after-separator-proposal"> <h3><a class="toc-backref" href="#after-separator-proposal" role="doc-backlink">After Separator Proposal</a></h3> Marking positional-parameters after the <code class="docutils literal notranslate">/</code> was another idea considered. However, we were unable to find an approach which would modify the arguments after the marker. Otherwise, would force the parameters before the marker to be positional-only as well. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>def (x, y, /, z): </pre></div> </div> If we define that <code class="docutils literal notranslate">/</code> marks <code class="docutils literal notranslate">z</code> as positional-only, it would not be possible to specify <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code> as keyword arguments. Finding a way to work around this limitation would add confusion given that at the moment keyword arguments cannot be followed by positional arguments. Therefore, <code class="docutils literal notranslate">/</code> would make both the preceding and following parameters positional-only. </section> </section> <section id="thanks"> <h2><a class="toc-backref" href="#thanks" role="doc-backlink">Thanks</a></h2> Credit for some of the content of this PEP is contained in Larry Hastings’s <a class="pep reference internal" href="../pep-0457/" title="PEP 457 – Notation For Positional-Only Parameters">PEP 457</a>. Credit for the use of <code class="docutils literal notranslate">/</code> as the separator between positional-only and positional-or-keyword parameters go to Guido van Rossum, in a proposal from 2012. <a class="footnote-reference brackets" href="#guido" id="id19">[8]</a> Credit for discussion about the simplification of the grammar goes to Braulio Valdivieso. <aside class="footnote-list brackets"> <aside class="footnote brackets" id="numpy-ufuncs" role="doc-footnote"> <dt class="label" id="numpy-ufuncs">[1] (<a href='#id3'>1</a>, <a href='#id10'>2</a>) </dt> <dd><a class="reference external" href="https://docs.scipy.org/doc/numpy/reference/ufuncs.html#available-ufuncs">https://docs.scipy.org/doc/numpy/reference/ufuncs.html#available-ufuncs</a></aside> <aside class="footnote brackets" id="scipy-gammaln" role="doc-footnote"> <dt class="label" id="scipy-gammaln">[2] (<a href='#id4'>1</a>, <a href='#id11'>2</a>) </dt> <dd><a class="reference external" href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammaln.html">https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammaln.html</a></aside> <aside class="footnote brackets" id="dict" role="doc-footnote"> <dt class="label" id="dict">[<a href="#id2">3</a>]</dt> <dd><a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#dict">http://docs.python.org/3/library/stdtypes.html#dict</a></aside> <aside class="footnote brackets" id="range" role="doc-footnote"> <dt class="label" id="range">[4] (<a href='#id1'>1</a>, <a href='#id8'>2</a>) </dt> <dd><a class="reference external" href="http://docs.python.org/3/library/functions.html#func-range">http://docs.python.org/3/library/functions.html#func-range</a></aside> <aside class="footnote brackets" id="border" role="doc-footnote"> <dt class="label" id="border">[<a href="#id6">5</a>]</dt> <dd><a class="reference external" href="http://docs.python.org/3/library/curses.html#curses.window.border">http://docs.python.org/3/library/curses.html#curses.window.border</a></aside> <aside class="footnote brackets" id="sendfile" role="doc-footnote"> <dt class="label" id="sendfile">[<a href="#id7">6</a>]</dt> <dd><a class="reference external" href="http://docs.python.org/3/library/os.html#os.sendfile">http://docs.python.org/3/library/os.html#os.sendfile</a></aside> <aside class="footnote brackets" id="addch" role="doc-footnote"> <dt class="label" id="addch">[<a href="#id9">7</a>]</dt> <dd><a class="reference external" href="http://docs.python.org/3/library/curses.html#curses.window.addch">http://docs.python.org/3/library/curses.html#curses.window.addch</a></aside> <aside class="footnote brackets" id="guido" role="doc-footnote"> <dt class="label" id="guido">[8] (<a href='#id14'>1</a>, <a href='#id15'>2</a>, <a href='#id19'>3</a>) </dt> <dd>Guido van Rossum, posting to python-ideas, March 2012: <a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2012-March/014364.html">https://mail.python.org/pipermail/python-ideas/2012-March/014364.html</a> and <a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2012-March/014378.html">https://mail.python.org/pipermail/python-ideas/2012-March/014378.html</a> and <a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2012-March/014417.html">https://mail.python.org/pipermail/python-ideas/2012-March/014417.html</a></aside> <aside class="footnote brackets" id="python-ideas-decorator-based" role="doc-footnote"> <dt class="label" id="python-ideas-decorator-based">[9] (<a href='#id13'>1</a>, <a href='#id17'>2</a>) </dt> <dd><a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2017-February/044888.html">https://mail.python.org/pipermail/python-ideas/2017-February/044888.html</a></aside> <aside class="footnote brackets" id="posonly-impl" role="doc-footnote"> <dt class="label" id="posonly-impl">[<a href="#id16">10</a>]</dt> <dd><a class="reference external" href="https://github.com/pablogsal/cpython_positional_only">https://github.com/pablogsal/cpython_positional_only</a></aside> <aside class="footnote brackets" id="thread-keyword-to-positional" role="doc-footnote"> <dt class="label" id="thread-keyword-to-positional">[<a href="#id12">11</a>]</dt> <dd><a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2016-January/037874.html">https://mail.python.org/pipermail/python-ideas/2016-January/037874.html</a></aside> <aside class="footnote brackets" id="leading-underscore" role="doc-footnote"> <dt class="label" id="leading-underscore">[<a href="#id18">12</a>]</dt> <dd><a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2018-September/053319.html">https://mail.python.org/pipermail/python-ideas/2018-September/053319.html</a></aside> <aside class="footnote brackets" id="document-positional-only" role="doc-footnote"> <dt class="label" id="document-positional-only">[<a href="#id5">13</a>]</dt> <dd><a class="reference external" href="https://bugs.python.org/issue21314">https://bugs.python.org/issue21314</a></aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0570.rst">https://github.com/python/peps/blob/main/peps/pep-0570.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0570.rst">2023-09-09 17:39:29 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a><ul> <li><a class="reference internal" href="#history-of-positional-only-parameter-semantics-in-python">History of Positional-Only Parameter Semantics in Python</a></li> <li><a class="reference internal" href="#problems-without-positional-only-parameters">Problems Without Positional-Only Parameters</a><ul> <li><a class="reference internal" href="#challenges-for-library-authors">Challenges for Library Authors</a></li> <li><a class="reference internal" href="#challenges-for-users-of-an-api">Challenges for Users of an API</a></li> </ul> </li> <li><a class="reference internal" href="#benefits-of-positional-only-parameters">Benefits of Positional-Only Parameters</a><ul> <li><a class="reference internal" href="#empowering-library-authors">Empowering Library Authors</a></li> <li><a class="reference internal" href="#improving-language-consistency">Improving Language Consistency</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#performance">Performance</a></li> <li><a class="reference internal" href="#maintainability">Maintainability</a></li> <li><a class="reference internal" href="#logical-ordering">Logical ordering</a></li> <li><a class="reference internal" href="#compatibility-for-pure-python-and-c-modules">Compatibility for Pure Python and C Modules</a></li> <li><a class="reference internal" href="#consistency-in-subclasses">Consistency in Subclasses</a></li> <li><a class="reference internal" href="#optimizations">Optimizations</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#syntax-and-semantics">Syntax and Semantics</a></li> <li><a class="reference internal" href="#full-grammar-specification">Full Grammar Specification</a></li> <li><a class="reference internal" href="#semantic-corner-case">Semantic Corner Case</a></li> <li><a class="reference internal" href="#origin-of-as-a-separator">Origin of “/” as a Separator</a></li> </ul> </li> <li><a class="reference internal" href="#how-to-teach-this">How To Teach This</a><ul> <li><a class="reference internal" href="#positional-or-keyword-arguments">Positional-or-Keyword Arguments</a></li> <li><a class="reference internal" href="#positional-only-parameters">Positional-Only Parameters</a></li> <li><a class="reference internal" href="#keyword-only-arguments">Keyword-Only Arguments</a></li> <li><a class="reference internal" href="#function-examples">Function Examples</a></li> <li><a class="reference internal" href="#recap">Recap</a></li> </ul> </li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#do-nothing">Do Nothing</a></li> <li><a class="reference internal" href="#decorators">Decorators</a></li> <li><a class="reference internal" href="#per-argument-marker">Per-Argument Marker</a></li> <li><a class="reference internal" href="#using-as-a-per-argument-marker">Using “__” as a Per-Argument Marker</a></li> <li><a class="reference internal" href="#group-positional-only-parameters-with-parentheses">Group Positional-Only Parameters With Parentheses</a></li> <li><a class="reference internal" href="#after-separator-proposal">After Separator Proposal</a></li> </ul> </li> <li><a class="reference internal" href="#thanks">Thanks</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0570.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>