Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
functools.html1147 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="functools — Higher-order functions and operations on callable objects" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/functools.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/functools.py The functools module is for higher-order functions: functions that act on or return other functions. In general, any callable object can be treated as a function for t..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_functools_d90ef356.png" />15<meta property="og:image:alt" content="Source code: Lib/functools.py The functools module is for higher-order functions: functions that act on or return other functions. In general, any callable object can be treated as a function for t..." />16<meta name="description" content="Source code: Lib/functools.py The functools module is for higher-order functions: functions that act on or return other functions. In general, any callable object can be treated as a function for t..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>functools — Higher-order functions and operations on callable objects &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="operator — Standard operators as functions" href="operator.html" />43    <link rel="prev" title="itertools — Functions creating iterators for efficient looping" href="itertools.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/functools.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> — Higher-order functions and operations on callable objects</a><ul>108<li><a class="reference internal" href="#partial-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code> Objects</a></li>109</ul>110</li>111</ul>112 113  </div>114  <div>115    <h4>Previous topic</h4>116    <p class="topless"><a href="itertools.html"117                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code> — Functions creating iterators for efficient looping</a></p>118  </div>119  <div>120    <h4>Next topic</h4>121    <p class="topless"><a href="operator.html"122                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">operator</span></code> — Standard operators as functions</a></p>123  </div>124  <script>125    document.addEventListener('DOMContentLoaded', () => {126        const title = document.querySelector('meta[property="og:title"]').content;127        const elements = document.querySelectorAll('.improvepage');128        const pageurl = window.location.href.split('?')[0];129        elements.forEach(element => {130            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));131            url.searchParams.set('pagetitle', title);132            url.searchParams.set('pageurl', pageurl);133            url.searchParams.set('pagesource', "library/functools.rst");134            element.href = url.toString();135        });136    });137  </script>138  <div role="note" aria-label="source link">139    <h3>This page</h3>140    <ul class="this-page-menu">141      <li><a href="../bugs.html">Report a bug</a></li>142      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>143      <li>144        <a href="https://github.com/python/cpython/blob/main/Doc/library/functools.rst?plain=1"145            rel="nofollow">Show source146        </a>147      </li>148      149    </ul>150  </div>151        </nav>152    </div>153</div>154 155  156    <div class="related" role="navigation" aria-label="Related">157      <h3>Navigation</h3>158      <ul>159        <li class="right" style="margin-right: 10px">160          <a href="../genindex.html" title="General Index"161             accesskey="I">index</a></li>162        <li class="right" >163          <a href="../py-modindex.html" title="Python Module Index"164             >modules</a> |</li>165        <li class="right" >166          <a href="operator.html" title="operator — Standard operators as functions"167             accesskey="N">next</a> |</li>168        <li class="right" >169          <a href="itertools.html" title="itertools — Functions creating iterators for efficient looping"170             accesskey="P">previous</a> |</li>171 172          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>173          <li><a href="https://www.python.org/">Python</a> &#187;</li>174          <li class="switchers">175            <div class="language_switcher_placeholder"></div>176            <div class="version_switcher_placeholder"></div>177          </li>178          <li>179              180          </li>181    <li id="cpython-language-and-version">182      <a href="../index.html">3.15.0a6 Documentation</a> &#187;183    </li>184 185          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>186          <li class="nav-item nav-item-2"><a href="functional.html" accesskey="U">Functional Programming Modules</a> &#187;</li>187        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> — Higher-order functions and operations on callable objects</a></li>188                <li class="right">189                    190 191    <div class="inline-search" role="search">192        <form class="inline-search" action="../search.html" method="get">193          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">194          <input type="submit" value="Go">195        </form>196    </div>197                     |198                </li>199            <li class="right">200<label class="theme-selector-label">201    Theme202    <select class="theme-selector" oninput="activateTheme(this.value)">203        <option value="auto" selected>Auto</option>204        <option value="light">Light</option>205        <option value="dark">Dark</option>206    </select>207</label> |</li>208            209      </ul>210    </div>    211 212    <div class="document">213      <div class="documentwrapper">214        <div class="bodywrapper">215          <div class="body" role="main">216            217  <section id="module-functools">218<span id="functools-higher-order-functions-and-operations-on-callable-objects"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> — Higher-order functions and operations on callable objects<a class="headerlink" href="#module-functools" title="Link to this heading">¶</a></h1>219<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/functools.py">Lib/functools.py</a></p>220<hr class="docutils" />221<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> module is for higher-order functions: functions that act on222or return other functions. In general, any callable object can be treated as a223function for the purposes of this module.</p>224<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> module defines the following functions:</p>225<dl class="py function">226<dt class="sig sig-object py" id="functools.cache">227<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">cache</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">user_function</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.cache" title="Link to this definition">¶</a></dt>228<dd><p>Simple lightweight unbounded function cache.  Sometimes called229<a class="reference external" href="https://en.wikipedia.org/wiki/Memoization">“memoize”</a>.</p>230<p>Returns the same as <code class="docutils literal notranslate"><span class="pre">lru_cache(maxsize=None)</span></code>, creating a thin231wrapper around a dictionary lookup for the function arguments.  Because it232never needs to evict old values, this is smaller and faster than233<a class="reference internal" href="#functools.lru_cache" title="functools.lru_cache"><code class="xref py py-func docutils literal notranslate"><span class="pre">lru_cache()</span></code></a> with a size limit.</p>234<p>For example:</p>235<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@cache</span>236<span class="k">def</span><span class="w"> </span><span class="nf">factorial</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>237    <span class="k">return</span> <span class="n">n</span> <span class="o">*</span> <span class="n">factorial</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="k">if</span> <span class="n">n</span> <span class="k">else</span> <span class="mi">1</span>238 239<span class="o">&gt;&gt;&gt;</span> <span class="n">factorial</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>   <span class="c1"># no previously cached result, makes 11 recursive calls</span>240<span class="mi">3628800</span>241<span class="o">&gt;&gt;&gt;</span> <span class="n">factorial</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>    <span class="c1"># no new calls, just returns the cached result</span>242<span class="mi">120</span>243<span class="o">&gt;&gt;&gt;</span> <span class="n">factorial</span><span class="p">(</span><span class="mi">12</span><span class="p">)</span>   <span class="c1"># two new recursive calls, factorial(10) is cached</span>244<span class="mi">479001600</span>245</pre></div>246</div>247<p>The cache is threadsafe so that the wrapped function can be used in248multiple threads.  This means that the underlying data structure will249remain coherent during concurrent updates.</p>250<p>It is possible for the wrapped function to be called more than once if251another thread makes an additional call before the initial call has been252completed and cached.</p>253<p>Call-once behavior is not guaranteed because locks are not held during the254function call. Potentially another call with the same arguments could255occur while the first call is still running.</p>256<div class="versionadded">257<p><span class="versionmodified added">Added in version 3.9.</span></p>258</div>259</dd></dl>260 261<dl class="py function">262<dt class="sig sig-object py" id="functools.cached_property">263<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">cached_property</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.cached_property" title="Link to this definition">¶</a></dt>264<dd><p>Transform a method of a class into a property whose value is computed once265and then cached as a normal attribute for the life of the instance. Similar266to <a class="reference internal" href="functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a>, with the addition of caching. Useful for expensive267computed properties of instances that are otherwise effectively immutable.</p>268<p>Example:</p>269<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">DataSet</span><span class="p">:</span>270 271    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">sequence_of_numbers</span><span class="p">):</span>272        <span class="bp">self</span><span class="o">.</span><span class="n">_data</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">sequence_of_numbers</span><span class="p">)</span>273 274    <span class="nd">@cached_property</span>275    <span class="k">def</span><span class="w"> </span><span class="nf">stdev</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>276        <span class="k">return</span> <span class="n">statistics</span><span class="o">.</span><span class="n">stdev</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_data</span><span class="p">)</span>277</pre></div>278</div>279<p>The mechanics of <code class="xref py py-func docutils literal notranslate"><span class="pre">cached_property()</span></code> are somewhat different from280<a class="reference internal" href="functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a>.  A regular property blocks attribute writes unless a281setter is defined. In contrast, a <em>cached_property</em> allows writes.</p>282<p>The <em>cached_property</em> decorator only runs on lookups and only when an283attribute of the same name doesn’t exist.  When it does run, the284<em>cached_property</em> writes to the attribute with the same name. Subsequent285attribute reads and writes take precedence over the <em>cached_property</em>286method and it works like a normal attribute.</p>287<p>The cached value can be cleared by deleting the attribute.  This288allows the <em>cached_property</em> method to run again.</p>289<p>The <em>cached_property</em> does not prevent a possible race condition in290multi-threaded usage. The getter function could run more than once on the291same instance, with the latest run setting the cached value. If the cached292property is idempotent or otherwise not harmful to run more than once on an293instance, this is fine. If synchronization is needed, implement the necessary294locking inside the decorated getter function or around the cached property295access.</p>296<p>Note, this decorator interferes with the operation of <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0412/"><strong>PEP 412</strong></a>297key-sharing dictionaries.  This means that instance dictionaries298can take more space than usual.</p>299<p>Also, this decorator requires that the <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> attribute on each instance300be a mutable mapping. This means it will not work with some types, such as301metaclasses (since the <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> attributes on type instances are302read-only proxies for the class namespace), and those that specify303<code class="docutils literal notranslate"><span class="pre">__slots__</span></code> without including <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> as one of the defined slots304(as such classes don’t provide a <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> attribute at all).</p>305<p>If a mutable mapping is not available or if space-efficient key sharing is306desired, an effect similar to <code class="xref py py-func docutils literal notranslate"><span class="pre">cached_property()</span></code> can also be achieved by307stacking <a class="reference internal" href="functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a> on top of <a class="reference internal" href="#functools.lru_cache" title="functools.lru_cache"><code class="xref py py-func docutils literal notranslate"><span class="pre">lru_cache()</span></code></a>. See308<a class="reference internal" href="../faq/programming.html#faq-cache-method-calls"><span class="std std-ref">How do I cache method calls?</span></a> for more details on how this differs from <code class="xref py py-func docutils literal notranslate"><span class="pre">cached_property()</span></code>.</p>309<div class="versionadded">310<p><span class="versionmodified added">Added in version 3.8.</span></p>311</div>312<div class="versionchanged">313<p><span class="versionmodified changed">Changed in version 3.12: </span>Prior to Python 3.12, <code class="docutils literal notranslate"><span class="pre">cached_property</span></code> included an undocumented lock to314ensure that in multi-threaded usage the getter function was guaranteed to315run only once per instance. However, the lock was per-property, not316per-instance, which could result in unacceptably high lock contention. In317Python 3.12+ this locking is removed.</p>318</div>319</dd></dl>320 321<dl class="py function">322<dt class="sig sig-object py" id="functools.cmp_to_key">323<span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">cmp_to_key</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.cmp_to_key" title="Link to this definition">¶</a></dt>324<dd><p>Transform an old-style comparison function to a <a class="reference internal" href="../glossary.html#term-key-function"><span class="xref std std-term">key function</span></a>.  Used325with tools that accept key functions (such as <a class="reference internal" href="functions.html#sorted" title="sorted"><code class="xref py py-func docutils literal notranslate"><span class="pre">sorted()</span></code></a>, <a class="reference internal" href="functions.html#min" title="min"><code class="xref py py-func docutils literal notranslate"><span class="pre">min()</span></code></a>,326<a class="reference internal" href="functions.html#max" title="max"><code class="xref py py-func docutils literal notranslate"><span class="pre">max()</span></code></a>, <a class="reference internal" href="heapq.html#heapq.nlargest" title="heapq.nlargest"><code class="xref py py-func docutils literal notranslate"><span class="pre">heapq.nlargest()</span></code></a>, <a class="reference internal" href="heapq.html#heapq.nsmallest" title="heapq.nsmallest"><code class="xref py py-func docutils literal notranslate"><span class="pre">heapq.nsmallest()</span></code></a>,327<a class="reference internal" href="itertools.html#itertools.groupby" title="itertools.groupby"><code class="xref py py-func docutils literal notranslate"><span class="pre">itertools.groupby()</span></code></a>).  This function is primarily used as a transition328tool for programs being converted from Python 2 which supported the use of329comparison functions.</p>330<p>A comparison function is any callable that accepts two arguments, compares them,331and returns a negative number for less-than, zero for equality, or a positive332number for greater-than.  A key function is a callable that accepts one333argument and returns another value to be used as the sort key.</p>334<p>Example:</p>335<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">sorted</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">cmp_to_key</span><span class="p">(</span><span class="n">locale</span><span class="o">.</span><span class="n">strcoll</span><span class="p">))</span>  <span class="c1"># locale-aware sort order</span>336</pre></div>337</div>338<p>For sorting examples and a brief sorting tutorial, see <a class="reference internal" href="../howto/sorting.html#sortinghowto"><span class="std std-ref">Sorting Techniques</span></a>.</p>339<div class="versionadded">340<p><span class="versionmodified added">Added in version 3.2.</span></p>341</div>342</dd></dl>343 344<dl class="py function">345<dt class="sig sig-object py" id="functools.lru_cache">346<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">lru_cache</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">user_function</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.lru_cache" title="Link to this definition">¶</a></dt>347<dt class="sig sig-object py">348<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">lru_cache</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">maxsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">128</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">typed</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span></dt>349<dd><p>Decorator to wrap a function with a memoizing callable that saves up to the350<em>maxsize</em> most recent calls.  It can save time when an expensive or I/O bound351function is periodically called with the same arguments.</p>352<p>The cache is threadsafe so that the wrapped function can be used in353multiple threads.  This means that the underlying data structure will354remain coherent during concurrent updates.</p>355<p>It is possible for the wrapped function to be called more than once if356another thread makes an additional call before the initial call has been357completed and cached.</p>358<p>Since a dictionary is used to cache results, the positional and keyword359arguments to the function must be <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a>.</p>360<p>Distinct argument patterns may be considered to be distinct calls with361separate cache entries.  For example, <code class="docutils literal notranslate"><span class="pre">f(a=1,</span> <span class="pre">b=2)</span></code> and <code class="docutils literal notranslate"><span class="pre">f(b=2,</span> <span class="pre">a=1)</span></code>362differ in their keyword argument order and may have two separate cache363entries.</p>364<p>If <em>user_function</em> is specified, it must be a callable. This allows the365<em>lru_cache</em> decorator to be applied directly to a user function, leaving366the <em>maxsize</em> at its default value of 128:</p>367<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@lru_cache</span>368<span class="k">def</span><span class="w"> </span><span class="nf">count_vowels</span><span class="p">(</span><span class="n">word</span><span class="p">):</span>369    <span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="n">word</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">vowel</span><span class="p">)</span> <span class="k">for</span> <span class="n">vowel</span> <span class="ow">in</span> <span class="s1">&#39;AEIOUaeiou&#39;</span><span class="p">)</span>370</pre></div>371</div>372<p>If <em>maxsize</em> is set to <code class="docutils literal notranslate"><span class="pre">None</span></code>, the LRU feature is disabled and the cache can373grow without bound.</p>374<p>If <em>typed</em> is set to true, function arguments of different types will be375cached separately.  If <em>typed</em> is false, the implementation will usually376regard them as equivalent calls and only cache a single result. (Some377types such as <em>str</em> and <em>int</em> may be cached separately even when <em>typed</em>378is false.)</p>379<p>Note, type specificity applies only to the function’s immediate arguments380rather than their contents.  The scalar arguments, <code class="docutils literal notranslate"><span class="pre">Decimal(42)</span></code> and381<code class="docutils literal notranslate"><span class="pre">Fraction(42)</span></code> are treated as distinct calls with distinct results.382In contrast, the tuple arguments <code class="docutils literal notranslate"><span class="pre">('answer',</span> <span class="pre">Decimal(42))</span></code> and383<code class="docutils literal notranslate"><span class="pre">('answer',</span> <span class="pre">Fraction(42))</span></code> are treated as equivalent.</p>384<p>The wrapped function is instrumented with a <code class="xref py py-func docutils literal notranslate"><span class="pre">cache_parameters()</span></code>385function that returns a new <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> showing the values for <em>maxsize</em>386and <em>typed</em>.  This is for information purposes only.  Mutating the values387has no effect.</p>388<p id="functools.lru_cache.cache_info">To help measure the effectiveness of the cache and tune the <em>maxsize</em>389parameter, the wrapped function is instrumented with a <code class="xref py py-func docutils literal notranslate"><span class="pre">cache_info()</span></code>390function that returns a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a> showing <em>hits</em>, <em>misses</em>,391<em>maxsize</em> and <em>currsize</em>.</p>392<p id="functools.lru_cache.cache_clear">The decorator also provides a <code class="xref py py-func docutils literal notranslate"><span class="pre">cache_clear()</span></code> function for clearing or393invalidating the cache.</p>394<p>The original underlying function is accessible through the395<code class="xref py py-attr docutils literal notranslate"><span class="pre">__wrapped__</span></code> attribute.  This is useful for introspection, for396bypassing the cache, or for rewrapping the function with a different cache.</p>397<p>The cache keeps references to the arguments and return values until they age398out of the cache or until the cache is cleared.</p>399<p>If a method is cached, the <code class="docutils literal notranslate"><span class="pre">self</span></code> instance argument is included in the400cache.  See <a class="reference internal" href="../faq/programming.html#faq-cache-method-calls"><span class="std std-ref">How do I cache method calls?</span></a></p>401<p>An <a class="reference external" href="https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_Recently_Used_(LRU)">LRU (least recently used) cache</a>402works best when the most recent calls are the best predictors of upcoming403calls (for example, the most popular articles on a news server tend to404change each day).  The cache’s size limit assures that the cache does not405grow without bound on long-running processes such as web servers.</p>406<p>In general, the LRU cache should only be used when you want to reuse407previously computed values.  Accordingly, it doesn’t make sense to cache408functions with side-effects, functions that need to create409distinct mutable objects on each call (such as generators and async functions),410or impure functions such as time() or random().</p>411<p>Example of an LRU cache for static web content:</p>412<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@lru_cache</span><span class="p">(</span><span class="n">maxsize</span><span class="o">=</span><span class="mi">32</span><span class="p">)</span>413<span class="k">def</span><span class="w"> </span><span class="nf">get_pep</span><span class="p">(</span><span class="n">num</span><span class="p">):</span>414    <span class="s1">&#39;Retrieve text of a Python Enhancement Proposal&#39;</span>415    <span class="n">resource</span> <span class="o">=</span> <span class="sa">f</span><span class="s1">&#39;https://peps.python.org/pep-</span><span class="si">{</span><span class="n">num</span><span class="si">:</span><span class="s1">04d</span><span class="si">}</span><span class="s1">&#39;</span>416    <span class="k">try</span><span class="p">:</span>417        <span class="k">with</span> <span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">urlopen</span><span class="p">(</span><span class="n">resource</span><span class="p">)</span> <span class="k">as</span> <span class="n">s</span><span class="p">:</span>418            <span class="k">return</span> <span class="n">s</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>419    <span class="k">except</span> <span class="n">urllib</span><span class="o">.</span><span class="n">error</span><span class="o">.</span><span class="n">HTTPError</span><span class="p">:</span>420        <span class="k">return</span> <span class="s1">&#39;Not Found&#39;</span>421 422<span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">290</span><span class="p">,</span> <span class="mi">308</span><span class="p">,</span> <span class="mi">320</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">218</span><span class="p">,</span> <span class="mi">320</span><span class="p">,</span> <span class="mi">279</span><span class="p">,</span> <span class="mi">289</span><span class="p">,</span> <span class="mi">320</span><span class="p">,</span> <span class="mi">9991</span><span class="p">:</span>423<span class="o">...</span>     <span class="n">pep</span> <span class="o">=</span> <span class="n">get_pep</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>424<span class="o">...</span>     <span class="nb">print</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">pep</span><span class="p">))</span>425 426<span class="o">&gt;&gt;&gt;</span> <span class="n">get_pep</span><span class="o">.</span><span class="n">cache_info</span><span class="p">()</span>427<span class="n">CacheInfo</span><span class="p">(</span><span class="n">hits</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">misses</span><span class="o">=</span><span class="mi">8</span><span class="p">,</span> <span class="n">maxsize</span><span class="o">=</span><span class="mi">32</span><span class="p">,</span> <span class="n">currsize</span><span class="o">=</span><span class="mi">8</span><span class="p">)</span>428</pre></div>429</div>430<p>Example of efficiently computing431<a class="reference external" href="https://en.wikipedia.org/wiki/Fibonacci_number">Fibonacci numbers</a>432using a cache to implement a433<a class="reference external" href="https://en.wikipedia.org/wiki/Dynamic_programming">dynamic programming</a>434technique:</p>435<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@lru_cache</span><span class="p">(</span><span class="n">maxsize</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>436<span class="k">def</span><span class="w"> </span><span class="nf">fib</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>437    <span class="k">if</span> <span class="n">n</span> <span class="o">&lt;</span> <span class="mi">2</span><span class="p">:</span>438        <span class="k">return</span> <span class="n">n</span>439    <span class="k">return</span> <span class="n">fib</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">+</span> <span class="n">fib</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">2</span><span class="p">)</span>440 441<span class="o">&gt;&gt;&gt;</span> <span class="p">[</span><span class="n">fib</span><span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">16</span><span class="p">)]</span>442<span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">13</span><span class="p">,</span> <span class="mi">21</span><span class="p">,</span> <span class="mi">34</span><span class="p">,</span> <span class="mi">55</span><span class="p">,</span> <span class="mi">89</span><span class="p">,</span> <span class="mi">144</span><span class="p">,</span> <span class="mi">233</span><span class="p">,</span> <span class="mi">377</span><span class="p">,</span> <span class="mi">610</span><span class="p">]</span>443 444<span class="o">&gt;&gt;&gt;</span> <span class="n">fib</span><span class="o">.</span><span class="n">cache_info</span><span class="p">()</span>445<span class="n">CacheInfo</span><span class="p">(</span><span class="n">hits</span><span class="o">=</span><span class="mi">28</span><span class="p">,</span> <span class="n">misses</span><span class="o">=</span><span class="mi">16</span><span class="p">,</span> <span class="n">maxsize</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">currsize</span><span class="o">=</span><span class="mi">16</span><span class="p">)</span>446</pre></div>447</div>448<div class="versionadded">449<p><span class="versionmodified added">Added in version 3.2.</span></p>450</div>451<div class="versionchanged">452<p><span class="versionmodified changed">Changed in version 3.3: </span>Added the <em>typed</em> option.</p>453</div>454<div class="versionchanged">455<p><span class="versionmodified changed">Changed in version 3.8: </span>Added the <em>user_function</em> option.</p>456</div>457<div class="versionchanged">458<p><span class="versionmodified changed">Changed in version 3.9: </span>Added the function <code class="xref py py-func docutils literal notranslate"><span class="pre">cache_parameters()</span></code></p>459</div>460</dd></dl>461 462<dl class="py function">463<dt class="sig sig-object py" id="functools.total_ordering">464<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">total_ordering</span></span><a class="headerlink" href="#functools.total_ordering" title="Link to this definition">¶</a></dt>465<dd><p>Given a class defining one or more rich comparison ordering methods, this466class decorator supplies the rest.  This simplifies the effort involved467in specifying all of the possible rich comparison operations:</p>468<p>The class must define one of <a class="reference internal" href="../reference/datamodel.html#object.__lt__" title="object.__lt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__le__" title="object.__le__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__le__()</span></code></a>,469<a class="reference internal" href="../reference/datamodel.html#object.__gt__" title="object.__gt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__gt__()</span></code></a>, or <a class="reference internal" href="../reference/datamodel.html#object.__ge__" title="object.__ge__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__ge__()</span></code></a>.470In addition, the class should supply an <a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> method.</p>471<p>For example:</p>472<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@total_ordering</span>473<span class="k">class</span><span class="w"> </span><span class="nc">Student</span><span class="p">:</span>474    <span class="k">def</span><span class="w"> </span><span class="nf">_is_valid_operand</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>475        <span class="k">return</span> <span class="p">(</span><span class="nb">hasattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="s2">&quot;lastname&quot;</span><span class="p">)</span> <span class="ow">and</span>476                <span class="nb">hasattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="s2">&quot;firstname&quot;</span><span class="p">))</span>477    <span class="k">def</span><span class="w"> </span><span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>478        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">_is_valid_operand</span><span class="p">(</span><span class="n">other</span><span class="p">):</span>479            <span class="k">return</span> <span class="bp">NotImplemented</span>480        <span class="k">return</span> <span class="p">((</span><span class="bp">self</span><span class="o">.</span><span class="n">lastname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="bp">self</span><span class="o">.</span><span class="n">firstname</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span> <span class="o">==</span>481                <span class="p">(</span><span class="n">other</span><span class="o">.</span><span class="n">lastname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="n">other</span><span class="o">.</span><span class="n">firstname</span><span class="o">.</span><span class="n">lower</span><span class="p">()))</span>482    <span class="k">def</span><span class="w"> </span><span class="fm">__lt__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>483        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">_is_valid_operand</span><span class="p">(</span><span class="n">other</span><span class="p">):</span>484            <span class="k">return</span> <span class="bp">NotImplemented</span>485        <span class="k">return</span> <span class="p">((</span><span class="bp">self</span><span class="o">.</span><span class="n">lastname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="bp">self</span><span class="o">.</span><span class="n">firstname</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span> <span class="o">&lt;</span>486                <span class="p">(</span><span class="n">other</span><span class="o">.</span><span class="n">lastname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="n">other</span><span class="o">.</span><span class="n">firstname</span><span class="o">.</span><span class="n">lower</span><span class="p">()))</span>487</pre></div>488</div>489<div class="admonition note">490<p class="admonition-title">Note</p>491<p>While this decorator makes it easy to create well behaved totally492ordered types, it <em>does</em> come at the cost of slower execution and493more complex stack traces for the derived comparison methods. If494performance benchmarking indicates this is a bottleneck for a given495application, implementing all six rich comparison methods instead is496likely to provide an easy speed boost.</p>497</div>498<div class="admonition note">499<p class="admonition-title">Note</p>500<p>This decorator makes no attempt to override methods that have been501declared in the class <em>or its superclasses</em>. Meaning that if a502superclass defines a comparison operator, <em>total_ordering</em> will not503implement it again, even if the original method is abstract.</p>504</div>505<div class="versionadded">506<p><span class="versionmodified added">Added in version 3.2.</span></p>507</div>508<div class="versionchanged">509<p><span class="versionmodified changed">Changed in version 3.4: </span>Returning <code class="docutils literal notranslate"><span class="pre">NotImplemented</span></code> from the underlying comparison function for510unrecognised types is now supported.</p>511</div>512</dd></dl>513 514<dl class="py data">515<dt class="sig sig-object py" id="functools.Placeholder">516<span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">Placeholder</span></span><a class="headerlink" href="#functools.Placeholder" title="Link to this definition">¶</a></dt>517<dd><p>A singleton object used as a sentinel to reserve a place518for positional arguments when calling <a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code></a>519and <a class="reference internal" href="#functools.partialmethod" title="functools.partialmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">partialmethod()</span></code></a>.</p>520<div class="versionadded">521<p><span class="versionmodified added">Added in version 3.14.</span></p>522</div>523</dd></dl>524 525<dl class="py function">526<dt class="sig sig-object py" id="functools.partial">527<span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">partial</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">keywords</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.partial" title="Link to this definition">¶</a></dt>528<dd><p>Return a new <a class="reference internal" href="#partial-objects"><span class="std std-ref">partial object</span></a> which when called529will behave like <em>func</em> called with the positional arguments <em>args</em>530and keyword arguments <em>keywords</em>. If more arguments are supplied to the531call, they are appended to <em>args</em>. If additional keyword arguments are532supplied, they extend and override <em>keywords</em>.533Roughly equivalent to:</p>534<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">partial</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">keywords</span><span class="p">):</span>535    <span class="k">def</span><span class="w"> </span><span class="nf">newfunc</span><span class="p">(</span><span class="o">*</span><span class="n">more_args</span><span class="p">,</span> <span class="o">**</span><span class="n">more_keywords</span><span class="p">):</span>536        <span class="k">return</span> <span class="n">func</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">*</span><span class="n">more_args</span><span class="p">,</span> <span class="o">**</span><span class="p">(</span><span class="n">keywords</span> <span class="o">|</span> <span class="n">more_keywords</span><span class="p">))</span>537    <span class="n">newfunc</span><span class="o">.</span><span class="n">func</span> <span class="o">=</span> <span class="n">func</span>538    <span class="n">newfunc</span><span class="o">.</span><span class="n">args</span> <span class="o">=</span> <span class="n">args</span>539    <span class="n">newfunc</span><span class="o">.</span><span class="n">keywords</span> <span class="o">=</span> <span class="n">keywords</span>540    <span class="k">return</span> <span class="n">newfunc</span>541</pre></div>542</div>543<p>The <code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code> function is used for partial function application which “freezes”544some portion of a function’s arguments and/or keywords resulting in a new object545with a simplified signature.  For example, <code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code> can be used to create546a callable that behaves like the <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a> function where the <em>base</em> argument547defaults to <code class="docutils literal notranslate"><span class="pre">2</span></code>:</p>548<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">basetwo</span> <span class="o">=</span> <span class="n">partial</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>549<span class="gp">&gt;&gt;&gt; </span><span class="n">basetwo</span><span class="o">.</span><span class="vm">__doc__</span> <span class="o">=</span> <span class="s1">&#39;Convert base 2 string to an int.&#39;</span>550<span class="gp">&gt;&gt;&gt; </span><span class="n">basetwo</span><span class="p">(</span><span class="s1">&#39;10010&#39;</span><span class="p">)</span>551<span class="go">18</span>552</pre></div>553</div>554<p>If <a class="reference internal" href="#functools.Placeholder" title="functools.Placeholder"><code class="xref py py-data docutils literal notranslate"><span class="pre">Placeholder</span></code></a> sentinels are present in <em>args</em>, they will be filled first555when <code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code> is called. This makes it possible to pre-fill any positional556argument with a call to <code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code>; without <code class="xref py py-data docutils literal notranslate"><span class="pre">Placeholder</span></code>,557only the chosen number of leading positional arguments can be pre-filled.</p>558<p>If any <code class="xref py py-data docutils literal notranslate"><span class="pre">Placeholder</span></code> sentinels are present, all must be filled at call time:</p>559<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">say_to_world</span> <span class="o">=</span> <span class="n">partial</span><span class="p">(</span><span class="nb">print</span><span class="p">,</span> <span class="n">Placeholder</span><span class="p">,</span> <span class="n">Placeholder</span><span class="p">,</span> <span class="s2">&quot;world!&quot;</span><span class="p">)</span>560<span class="gp">&gt;&gt;&gt; </span><span class="n">say_to_world</span><span class="p">(</span><span class="s1">&#39;Hello&#39;</span><span class="p">,</span> <span class="s1">&#39;dear&#39;</span><span class="p">)</span>561<span class="go">Hello dear world!</span>562</pre></div>563</div>564<p>Calling <code class="docutils literal notranslate"><span class="pre">say_to_world('Hello')</span></code> raises a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>, because565only one positional argument is provided, but there are two placeholders566that must be filled in.</p>567<p>If <code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code> is applied to an existing <code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code> object,568<code class="xref py py-data docutils literal notranslate"><span class="pre">Placeholder</span></code> sentinels of the input object are filled in with569new positional arguments.570A placeholder can be retained by inserting a new571<code class="xref py py-data docutils literal notranslate"><span class="pre">Placeholder</span></code> sentinel to the place held by a previous <code class="xref py py-data docutils literal notranslate"><span class="pre">Placeholder</span></code>:</p>572<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">functools</span><span class="w"> </span><span class="kn">import</span> <span class="n">partial</span><span class="p">,</span> <span class="n">Placeholder</span> <span class="k">as</span> <span class="n">_</span>573<span class="gp">&gt;&gt;&gt; </span><span class="n">remove</span> <span class="o">=</span> <span class="n">partial</span><span class="p">(</span><span class="nb">str</span><span class="o">.</span><span class="n">replace</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">)</span>574<span class="gp">&gt;&gt;&gt; </span><span class="n">message</span> <span class="o">=</span> <span class="s1">&#39;Hello, dear dear world!&#39;</span>575<span class="gp">&gt;&gt;&gt; </span><span class="n">remove</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="s1">&#39; dear&#39;</span><span class="p">)</span>576<span class="go">&#39;Hello, world!&#39;</span>577<span class="gp">&gt;&gt;&gt; </span><span class="n">remove_dear</span> <span class="o">=</span> <span class="n">partial</span><span class="p">(</span><span class="n">remove</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="s1">&#39; dear&#39;</span><span class="p">)</span>578<span class="gp">&gt;&gt;&gt; </span><span class="n">remove_dear</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>579<span class="go">&#39;Hello, world!&#39;</span>580<span class="gp">&gt;&gt;&gt; </span><span class="n">remove_first_dear</span> <span class="o">=</span> <span class="n">partial</span><span class="p">(</span><span class="n">remove_dear</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>581<span class="gp">&gt;&gt;&gt; </span><span class="n">remove_first_dear</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>582<span class="go">&#39;Hello, dear world!&#39;</span>583</pre></div>584</div>585<p><code class="xref py py-data docutils literal notranslate"><span class="pre">Placeholder</span></code> cannot be passed to <code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code> as a keyword argument.</p>586<div class="versionchanged">587<p><span class="versionmodified changed">Changed in version 3.14: </span>Added support for <a class="reference internal" href="#functools.Placeholder" title="functools.Placeholder"><code class="xref py py-data docutils literal notranslate"><span class="pre">Placeholder</span></code></a> in positional arguments.</p>588</div>589</dd></dl>590 591<dl class="py class">592<dt class="sig sig-object py" id="functools.partialmethod">593<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">partialmethod</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">keywords</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.partialmethod" title="Link to this definition">¶</a></dt>594<dd><p>Return a new <code class="xref py py-class docutils literal notranslate"><span class="pre">partialmethod</span></code> descriptor which behaves595like <a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code></a> except that it is designed to be used as a method596definition rather than being directly callable.</p>597<p><em>func</em> must be a <a class="reference internal" href="../glossary.html#term-descriptor"><span class="xref std std-term">descriptor</span></a> or a callable (objects which are both,598like normal functions, are handled as descriptors).</p>599<p>When <em>func</em> is a descriptor (such as a normal Python function,600<a class="reference internal" href="functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">classmethod()</span></code></a>, <a class="reference internal" href="functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a>, <a class="reference internal" href="abc.html#abc.abstractmethod" title="abc.abstractmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">abstractmethod()</span></code></a> or601another instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">partialmethod</span></code>), calls to <code class="docutils literal notranslate"><span class="pre">__get__</span></code> are602delegated to the underlying descriptor, and an appropriate603<a class="reference internal" href="#partial-objects"><span class="std std-ref">partial object</span></a> returned as the result.</p>604<p>When <em>func</em> is a non-descriptor callable, an appropriate bound method is605created dynamically. This behaves like a normal Python function when606used as a method: the <em>self</em> argument will be inserted as the first607positional argument, even before the <em>args</em> and <em>keywords</em> supplied to608the <code class="xref py py-class docutils literal notranslate"><span class="pre">partialmethod</span></code> constructor.</p>609<p>Example:</p>610<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span><span class="w"> </span><span class="nc">Cell</span><span class="p">:</span>611<span class="gp">... </span>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>612<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">_alive</span> <span class="o">=</span> <span class="kc">False</span>613<span class="gp">... </span>    <span class="nd">@property</span>614<span class="gp">... </span>    <span class="k">def</span><span class="w"> </span><span class="nf">alive</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>615<span class="gp">... </span>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_alive</span>616<span class="gp">... </span>    <span class="k">def</span><span class="w"> </span><span class="nf">set_state</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">state</span><span class="p">):</span>617<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">_alive</span> <span class="o">=</span> <span class="nb">bool</span><span class="p">(</span><span class="n">state</span><span class="p">)</span>618<span class="gp">... </span>    <span class="n">set_alive</span> <span class="o">=</span> <span class="n">partialmethod</span><span class="p">(</span><span class="n">set_state</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span>619<span class="gp">... </span>    <span class="n">set_dead</span> <span class="o">=</span> <span class="n">partialmethod</span><span class="p">(</span><span class="n">set_state</span><span class="p">,</span> <span class="kc">False</span><span class="p">)</span>620<span class="gp">...</span>621<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Cell</span><span class="p">()</span>622<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">alive</span>623<span class="go">False</span>624<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">set_alive</span><span class="p">()</span>625<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">alive</span>626<span class="go">True</span>627</pre></div>628</div>629<div class="versionadded">630<p><span class="versionmodified added">Added in version 3.4.</span></p>631</div>632</dd></dl>633 634<dl class="py function">635<dt class="sig sig-object py" id="functools.reduce">636<span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">reduce</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">function</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">/</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">initial</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#functools.reduce" title="Link to this definition">¶</a></dt>637<dd><p>Apply <em>function</em> of two arguments cumulatively to the items of <em>iterable</em>, from638left to right, so as to reduce the iterable to a single value.  For example,639<code class="docutils literal notranslate"><span class="pre">reduce(lambda</span> <span class="pre">x,</span> <span class="pre">y:</span> <span class="pre">x+y,</span> <span class="pre">[1,</span> <span class="pre">2,</span> <span class="pre">3,</span> <span class="pre">4,</span> <span class="pre">5])</span></code> calculates <code class="docutils literal notranslate"><span class="pre">((((1+2)+3)+4)+5)</span></code>.640The left argument, <em>x</em>, is the accumulated value and the right argument, <em>y</em>, is641the update value from the <em>iterable</em>.  If the optional <em>initial</em> is present,642it is placed before the items of the iterable in the calculation, and serves as643a default when the iterable is empty.  If <em>initial</em> is not given and644<em>iterable</em> contains only one item, the first item is returned.</p>645<p>Roughly equivalent to:</p>646<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">initial_missing</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>647 648<span class="k">def</span><span class="w"> </span><span class="nf">reduce</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">iterable</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="n">initial_missing</span><span class="p">):</span>649    <span class="n">it</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>650    <span class="k">if</span> <span class="n">initial</span> <span class="ow">is</span> <span class="n">initial_missing</span><span class="p">:</span>651        <span class="n">value</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">it</span><span class="p">)</span>652    <span class="k">else</span><span class="p">:</span>653        <span class="n">value</span> <span class="o">=</span> <span class="n">initial</span>654    <span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">it</span><span class="p">:</span>655        <span class="n">value</span> <span class="o">=</span> <span class="n">function</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">element</span><span class="p">)</span>656    <span class="k">return</span> <span class="n">value</span>657</pre></div>658</div>659<p>See <a class="reference internal" href="itertools.html#itertools.accumulate" title="itertools.accumulate"><code class="xref py py-func docutils literal notranslate"><span class="pre">itertools.accumulate()</span></code></a> for an iterator that yields all intermediate660values.</p>661<div class="versionchanged">662<p><span class="versionmodified changed">Changed in version 3.14: </span><em>initial</em> is now supported as a keyword argument.</p>663</div>664</dd></dl>665 666<dl class="py function">667<dt class="sig sig-object py" id="functools.singledispatch">668<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">singledispatch</span></span><a class="headerlink" href="#functools.singledispatch" title="Link to this definition">¶</a></dt>669<dd><p>Transform a function into a <a class="reference internal" href="../glossary.html#term-single-dispatch"><span class="xref std std-term">single-dispatch</span></a> <a class="reference internal" href="../glossary.html#term-generic-function"><span class="xref std std-term">generic function</span></a>.</p>670<p>To define a generic function, decorate it with the <code class="docutils literal notranslate"><span class="pre">&#64;singledispatch</span></code>671decorator. When defining a function using <code class="docutils literal notranslate"><span class="pre">&#64;singledispatch</span></code>, note that the672dispatch happens on the type of the first argument:</p>673<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">functools</span><span class="w"> </span><span class="kn">import</span> <span class="n">singledispatch</span>674<span class="gp">&gt;&gt;&gt; </span><span class="nd">@singledispatch</span>675<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">fun</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>676<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>677<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Let me just say,&quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>678<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>679</pre></div>680</div>681<p id="functools.singledispatch.register">To add overloaded implementations to the function, use the <code class="xref py py-func docutils literal notranslate"><span class="pre">register()</span></code>682attribute of the generic function, which can be used as a decorator.  For683functions annotated with types, the decorator will infer the type of the684first argument automatically:</p>685<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span>686<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="n">arg</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>687<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>688<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Strength in numbers, eh?&quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>689<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>690<span class="gp">...</span>691<span class="gp">&gt;&gt;&gt; </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span>692<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="n">arg</span><span class="p">:</span> <span class="nb">list</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>693<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>694<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Enumerate this:&quot;</span><span class="p">)</span>695<span class="gp">... </span>    <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">elem</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>696<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">elem</span><span class="p">)</span>697</pre></div>698</div>699<p><a class="reference internal" href="typing.html#typing.Union" title="typing.Union"><code class="xref py py-class docutils literal notranslate"><span class="pre">typing.Union</span></code></a> can also be used:</p>700<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span>701<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="n">arg</span><span class="p">:</span> <span class="nb">int</span> <span class="o">|</span> <span class="nb">float</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>702<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>703<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Strength in numbers, eh?&quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>704<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>705<span class="gp">...</span>706<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Union</span>707<span class="gp">&gt;&gt;&gt; </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span>708<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="n">arg</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="nb">list</span><span class="p">,</span> <span class="nb">set</span><span class="p">],</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>709<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>710<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Enumerate this:&quot;</span><span class="p">)</span>711<span class="gp">... </span>    <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">elem</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>712<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">elem</span><span class="p">)</span>713<span class="gp">...</span>714</pre></div>715</div>716<p>For code which doesn’t use type annotations, the appropriate type717argument can be passed explicitly to the decorator itself:</p>718<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="nb">complex</span><span class="p">)</span>719<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>720<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>721<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Better than complicated.&quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>722<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">arg</span><span class="o">.</span><span class="n">real</span><span class="p">,</span> <span class="n">arg</span><span class="o">.</span><span class="n">imag</span><span class="p">)</span>723<span class="gp">...</span>724</pre></div>725</div>726<p>For code that dispatches on a collections type (e.g., <code class="docutils literal notranslate"><span class="pre">list</span></code>), but wants727to typehint the items of the collection (e.g., <code class="docutils literal notranslate"><span class="pre">list[int]</span></code>), the728dispatch type should be passed explicitly to the decorator itself with the729typehint going into the function definition:</p>730<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>731<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="n">arg</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">int</span><span class="p">],</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>732<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>733<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Enumerate this:&quot;</span><span class="p">)</span>734<span class="gp">... </span>    <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">elem</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>735<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">elem</span><span class="p">)</span>736</pre></div>737</div>738<div class="admonition note">739<p class="admonition-title">Note</p>740<p>At runtime the function will dispatch on an instance of a list regardless741of the type contained within the list i.e. <code class="docutils literal notranslate"><span class="pre">[1,2,3]</span></code> will be742dispatched the same as <code class="docutils literal notranslate"><span class="pre">[&quot;foo&quot;,</span> <span class="pre">&quot;bar&quot;,</span> <span class="pre">&quot;baz&quot;]</span></code>. The annotation743provided in this example is for static type checkers only and has no744runtime impact.</p>745</div>746<p>To enable registering <a class="reference internal" href="../glossary.html#term-lambda"><span class="xref std std-term">lambdas</span></a> and pre-existing functions,747the <a class="reference internal" href="#functools.singledispatch.register" title="functools.singledispatch.register"><code class="xref py py-func docutils literal notranslate"><span class="pre">register()</span></code></a> attribute can also be used in a functional form:</p>748<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span><span class="w"> </span><span class="nf">nothing</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>749<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Nothing.&quot;</span><span class="p">)</span>750<span class="gp">...</span>751<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="kc">None</span><span class="p">),</span> <span class="n">nothing</span><span class="p">)</span>752</pre></div>753</div>754<p>The <a class="reference internal" href="#functools.singledispatch.register" title="functools.singledispatch.register"><code class="xref py py-func docutils literal notranslate"><span class="pre">register()</span></code></a> attribute returns the undecorated function. This755enables decorator stacking, <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pickling</span></code></a>, and the creation756of unit tests for each variant independently:</p>757<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="nb">float</span><span class="p">)</span>758<span class="gp">... </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="n">Decimal</span><span class="p">)</span>759<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">fun_num</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>760<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>761<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Half of your number:&quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>762<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">arg</span> <span class="o">/</span> <span class="mi">2</span><span class="p">)</span>763<span class="gp">...</span>764<span class="gp">&gt;&gt;&gt; </span><span class="n">fun_num</span> <span class="ow">is</span> <span class="n">fun</span>765<span class="go">False</span>766</pre></div>767</div>768<p>When called, the generic function dispatches on the type of the first769argument:</p>770<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="p">(</span><span class="s2">&quot;Hello, world.&quot;</span><span class="p">)</span>771<span class="go">Hello, world.</span>772<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="p">(</span><span class="s2">&quot;test.&quot;</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>773<span class="go">Let me just say, test.</span>774<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>775<span class="go">Strength in numbers, eh? 42</span>776<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="p">([</span><span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;eggs&#39;</span><span class="p">,</span> <span class="s1">&#39;spam&#39;</span><span class="p">],</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>777<span class="go">Enumerate this:</span>778<span class="go">0 spam</span>779<span class="go">1 spam</span>780<span class="go">2 eggs</span>781<span class="go">3 spam</span>782<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="p">(</span><span class="kc">None</span><span class="p">)</span>783<span class="go">Nothing.</span>784<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="p">(</span><span class="mf">1.23</span><span class="p">)</span>785<span class="go">0.615</span>786</pre></div>787</div>788<p>Where there is no registered implementation for a specific type, its789method resolution order is used to find a more generic implementation.790The original function decorated with <code class="docutils literal notranslate"><span class="pre">&#64;singledispatch</span></code> is registered791for the base <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a> type, which means it is used if no better792implementation is found.</p>793<p>If an implementation is registered to an <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a>,794virtual subclasses of the base class will be dispatched to that795implementation:</p>796<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Mapping</span>797<span class="gp">&gt;&gt;&gt; </span><span class="nd">@fun</span><span class="o">.</span><span class="n">register</span>798<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="n">arg</span><span class="p">:</span> <span class="n">Mapping</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>799<span class="gp">... </span>    <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span>800<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Keys &amp; Values&quot;</span><span class="p">)</span>801<span class="gp">... </span>    <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">arg</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>802<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="s2">&quot;=&gt;&quot;</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>803<span class="gp">...</span>804<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="p">({</span><span class="s2">&quot;a&quot;</span><span class="p">:</span> <span class="s2">&quot;b&quot;</span><span class="p">})</span>805<span class="go">a =&gt; b</span>806</pre></div>807</div>808<p>To check which implementation the generic function will choose for809a given type, use the <code class="docutils literal notranslate"><span class="pre">dispatch()</span></code> attribute:</p>810<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="o">.</span><span class="n">dispatch</span><span class="p">(</span><span class="nb">float</span><span class="p">)</span>811<span class="go">&lt;function fun_num at 0x1035a2840&gt;</span>812<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="o">.</span><span class="n">dispatch</span><span class="p">(</span><span class="nb">dict</span><span class="p">)</span>    <span class="c1"># note: default implementation</span>813<span class="go">&lt;function fun at 0x103fe0000&gt;</span>814</pre></div>815</div>816<p>To access all registered implementations, use the read-only <code class="docutils literal notranslate"><span class="pre">registry</span></code>817attribute:</p>818<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="o">.</span><span class="n">registry</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span>819<span class="go">dict_keys([&lt;class &#39;NoneType&#39;&gt;, &lt;class &#39;int&#39;&gt;, &lt;class &#39;object&#39;&gt;,</span>820<span class="go">          &lt;class &#39;decimal.Decimal&#39;&gt;, &lt;class &#39;list&#39;&gt;,</span>821<span class="go">          &lt;class &#39;float&#39;&gt;])</span>822<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="o">.</span><span class="n">registry</span><span class="p">[</span><span class="nb">float</span><span class="p">]</span>823<span class="go">&lt;function fun_num at 0x1035a2840&gt;</span>824<span class="gp">&gt;&gt;&gt; </span><span class="n">fun</span><span class="o">.</span><span class="n">registry</span><span class="p">[</span><span class="nb">object</span><span class="p">]</span>825<span class="go">&lt;function fun at 0x103fe0000&gt;</span>826</pre></div>827</div>828<div class="versionadded">829<p><span class="versionmodified added">Added in version 3.4.</span></p>830</div>831<div class="versionchanged">832<p><span class="versionmodified changed">Changed in version 3.7: </span>The <a class="reference internal" href="#functools.singledispatch.register" title="functools.singledispatch.register"><code class="xref py py-func docutils literal notranslate"><span class="pre">register()</span></code></a> attribute now supports using type annotations.</p>833</div>834<div class="versionchanged">835<p><span class="versionmodified changed">Changed in version 3.11: </span>The <a class="reference internal" href="#functools.singledispatch.register" title="functools.singledispatch.register"><code class="xref py py-func docutils literal notranslate"><span class="pre">register()</span></code></a> attribute now supports836<a class="reference internal" href="typing.html#typing.Union" title="typing.Union"><code class="xref py py-class docutils literal notranslate"><span class="pre">typing.Union</span></code></a> as a type annotation.</p>837</div>838</dd></dl>839 840<dl class="py class">841<dt class="sig sig-object py" id="functools.singledispatchmethod">842<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">singledispatchmethod</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.singledispatchmethod" title="Link to this definition">¶</a></dt>843<dd><p>Transform a method into a <a class="reference internal" href="../glossary.html#term-single-dispatch"><span class="xref std std-term">single-dispatch</span></a> <a class="reference internal" href="../glossary.html#term-generic-function"><span class="xref std std-term">generic function</span></a>.</p>844<p>To define a generic method, decorate it with the <code class="docutils literal notranslate"><span class="pre">&#64;singledispatchmethod</span></code>845decorator. When defining a method using <code class="docutils literal notranslate"><span class="pre">&#64;singledispatchmethod</span></code>, note846that the dispatch happens on the type of the first non-<em>self</em> or non-<em>cls</em>847argument:</p>848<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Negator</span><span class="p">:</span>849    <span class="nd">@singledispatchmethod</span>850    <span class="k">def</span><span class="w"> </span><span class="nf">neg</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>851        <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span><span class="s2">&quot;Cannot negate a&quot;</span><span class="p">)</span>852 853    <span class="nd">@neg</span><span class="o">.</span><span class="n">register</span>854    <span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>855        <span class="k">return</span> <span class="o">-</span><span class="n">arg</span>856 857    <span class="nd">@neg</span><span class="o">.</span><span class="n">register</span>858    <span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">:</span> <span class="nb">bool</span><span class="p">):</span>859        <span class="k">return</span> <span class="ow">not</span> <span class="n">arg</span>860</pre></div>861</div>862<p><code class="docutils literal notranslate"><span class="pre">&#64;singledispatchmethod</span></code> supports nesting with other decorators such as863<a class="reference internal" href="functions.html#classmethod" title="classmethod"><code class="xref py py-deco docutils literal notranslate"><span class="pre">&#64;classmethod</span></code></a>. Note that to allow for864<code class="docutils literal notranslate"><span class="pre">dispatcher.register</span></code>, <code class="docutils literal notranslate"><span class="pre">singledispatchmethod</span></code> must be the <em>outer most</em>865decorator. Here is the <code class="docutils literal notranslate"><span class="pre">Negator</span></code> class with the <code class="docutils literal notranslate"><span class="pre">neg</span></code> methods bound to866the class, rather than an instance of the class:</p>867<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Negator</span><span class="p">:</span>868    <span class="nd">@singledispatchmethod</span>869    <span class="nd">@classmethod</span>870    <span class="k">def</span><span class="w"> </span><span class="nf">neg</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>871        <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span><span class="s2">&quot;Cannot negate a&quot;</span><span class="p">)</span>872 873    <span class="nd">@neg</span><span class="o">.</span><span class="n">register</span>874    <span class="nd">@classmethod</span>875    <span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">arg</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>876        <span class="k">return</span> <span class="o">-</span><span class="n">arg</span>877 878    <span class="nd">@neg</span><span class="o">.</span><span class="n">register</span>879    <span class="nd">@classmethod</span>880    <span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">arg</span><span class="p">:</span> <span class="nb">bool</span><span class="p">):</span>881        <span class="k">return</span> <span class="ow">not</span> <span class="n">arg</span>882</pre></div>883</div>884<p>The same pattern can be used for other similar decorators:885<a class="reference internal" href="functions.html#staticmethod" title="staticmethod"><code class="xref py py-deco docutils literal notranslate"><span class="pre">&#64;staticmethod</span></code></a>, <a class="reference internal" href="abc.html#abc.abstractmethod" title="abc.abstractmethod"><code class="xref py py-deco docutils literal notranslate"><span class="pre">&#64;~abc.abstractmethod</span></code></a>, and others.</p>886<div class="versionadded">887<p><span class="versionmodified added">Added in version 3.8.</span></p>888</div>889<div class="versionchanged">890<p><span class="versionmodified changed">Changed in version 3.15: </span>Added support of non-<a class="reference internal" href="../glossary.html#term-descriptor"><span class="xref std std-term">descriptor</span></a> callables.</p>891</div>892</dd></dl>893 894<dl class="py function">895<dt class="sig sig-object py" id="functools.update_wrapper">896<span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">update_wrapper</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">wrapper</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wrapped</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">assigned</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">WRAPPER_ASSIGNMENTS</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">updated</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">WRAPPER_UPDATES</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.update_wrapper" title="Link to this definition">¶</a></dt>897<dd><p>Update a <em>wrapper</em> function to look like the <em>wrapped</em> function. The optional898arguments are tuples to specify which attributes of the original function are899assigned directly to the matching attributes on the wrapper function and which900attributes of the wrapper function are updated with the corresponding attributes901from the original function. The default values for these arguments are the902module level constants <code class="docutils literal notranslate"><span class="pre">WRAPPER_ASSIGNMENTS</span></code> (which assigns to the wrapper903function’s <a class="reference internal" href="../reference/datamodel.html#function.__module__" title="function.__module__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__module__</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#function.__name__" title="function.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a>,904<a class="reference internal" href="../reference/datamodel.html#function.__qualname__" title="function.__qualname__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__qualname__</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#function.__annotations__" title="function.__annotations__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code></a>,905<a class="reference internal" href="../reference/datamodel.html#function.__type_params__" title="function.__type_params__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__type_params__</span></code></a>, and <a class="reference internal" href="../reference/datamodel.html#function.__doc__" title="function.__doc__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code></a>, the906documentation string) and <code class="docutils literal notranslate"><span class="pre">WRAPPER_UPDATES</span></code> (which updates the wrapper907function’s <a class="reference internal" href="../reference/datamodel.html#function.__dict__" title="function.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>, i.e. the instance dictionary).</p>908<p>To allow access to the original function for introspection and other purposes909(e.g. bypassing a caching decorator such as <a class="reference internal" href="#functools.lru_cache" title="functools.lru_cache"><code class="xref py py-func docutils literal notranslate"><span class="pre">lru_cache()</span></code></a>), this function910automatically adds a <code class="docutils literal notranslate"><span class="pre">__wrapped__</span></code> attribute to the wrapper that refers to911the function being wrapped.</p>912<p>The main intended use for this function is in <a class="reference internal" href="../glossary.html#term-decorator"><span class="xref std std-term">decorator</span></a> functions which913wrap the decorated function and return the wrapper. If the wrapper function is914not updated, the metadata of the returned function will reflect the wrapper915definition rather than the original function definition, which is typically less916than helpful.</p>917<p><code class="xref py py-func docutils literal notranslate"><span class="pre">update_wrapper()</span></code> may be used with callables other than functions. Any918attributes named in <em>assigned</em> or <em>updated</em> that are missing from the object919being wrapped are ignored (i.e. this function will not attempt to set them920on the wrapper function). <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> is still raised if the921wrapper function itself is missing any attributes named in <em>updated</em>.</p>922<div class="versionchanged">923<p><span class="versionmodified changed">Changed in version 3.2: </span>The <code class="docutils literal notranslate"><span class="pre">__wrapped__</span></code> attribute is now automatically added.924The <a class="reference internal" href="../reference/datamodel.html#function.__annotations__" title="function.__annotations__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code></a> attribute is now copied by default.925Missing attributes no longer trigger an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.</p>926</div>927<div class="versionchanged">928<p><span class="versionmodified changed">Changed in version 3.4: </span>The <code class="docutils literal notranslate"><span class="pre">__wrapped__</span></code> attribute now always refers to the wrapped929function, even if that function defined a <code class="docutils literal notranslate"><span class="pre">__wrapped__</span></code> attribute.930(see <a class="reference external" href="https://bugs.python.org/issue?&#64;action=redirect&amp;bpo=17482">bpo-17482</a>)</p>931</div>932<div class="versionchanged">933<p><span class="versionmodified changed">Changed in version 3.12: </span>The <a class="reference internal" href="../reference/datamodel.html#function.__type_params__" title="function.__type_params__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__type_params__</span></code></a> attribute is now copied by default.</p>934</div>935</dd></dl>936 937<dl class="py function">938<dt class="sig sig-object py" id="functools.wraps">939<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">functools.</span></span><span class="sig-name descname"><span class="pre">wraps</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">wrapped</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">assigned</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">WRAPPER_ASSIGNMENTS</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">updated</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">WRAPPER_UPDATES</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#functools.wraps" title="Link to this definition">¶</a></dt>940<dd><p>This is a convenience function for invoking <a class="reference internal" href="#functools.update_wrapper" title="functools.update_wrapper"><code class="xref py py-func docutils literal notranslate"><span class="pre">update_wrapper()</span></code></a> as a941function decorator when defining a wrapper function.  It is equivalent to942<code class="docutils literal notranslate"><span class="pre">partial(update_wrapper,</span> <span class="pre">wrapped=wrapped,</span> <span class="pre">assigned=assigned,</span> <span class="pre">updated=updated)</span></code>.943For example:</p>944<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">functools</span><span class="w"> </span><span class="kn">import</span> <span class="n">wraps</span>945<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span><span class="w"> </span><span class="nf">my_decorator</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>946<span class="gp">... </span>    <span class="nd">@wraps</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>947<span class="gp">... </span>    <span class="k">def</span><span class="w"> </span><span class="nf">wrapper</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwds</span><span class="p">):</span>948<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Calling decorated function&#39;</span><span class="p">)</span>949<span class="gp">... </span>        <span class="k">return</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwds</span><span class="p">)</span>950<span class="gp">... </span>    <span class="k">return</span> <span class="n">wrapper</span>951<span class="gp">...</span>952<span class="gp">&gt;&gt;&gt; </span><span class="nd">@my_decorator</span>953<span class="gp">... </span><span class="k">def</span><span class="w"> </span><span class="nf">example</span><span class="p">():</span>954<span class="gp">... </span><span class="w">    </span><span class="sd">&quot;&quot;&quot;Docstring&quot;&quot;&quot;</span>955<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Called example function&#39;</span><span class="p">)</span>956<span class="gp">...</span>957<span class="gp">&gt;&gt;&gt; </span><span class="n">example</span><span class="p">()</span>958<span class="go">Calling decorated function</span>959<span class="go">Called example function</span>960<span class="gp">&gt;&gt;&gt; </span><span class="n">example</span><span class="o">.</span><span class="vm">__name__</span>961<span class="go">&#39;example&#39;</span>962<span class="gp">&gt;&gt;&gt; </span><span class="n">example</span><span class="o">.</span><span class="vm">__doc__</span>963<span class="go">&#39;Docstring&#39;</span>964</pre></div>965</div>966<p>Without the use of this decorator factory, the name of the example function967would have been <code class="docutils literal notranslate"><span class="pre">'wrapper'</span></code>, and the docstring of the original <code class="xref py py-func docutils literal notranslate"><span class="pre">example()</span></code>968would have been lost.</p>969</dd></dl>970 971<section id="partial-objects">972<span id="id1"></span><h2><a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code></a> Objects<a class="headerlink" href="#partial-objects" title="Link to this heading">¶</a></h2>973<p><a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code></a> objects are callable objects created by <a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal notranslate"><span class="pre">partial()</span></code></a>. They974have three read-only attributes:</p>975<dl class="py attribute">976<dt class="sig sig-object py" id="functools.partial.func">977<span class="sig-prename descclassname"><span class="pre">partial.</span></span><span class="sig-name descname"><span class="pre">func</span></span><a class="headerlink" href="#functools.partial.func" title="Link to this definition">¶</a></dt>978<dd><p>A callable object or function.  Calls to the <a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code></a> object will be979forwarded to <a class="reference internal" href="#functools.partial.func" title="functools.partial.func"><code class="xref py py-attr docutils literal notranslate"><span class="pre">func</span></code></a> with new arguments and keywords.</p>980</dd></dl>981 982<dl class="py attribute">983<dt class="sig sig-object py" id="functools.partial.args">984<span class="sig-prename descclassname"><span class="pre">partial.</span></span><span class="sig-name descname"><span class="pre">args</span></span><a class="headerlink" href="#functools.partial.args" title="Link to this definition">¶</a></dt>985<dd><p>The leftmost positional arguments that will be prepended to the positional986arguments provided to a <a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code></a> object call.</p>987</dd></dl>988 989<dl class="py attribute">990<dt class="sig sig-object py" id="functools.partial.keywords">991<span class="sig-prename descclassname"><span class="pre">partial.</span></span><span class="sig-name descname"><span class="pre">keywords</span></span><a class="headerlink" href="#functools.partial.keywords" title="Link to this definition">¶</a></dt>992<dd><p>The keyword arguments that will be supplied when the <a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code></a> object is993called.</p>994</dd></dl>995 996<p><a class="reference internal" href="#functools.partial" title="functools.partial"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code></a> objects are like <a class="reference internal" href="../reference/datamodel.html#user-defined-funcs"><span class="std std-ref">function objects</span></a> in that they are997callable, weak referenceable, and can have attributes.  There are some important998differences.  For instance, the <a class="reference internal" href="stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a> and <a class="reference internal" href="stdtypes.html#definition.__doc__" title="definition.__doc__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code></a> attributes999are not created automatically.</p>1000</section>1001</section>1002 1003 1004            <div class="clearer"></div>1005          </div>1006        </div>1007      </div>1008      <div class="sphinxsidebar" role="navigation" aria-label="Main">1009        <div class="sphinxsidebarwrapper">1010  <div>1011    <h3><a href="../contents.html">Table of Contents</a></h3>1012    <ul>1013<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> — Higher-order functions and operations on callable objects</a><ul>1014<li><a class="reference internal" href="#partial-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">partial</span></code> Objects</a></li>1015</ul>1016</li>1017</ul>1018 1019  </div>1020  <div>1021    <h4>Previous topic</h4>1022    <p class="topless"><a href="itertools.html"1023                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code> — Functions creating iterators for efficient looping</a></p>1024  </div>1025  <div>1026    <h4>Next topic</h4>1027    <p class="topless"><a href="operator.html"1028                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">operator</span></code> — Standard operators as functions</a></p>1029  </div>1030  <script>1031    document.addEventListener('DOMContentLoaded', () => {1032        const title = document.querySelector('meta[property="og:title"]').content;1033        const elements = document.querySelectorAll('.improvepage');1034        const pageurl = window.location.href.split('?')[0];1035        elements.forEach(element => {1036            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));1037            url.searchParams.set('pagetitle', title);1038            url.searchParams.set('pageurl', pageurl);1039            url.searchParams.set('pagesource', "library/functools.rst");1040            element.href = url.toString();1041        });1042    });1043  </script>1044  <div role="note" aria-label="source link">1045    <h3>This page</h3>1046    <ul class="this-page-menu">1047      <li><a href="../bugs.html">Report a bug</a></li>1048      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>1049      <li>1050        <a href="https://github.com/python/cpython/blob/main/Doc/library/functools.rst?plain=1"1051            rel="nofollow">Show source1052        </a>1053      </li>1054      1055    </ul>1056  </div>1057        </div>1058<div id="sidebarbutton" title="Collapse sidebar">1059<span>«</span>1060</div>1061 1062      </div>1063      <div class="clearer"></div>1064    </div>  1065    <div class="related" role="navigation" aria-label="Related">1066      <h3>Navigation</h3>1067      <ul>1068        <li class="right" style="margin-right: 10px">1069          <a href="../genindex.html" title="General Index"1070             >index</a></li>1071        <li class="right" >1072          <a href="../py-modindex.html" title="Python Module Index"1073             >modules</a> |</li>1074        <li class="right" >1075          <a href="operator.html" title="operator — Standard operators as functions"1076             >next</a> |</li>1077        <li class="right" >1078          <a href="itertools.html" title="itertools — Functions creating iterators for efficient looping"1079             >previous</a> |</li>1080 1081          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>1082          <li><a href="https://www.python.org/">Python</a> &#187;</li>1083          <li class="switchers">1084            <div class="language_switcher_placeholder"></div>1085            <div class="version_switcher_placeholder"></div>1086          </li>1087          <li>1088              1089          </li>1090    <li id="cpython-language-and-version">1091      <a href="../index.html">3.15.0a6 Documentation</a> &#187;1092    </li>1093 1094          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>1095          <li class="nav-item nav-item-2"><a href="functional.html" >Functional Programming Modules</a> &#187;</li>1096        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> — Higher-order functions and operations on callable objects</a></li>1097                <li class="right">1098                    1099 1100    <div class="inline-search" role="search">1101        <form class="inline-search" action="../search.html" method="get">1102          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">1103          <input type="submit" value="Go">1104        </form>1105    </div>1106                     |1107                </li>1108            <li class="right">1109<label class="theme-selector-label">1110    Theme1111    <select class="theme-selector" oninput="activateTheme(this.value)">1112        <option value="auto" selected>Auto</option>1113        <option value="light">Light</option>1114        <option value="dark">Dark</option>1115    </select>1116</label> |</li>1117            1118      </ul>1119    </div>  1120    <div class="footer">1121    &copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.1122    <br>1123    This page is licensed under the Python Software Foundation License Version 2.1124    <br>1125    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.1126    <br>1127    1128      See <a href="/license.html">History and License</a> for more information.<br>1129    1130    1131    <br>1132 1133    The Python Software Foundation is a non-profit corporation.1134<a href="https://www.python.org/psf/donations/">Please donate.</a>1135<br>1136    <br>1137      Last updated on Mar 10, 2026 (08:58 UTC).1138    1139      <a href="/bugs.html">Found a bug</a>?1140    1141    <br>1142 1143    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.1144    </div>1145 1146  </body>1147</html>