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 309 – Partial Function Application | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0309/"> <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 309 – Partial Function Application | peps.python.org'> <meta property="og:description" content="This proposal is for a function or callable class that allows a new callable to be constructed from a callable and a partial argument list (including positional and keyword arguments)."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0309/"> <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 proposal is for a function or callable class that allows a new callable to be constructed from a callable and a partial argument list (including positional and keyword arguments)."> <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 309</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 309 – Partial Function Application</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Peter Harris <scav at blueyonder.co.uk></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">08-Feb-2003</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">2.5</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">10-Feb-2003, 27-Feb-2003, 22-Feb-2004, 28-Apr-2006</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#note">Note</a></li> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#acceptance">Acceptance</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#example-implementation">Example Implementation</a></li> <li><a class="reference internal" href="#examples-of-use">Examples of Use</a></li> <li><a class="reference internal" href="#abandoned-syntax-proposal">Abandoned Syntax Proposal</a></li> <li><a class="reference internal" href="#feedback-from-comp-lang-python-and-python-dev">Feedback from comp.lang.python and python-dev</a></li> <li><a class="reference internal" href="#summary">Summary</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="note"> <h2><a class="toc-backref" href="#note" role="doc-backlink">Note</a></h2> Following the acceptance of this PEP, further discussion on python-dev and comp.lang.python revealed a desire for several tools that operated on function objects, but were not related to functional programming. Rather than create a new module for these tools, it was agreed <a class="footnote-reference brackets" href="#id4" id="id1">[1]</a> that the “functional” module be renamed to “functools” to reflect its newly-widened focus. References in this PEP to a “functional” module have been left in for historical reasons. </section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This proposal is for a function or callable class that allows a new callable to be constructed from a callable and a partial argument list (including positional and keyword arguments). I propose a standard library module called “functional”, to hold useful higher-order functions, including the implementation of partial(). An implementation has been submitted to SourceForge <a class="footnote-reference brackets" href="#id5" id="id2">[2]</a>. </section> <section id="acceptance"> <h2><a class="toc-backref" href="#acceptance" role="doc-backlink">Acceptance</a></h2> Patch #941881 was accepted and applied in 2005 for Py2.5. It is essentially as outlined here, a partial() type constructor binding leftmost positional arguments and any keywords. The partial object has three read-only attributes func, args, and keywords. Calls to the partial object can specify keywords that override those in the object itself. There is a separate and continuing discussion of whether to modify the partial implementation with a __get__ method to more closely emulate the behavior of an equivalent function. </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> In functional programming, function currying is a way of implementing multi-argument functions in terms of single-argument functions. A function with N arguments is really a function with 1 argument that returns another function taking (N-1) arguments. Function application in languages like Haskell and ML works such that a function call: <div class="highlight-default notranslate"><div class="highlight"><pre>f x y z </pre></div> </div> actually means: <div class="highlight-default notranslate"><div class="highlight"><pre>(((f x) y) z) </pre></div> </div> This would be only an obscure theoretical issue except that in actual programming it turns out to be very useful. Expressing a function in terms of partial application of arguments to another function can be both elegant and powerful, and in functional languages it is heavily used. In some functional languages, (e.g. Miranda) you can use an expression such as <code class="docutils literal notranslate">(+1)</code> to mean the equivalent of Python’s <code class="docutils literal notranslate">(lambda x: x + 1)</code>. In general, languages like that are strongly typed, so the compiler always knows the number of arguments expected and can do the right thing when presented with a functor and less arguments than expected. Python does not implement multi-argument functions by currying, so if you want a function with partially-applied arguments you would probably use a lambda as above, or define a named function for each instance. However, lambda syntax is not to everyone’s taste, so say the least. Furthermore, Python’s flexible parameter passing using both positional and keyword presents an opportunity to generalise the idea of partial application and do things that lambda cannot. </section> <section id="example-implementation"> <h2><a class="toc-backref" href="#example-implementation" role="doc-backlink">Example Implementation</a></h2> Here is one way to do a create a callable with partially-applied arguments in Python. The implementation below is based on improvements provided by Scott David Daniels: <div class="highlight-default notranslate"><div class="highlight"><pre>class partial(object): def __init__(*args, **kw): self = args[0] self.fn, self.args, self.kw = (args[1], args[2:], kw) def __call__(self, *args, **kw): if kw and self.kw: d = self.kw.copy() d.update(kw) else: d = kw or self.kw return self.fn(*(self.args + args), **d) </pre></div> </div> (A recipe similar to this has been in the Python Cookbook for some time <a class="footnote-reference brackets" href="#id6" id="id3">[3]</a>.) Note that when the object is called as though it were a function, positional arguments are appended to those provided to the constructor, and keyword arguments override and augment those provided to the constructor. Positional arguments, keyword arguments or both can be supplied at when creating the object and when calling it. </section> <section id="examples-of-use"> <h2><a class="toc-backref" href="#examples-of-use" role="doc-backlink">Examples of Use</a></h2> So <code class="docutils literal notranslate">partial(operator.add, 1)</code> is a bit like <code class="docutils literal notranslate">(lambda x: 1 + x)</code>. Not an example where you see the benefits, of course. Note too, that you could wrap a class in the same way, since classes themselves are callable factories for objects. So in some cases, rather than defining a subclass, you can specialise classes by partial application of the arguments to the constructor. For example, <code class="docutils literal notranslate">partial(Tkinter.Label, fg='blue')</code> makes Tkinter Labels that have a blue foreground by default. Here’s a simple example that uses partial application to construct callbacks for Tkinter widgets on the fly: <div class="highlight-default notranslate"><div class="highlight"><pre>from Tkinter import Tk, Canvas, Button import sys from functional import partial win = Tk() c = Canvas(win,width=200,height=50) c.pack() for colour in sys.argv[1:]: b = Button(win, text=colour, command=partial(c.config, bg=colour)) b.pack(side='left') win.mainloop() </pre></div> </div> </section> <section id="abandoned-syntax-proposal"> <h2><a class="toc-backref" href="#abandoned-syntax-proposal" role="doc-backlink">Abandoned Syntax Proposal</a></h2> I originally suggested the syntax <code class="docutils literal notranslate">fn@(*args, **kw)</code>, meaning the same as <code class="docutils literal notranslate">partial(fn, *args, **kw)</code>. The @ sign is used in some assembly languages to imply register indirection, and the use here is also a kind of indirection. <code class="docutils literal notranslate">f@(x)</code> is not <code class="docutils literal notranslate">f(x)</code>, but a thing that becomes <code class="docutils literal notranslate">f(x)</code> when you call it. It was not well-received, so I have withdrawn this part of the proposal. In any case, @ has been taken for the new decorator syntax. </section> <section id="feedback-from-comp-lang-python-and-python-dev"> <h2><a class="toc-backref" href="#feedback-from-comp-lang-python-and-python-dev" role="doc-backlink">Feedback from comp.lang.python and python-dev</a></h2> Among the opinions voiced were the following (which I summarise): <ul class="simple"> <li>Lambda is good enough.</li> <li>The @ syntax is ugly (unanimous).</li> <li>It’s really a curry rather than a closure. There is an almost identical implementation of a curry class on ActiveState’s Python Cookbook.</li> <li>A curry class would indeed be a useful addition to the standard library.</li> <li>It isn’t function currying, but partial application. Hence the name is now proposed to be partial().</li> <li>It maybe isn’t useful enough to be in the built-ins.</li> <li>The idea of a module called <code class="docutils literal notranslate">functional</code> was well received, and there are other things that belong there (for example function composition).</li> <li>For completeness, another object that appends partial arguments after those supplied in the function call (maybe called <code class="docutils literal notranslate">rightcurry</code>) has been suggested.</li> </ul> I agree that lambda is usually good enough, just not always. And I want the possibility of useful introspection and subclassing. I disagree that @ is particularly ugly, but it may be that I’m just weird. We have dictionary, list and tuple literals neatly differentiated by special punctuation – a way of directly expressing partially-applied function literals is not such a stretch. However, not one single person has said they like it, so as far as I’m concerned it’s a dead parrot. I concur with calling the class partial rather than curry or closure, so I have amended the proposal in this PEP accordingly. But not throughout: some incorrect references to ‘curry’ have been left in since that’s where the discussion was at the time. Partially applying arguments from the right, or inserting arguments at arbitrary positions creates its own problems, but pending discovery of a good implementation and non-confusing semantics, I don’t think it should be ruled out. Carl Banks posted an implementation as a real functional closure: <div class="highlight-default notranslate"><div class="highlight"><pre>def curry(fn, *cargs, **ckwargs): def call_fn(*fargs, **fkwargs): d = ckwargs.copy() d.update(fkwargs) return fn(*(cargs + fargs), **d) return call_fn </pre></div> </div> which he assures me is more efficient. I also coded the class in Pyrex, to estimate how the performance might be improved by coding it in C: <div class="highlight-default notranslate"><div class="highlight"><pre>cdef class curry: cdef object fn, args, kw def __init__(self, fn, *args, **kw): self.fn=fn self.args=args self.kw = kw def __call__(self, *args, **kw): if self.kw: # from Python Cookbook version d = self.kw.copy() d.update(kw) else: d=kw return self.fn(*(self.args + args), **d) </pre></div> </div> The performance gain in Pyrex is less than 100% over the nested function implementation, since to be fully general it has to operate by Python API calls. For the same reason, a C implementation will be unlikely to be much faster, so the case for a built-in coded in C is not very strong. </section> <section id="summary"> <h2><a class="toc-backref" href="#summary" role="doc-backlink">Summary</a></h2> I prefer that some means to partially-apply functions and other callables should be present in the standard library. A standard library module <code class="docutils literal notranslate">functional</code> should contain an implementation of <code class="docutils literal notranslate">partial</code>, and any other higher-order functions the community want. Other functions that might belong there fall outside the scope of this PEP though. Patches for the implementation, documentation and unit tests (SF patches <a class="reference external" href="https://bugs.python.org/issue931005">931005</a>, <a class="reference external" href="https://bugs.python.org/issue931007">931007</a>, and <a class="reference external" href="https://bugs.python.org/issue931010">931010</a> respectively) have been submitted but not yet checked in. A C implementation by Hye-Shik Chang has also been submitted, although it is not expected to be included until after the Python implementation has proven itself useful enough to be worth optimising. </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id4" role="doc-footnote"> <dt class="label" id="id4">[<a href="#id1">1</a>]</dt> <dd><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2006-March/062290.html">https://mail.python.org/pipermail/python-dev/2006-March/062290.html</a></aside> <aside class="footnote brackets" id="id5" role="doc-footnote"> <dt class="label" id="id5">[<a href="#id2">2</a>]</dt> <dd>Patches <a class="reference external" href="https://bugs.python.org/issue931005">931005</a>, <a class="reference external" href="https://bugs.python.org/issue931007">931007</a>, and <a class="reference external" href="https://bugs.python.org/issue931010">931010</a>.</aside> <aside class="footnote brackets" id="id6" role="doc-footnote"> <dt class="label" id="id6">[<a href="#id3">3</a>]</dt> <dd><a class="reference external" href="http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52549">http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52549</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-0309.rst">https://github.com/python/peps/blob/main/peps/pep-0309.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0309.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#note">Note</a></li> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#acceptance">Acceptance</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#example-implementation">Example Implementation</a></li> <li><a class="reference internal" href="#examples-of-use">Examples of Use</a></li> <li><a class="reference internal" href="#abandoned-syntax-proposal">Abandoned Syntax Proposal</a></li> <li><a class="reference internal" href="#feedback-from-comp-lang-python-and-python-dev">Feedback from comp.lang.python and python-dev</a></li> <li><a class="reference internal" href="#summary">Summary</a></li> <li><a class="reference internal" href="#references">References</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-0309.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>