Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Vērot 1
Pievienot zvaigznīti 0
Vikivietne 捐赠
gooderp18绿色标准版
Nevar pievienot vairāk kā 25 tēmas Tēmai ir jāsākas ar burtu vai ciparu, tā var saturēt domu zīmes ('-') un var būt līdz 35 simboliem gara.
Atzars: master
Atzari Tagi
${ item.name }
Izveidot atzaru ${ searchTerm }
no 'master'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/howto/descriptor.html

1645 rindas
166KB
Neapstrādāts Patstāvīgā saite Vainot Vēsture 

  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="Descriptor Guide" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/howto/descriptor.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Author, Raymond Hettinger,, Contact,<python at rcn dot com>,. Contents: Descriptor Guide- Primer- Simple example: A descriptor that returns a constant, Dynamic lookups, Managed attributes, Customiz..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Author, Raymond Hettinger,, Contact,<python at rcn dot com>,. Contents: Descriptor Guide- Primer- Simple example: A descriptor that returns a constant, Dynamic lookups, Managed attributes, Customiz..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>Descriptor Guide &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="Debugging C API extensions and CPython Internals with GDB" href="gdb_helpers.html" />

  39.     <link rel="prev" title="Curses Programming with Python" href="curses.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/howto/descriptor.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#">Descriptor Guide</a><ul>

  99. <li><a class="reference internal" href="#primer">Primer</a><ul>

  100. <li><a class="reference internal" href="#simple-example-a-descriptor-that-returns-a-constant">Simple example: A descriptor that returns a constant</a></li>

  101. <li><a class="reference internal" href="#dynamic-lookups">Dynamic lookups</a></li>

  102. <li><a class="reference internal" href="#managed-attributes">Managed attributes</a></li>

  103. <li><a class="reference internal" href="#customized-names">Customized names</a></li>

  104. <li><a class="reference internal" href="#closing-thoughts">Closing thoughts</a></li>

  105. </ul>

  106. </li>

  107. <li><a class="reference internal" href="#complete-practical-example">Complete Practical Example</a><ul>

  108. <li><a class="reference internal" href="#validator-class">Validator class</a></li>

  109. <li><a class="reference internal" href="#custom-validators">Custom validators</a></li>

  110. <li><a class="reference internal" href="#practical-application">Practical application</a></li>

  111. </ul>

  112. </li>

  113. <li><a class="reference internal" href="#technical-tutorial">Technical Tutorial</a><ul>

  114. <li><a class="reference internal" href="#abstract">Abstract</a></li>

  115. <li><a class="reference internal" href="#definition-and-introduction">Definition and introduction</a></li>

  116. <li><a class="reference internal" href="#descriptor-protocol">Descriptor protocol</a></li>

  117. <li><a class="reference internal" href="#overview-of-descriptor-invocation">Overview of descriptor invocation</a></li>

  118. <li><a class="reference internal" href="#invocation-from-an-instance">Invocation from an instance</a></li>

  119. <li><a class="reference internal" href="#invocation-from-a-class">Invocation from a class</a></li>

  120. <li><a class="reference internal" href="#invocation-from-super">Invocation from super</a></li>

  121. <li><a class="reference internal" href="#summary-of-invocation-logic">Summary of invocation logic</a></li>

  122. <li><a class="reference internal" href="#automatic-name-notification">Automatic name notification</a></li>

  123. <li><a class="reference internal" href="#orm-example">ORM example</a></li>

  124. </ul>

  125. </li>

  126. <li><a class="reference internal" href="#pure-python-equivalents">Pure Python Equivalents</a><ul>

  127. <li><a class="reference internal" href="#properties">Properties</a></li>

  128. <li><a class="reference internal" href="#functions-and-methods">Functions and methods</a></li>

  129. <li><a class="reference internal" href="#kinds-of-methods">Kinds of methods</a></li>

  130. <li><a class="reference internal" href="#static-methods">Static methods</a></li>

  131. <li><a class="reference internal" href="#class-methods">Class methods</a></li>

  132. <li><a class="reference internal" href="#member-objects-and-slots">Member objects and __slots__</a></li>

  133. </ul>

  134. </li>

  135. </ul>

  136. </li>

  137. </ul>

  138. 

  139.   </div>

  140.   <div>

  141.     <h4>Previous topic</h4>

  142.     <p class="topless"><a href="curses.html"

  143.                           title="previous chapter">Curses Programming with Python</a></p>

  144.   </div>

  145.   <div>

  146.     <h4>Next topic</h4>

  147.     <p class="topless"><a href="gdb_helpers.html"

  148.                           title="next chapter">Debugging C API extensions and CPython Internals with GDB</a></p>

  149.   </div>

  150.   <div role="note" aria-label="source link">

  151.     <h3>This Page</h3>

  152.     <ul class="this-page-menu">

  153.       <li><a href="../bugs.html">Report a Bug</a></li>

  154.       <li>

  155.         <a href="https://github.com/python/cpython/blob/main/Doc/howto/descriptor.rst"

  156.             rel="nofollow">Show Source

  157.         </a>

  158.       </li>

  159.     </ul>

  160.   </div>

  161.         </nav>

  162.     </div>

  163. </div>

  164. 

  165.   

  166.     <div class="related" role="navigation" aria-label="related navigation">

  167.       <h3>Navigation</h3>

  168.       <ul>

  169.         <li class="right" style="margin-right: 10px">

  170.           <a href="../genindex.html" title="General Index"

  171.              accesskey="I">index</a></li>

  172.         <li class="right" >

  173.           <a href="../py-modindex.html" title="Python Module Index"

  174.              >modules</a> |</li>

  175.         <li class="right" >

  176.           <a href="gdb_helpers.html" title="Debugging C API extensions and CPython Internals with GDB"

  177.              accesskey="N">next</a> |</li>

  178.         <li class="right" >

  179.           <a href="curses.html" title="Curses Programming with Python"

  180.              accesskey="P">previous</a> |</li>

  181. 

  182.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  183.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  184.           <li class="switchers">

  185.             <div class="language_switcher_placeholder"></div>

  186.             <div class="version_switcher_placeholder"></div>

  187.           </li>

  188.           <li>

  189.               

  190.           </li>

  191.     <li id="cpython-language-and-version">

  192.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  193.     </li>

  194. 

  195.           <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python HOWTOs</a> &#187;</li>

  196.         <li class="nav-item nav-item-this"><a href="">Descriptor Guide</a></li>

  197.                 <li class="right">

  198.                     

  199. 

  200.     <div class="inline-search" role="search">

  201.         <form class="inline-search" action="../search.html" method="get">

  202.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  203.           <input type="submit" value="Go" />

  204.         </form>

  205.     </div>

  206.                      |

  207.                 </li>

  208.             <li class="right">

  209. <label class="theme-selector-label">

  210.     Theme

  211.     <select class="theme-selector" oninput="activateTheme(this.value)">

  212.         <option value="auto" selected>Auto</option>

  213.         <option value="light">Light</option>

  214.         <option value="dark">Dark</option>

  215.     </select>

  216. </label> |</li>

  217.             

  218.       </ul>

  219.     </div>    

  220. 

  221.     <div class="document">

  222.       <div class="documentwrapper">

  223.         <div class="bodywrapper">

  224.           <div class="body" role="main">

  225.             

  226.   <section id="descriptor-guide">

  227. <span id="descriptorhowto"></span><h1><a class="toc-backref" href="#id1" role="doc-backlink">Descriptor Guide</a><a class="headerlink" href="#descriptor-guide" title="Link to this heading">¶</a></h1>

  228. <dl class="field-list simple">

  229. <dt class="field-odd">Author<span class="colon">:</span></dt>

  230. <dd class="field-odd"><p>Raymond Hettinger</p>

  231. </dd>

  232. <dt class="field-even">Contact<span class="colon">:</span></dt>

  233. <dd class="field-even"><p>&lt;python at rcn dot com&gt;</p>

  234. </dd>

  235. </dl>

  236. <nav class="contents" id="contents">

  237. <p class="topic-title">Contents</p>

  238. <ul class="simple">

  239. <li><p><a class="reference internal" href="#descriptor-guide" id="id1">Descriptor Guide</a></p>

  240. <ul>

  241. <li><p><a class="reference internal" href="#primer" id="id2">Primer</a></p>

  242. <ul>

  243. <li><p><a class="reference internal" href="#simple-example-a-descriptor-that-returns-a-constant" id="id3">Simple example: A descriptor that returns a constant</a></p></li>

  244. <li><p><a class="reference internal" href="#dynamic-lookups" id="id4">Dynamic lookups</a></p></li>

  245. <li><p><a class="reference internal" href="#managed-attributes" id="id5">Managed attributes</a></p></li>

  246. <li><p><a class="reference internal" href="#customized-names" id="id6">Customized names</a></p></li>

  247. <li><p><a class="reference internal" href="#closing-thoughts" id="id7">Closing thoughts</a></p></li>

  248. </ul>

  249. </li>

  250. <li><p><a class="reference internal" href="#complete-practical-example" id="id8">Complete Practical Example</a></p>

  251. <ul>

  252. <li><p><a class="reference internal" href="#validator-class" id="id9">Validator class</a></p></li>

  253. <li><p><a class="reference internal" href="#custom-validators" id="id10">Custom validators</a></p></li>

  254. <li><p><a class="reference internal" href="#practical-application" id="id11">Practical application</a></p></li>

  255. </ul>

  256. </li>

  257. <li><p><a class="reference internal" href="#technical-tutorial" id="id12">Technical Tutorial</a></p>

  258. <ul>

  259. <li><p><a class="reference internal" href="#abstract" id="id13">Abstract</a></p></li>

  260. <li><p><a class="reference internal" href="#definition-and-introduction" id="id14">Definition and introduction</a></p></li>

  261. <li><p><a class="reference internal" href="#descriptor-protocol" id="id15">Descriptor protocol</a></p></li>

  262. <li><p><a class="reference internal" href="#overview-of-descriptor-invocation" id="id16">Overview of descriptor invocation</a></p></li>

  263. <li><p><a class="reference internal" href="#invocation-from-an-instance" id="id17">Invocation from an instance</a></p></li>

  264. <li><p><a class="reference internal" href="#invocation-from-a-class" id="id18">Invocation from a class</a></p></li>

  265. <li><p><a class="reference internal" href="#invocation-from-super" id="id19">Invocation from super</a></p></li>

  266. <li><p><a class="reference internal" href="#summary-of-invocation-logic" id="id20">Summary of invocation logic</a></p></li>

  267. <li><p><a class="reference internal" href="#automatic-name-notification" id="id21">Automatic name notification</a></p></li>

  268. <li><p><a class="reference internal" href="#orm-example" id="id22">ORM example</a></p></li>

  269. </ul>

  270. </li>

  271. <li><p><a class="reference internal" href="#pure-python-equivalents" id="id23">Pure Python Equivalents</a></p>

  272. <ul>

  273. <li><p><a class="reference internal" href="#properties" id="id24">Properties</a></p></li>

  274. <li><p><a class="reference internal" href="#functions-and-methods" id="id25">Functions and methods</a></p></li>

  275. <li><p><a class="reference internal" href="#kinds-of-methods" id="id26">Kinds of methods</a></p></li>

  276. <li><p><a class="reference internal" href="#static-methods" id="id27">Static methods</a></p></li>

  277. <li><p><a class="reference internal" href="#class-methods" id="id28">Class methods</a></p></li>

  278. <li><p><a class="reference internal" href="#member-objects-and-slots" id="id29">Member objects and __slots__</a></p></li>

  279. </ul>

  280. </li>

  281. </ul>

  282. </li>

  283. </ul>

  284. </nav>

  285. <p><a class="reference internal" href="../glossary.html#term-descriptor"><span class="xref std std-term">Descriptors</span></a> let objects customize attribute lookup,

  286. storage, and deletion.</p>

  287. <p>This guide has four major sections:</p>

  288. <ol class="arabic simple">

  289. <li><p>The “primer” gives a basic overview, moving gently from simple examples,

  290. adding one feature at a time.  Start here if you’re new to descriptors.</p></li>

  291. <li><p>The second section shows a complete, practical descriptor example.  If you

  292. already know the basics, start there.</p></li>

  293. <li><p>The third section provides a more technical tutorial that goes into the

  294. detailed mechanics of how descriptors work.  Most people don’t need this

  295. level of detail.</p></li>

  296. <li><p>The last section has pure Python equivalents for built-in descriptors that

  297. are written in C.  Read this if you’re curious about how functions turn

  298. into bound methods or about the implementation of common tools like

  299. <a class="reference internal" href="../library/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="../library/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="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a>, and

  300. <a class="reference internal" href="../glossary.html#term-__slots__"><span class="xref std std-term">__slots__</span></a>.</p></li>

  301. </ol>

  302. <section id="primer">

  303. <h2><a class="toc-backref" href="#id2" role="doc-backlink">Primer</a><a class="headerlink" href="#primer" title="Link to this heading">¶</a></h2>

  304. <p>In this primer, we start with the most basic possible example and then we’ll

  305. add new capabilities one by one.</p>

  306. <section id="simple-example-a-descriptor-that-returns-a-constant">

  307. <h3><a class="toc-backref" href="#id3" role="doc-backlink">Simple example: A descriptor that returns a constant</a><a class="headerlink" href="#simple-example-a-descriptor-that-returns-a-constant" title="Link to this heading">¶</a></h3>

  308. <p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Ten</span></code> class is a descriptor whose <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> method always

  309. returns the constant <code class="docutils literal notranslate"><span class="pre">10</span></code>:</p>

  310. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Ten</span><span class="p">:</span>

  311.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  312.         <span class="k">return</span> <span class="mi">10</span>

  313. </pre></div>

  314. </div>

  315. <p>To use the descriptor, it must be stored as a class variable in another class:</p>

  316. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">A</span><span class="p">:</span>

  317.     <span class="n">x</span> <span class="o">=</span> <span class="mi">5</span>                       <span class="c1"># Regular class attribute</span>

  318.     <span class="n">y</span> <span class="o">=</span> <span class="n">Ten</span><span class="p">()</span>                   <span class="c1"># Descriptor instance</span>

  319. </pre></div>

  320. </div>

  321. <p>An interactive session shows the difference between normal attribute lookup

  322. and descriptor lookup:</p>

  323. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">A</span><span class="p">()</span>                     <span class="c1"># Make an instance of class A</span>

  324. <span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">.</span><span class="n">x</span>                         <span class="c1"># Normal attribute lookup</span>

  325. <span class="go">5</span>

  326. <span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">.</span><span class="n">y</span>                         <span class="c1"># Descriptor lookup</span>

  327. <span class="go">10</span>

  328. </pre></div>

  329. </div>

  330. <p>In the <code class="docutils literal notranslate"><span class="pre">a.x</span></code> attribute lookup, the dot operator finds <code class="docutils literal notranslate"><span class="pre">'x':</span> <span class="pre">5</span></code>

  331. in the class dictionary.  In the <code class="docutils literal notranslate"><span class="pre">a.y</span></code> lookup, the dot operator

  332. finds a descriptor instance, recognized by its <code class="docutils literal notranslate"><span class="pre">__get__</span></code> method.

  333. Calling that method returns <code class="docutils literal notranslate"><span class="pre">10</span></code>.</p>

  334. <p>Note that the value <code class="docutils literal notranslate"><span class="pre">10</span></code> is not stored in either the class dictionary or the

  335. instance dictionary.  Instead, the value <code class="docutils literal notranslate"><span class="pre">10</span></code> is computed on demand.</p>

  336. <p>This example shows how a simple descriptor works, but it isn’t very useful.

  337. For retrieving constants, normal attribute lookup would be better.</p>

  338. <p>In the next section, we’ll create something more useful, a dynamic lookup.</p>

  339. </section>

  340. <section id="dynamic-lookups">

  341. <h3><a class="toc-backref" href="#id4" role="doc-backlink">Dynamic lookups</a><a class="headerlink" href="#dynamic-lookups" title="Link to this heading">¶</a></h3>

  342. <p>Interesting descriptors typically run computations instead of returning

  343. constants:</p>

  344. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>

  345. 

  346. <span class="k">class</span> <span class="nc">DirectorySize</span><span class="p">:</span>

  347. 

  348.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  349.         <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">obj</span><span class="o">.</span><span class="n">dirname</span><span class="p">))</span>

  350. 

  351. <span class="k">class</span> <span class="nc">Directory</span><span class="p">:</span>

  352. 

  353.     <span class="n">size</span> <span class="o">=</span> <span class="n">DirectorySize</span><span class="p">()</span>              <span class="c1"># Descriptor instance</span>

  354. 

  355.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dirname</span><span class="p">):</span>

  356.         <span class="bp">self</span><span class="o">.</span><span class="n">dirname</span> <span class="o">=</span> <span class="n">dirname</span>          <span class="c1"># Regular instance attribute</span>

  357. </pre></div>

  358. </div>

  359. <p>An interactive session shows that the lookup is dynamic — it computes

  360. different, updated answers each time:</p>

  361. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">Directory</span><span class="p">(</span><span class="s1">&#39;songs&#39;</span><span class="p">)</span>

  362. <span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">Directory</span><span class="p">(</span><span class="s1">&#39;games&#39;</span><span class="p">)</span>

  363. <span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">size</span>                              <span class="c1"># The songs directory has twenty files</span>

  364. <span class="go">20</span>

  365. <span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">size</span>                              <span class="c1"># The games directory has three files</span>

  366. <span class="go">3</span>

  367. <span class="gp">&gt;&gt;&gt; </span><span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s1">&#39;games/chess&#39;</span><span class="p">)</span>            <span class="c1"># Delete a game</span>

  368. <span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">size</span>                              <span class="c1"># File count is automatically updated</span>

  369. <span class="go">2</span>

  370. </pre></div>

  371. </div>

  372. <p>Besides showing how descriptors can run computations, this example also

  373. reveals the purpose of the parameters to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code>.  The <em>self</em>

  374. parameter is <em>size</em>, an instance of <em>DirectorySize</em>.  The <em>obj</em> parameter is

  375. either <em>g</em> or <em>s</em>, an instance of <em>Directory</em>.  It is the <em>obj</em> parameter that

  376. lets the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> method learn the target directory.  The <em>objtype</em>

  377. parameter is the class <em>Directory</em>.</p>

  378. </section>

  379. <section id="managed-attributes">

  380. <h3><a class="toc-backref" href="#id5" role="doc-backlink">Managed attributes</a><a class="headerlink" href="#managed-attributes" title="Link to this heading">¶</a></h3>

  381. <p>A popular use for descriptors is managing access to instance data.  The

  382. descriptor is assigned to a public attribute in the class dictionary while the

  383. actual data is stored as a private attribute in the instance dictionary.  The

  384. descriptor’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code> methods are triggered when

  385. the public attribute is accessed.</p>

  386. <p>In the following example, <em>age</em> is the public attribute and <em>_age</em> is the

  387. private attribute.  When the public attribute is accessed, the descriptor logs

  388. the lookup or update:</p>

  389. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  390. 

  391. <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>

  392. 

  393. <span class="k">class</span> <span class="nc">LoggedAgeAccess</span><span class="p">:</span>

  394. 

  395.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  396.         <span class="n">value</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">_age</span>

  397.         <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Accessing </span><span class="si">%r</span><span class="s1"> giving </span><span class="si">%r</span><span class="s1">&#39;</span><span class="p">,</span> <span class="s1">&#39;age&#39;</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  398.         <span class="k">return</span> <span class="n">value</span>

  399. 

  400.     <span class="k">def</span> <span class="fm">__set__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  401.         <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Updating </span><span class="si">%r</span><span class="s1"> to </span><span class="si">%r</span><span class="s1">&#39;</span><span class="p">,</span> <span class="s1">&#39;age&#39;</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  402.         <span class="n">obj</span><span class="o">.</span><span class="n">_age</span> <span class="o">=</span> <span class="n">value</span>

  403. 

  404. <span class="k">class</span> <span class="nc">Person</span><span class="p">:</span>

  405. 

  406.     <span class="n">age</span> <span class="o">=</span> <span class="n">LoggedAgeAccess</span><span class="p">()</span>             <span class="c1"># Descriptor instance</span>

  407. 

  408.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">age</span><span class="p">):</span>

  409.         <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>                <span class="c1"># Regular instance attribute</span>

  410.         <span class="bp">self</span><span class="o">.</span><span class="n">age</span> <span class="o">=</span> <span class="n">age</span>                  <span class="c1"># Calls __set__()</span>

  411. 

  412.     <span class="k">def</span> <span class="nf">birthday</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  413.         <span class="bp">self</span><span class="o">.</span><span class="n">age</span> <span class="o">+=</span> <span class="mi">1</span>                   <span class="c1"># Calls both __get__() and __set__()</span>

  414. </pre></div>

  415. </div>

  416. <p>An interactive session shows that all access to the managed attribute <em>age</em> is

  417. logged, but that the regular attribute <em>name</em> is not logged:</p>

  418. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mary</span> <span class="o">=</span> <span class="n">Person</span><span class="p">(</span><span class="s1">&#39;Mary M&#39;</span><span class="p">,</span> <span class="mi">30</span><span class="p">)</span>         <span class="c1"># The initial age update is logged</span>

  419. <span class="go">INFO:root:Updating &#39;age&#39; to 30</span>

  420. <span class="gp">&gt;&gt;&gt; </span><span class="n">dave</span> <span class="o">=</span> <span class="n">Person</span><span class="p">(</span><span class="s1">&#39;David D&#39;</span><span class="p">,</span> <span class="mi">40</span><span class="p">)</span>

  421. <span class="go">INFO:root:Updating &#39;age&#39; to 40</span>

  422. 

  423. <span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="n">mary</span><span class="p">)</span>                          <span class="c1"># The actual data is in a private attribute</span>

  424. <span class="go">{&#39;name&#39;: &#39;Mary M&#39;, &#39;_age&#39;: 30}</span>

  425. <span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="n">dave</span><span class="p">)</span>

  426. <span class="go">{&#39;name&#39;: &#39;David D&#39;, &#39;_age&#39;: 40}</span>

  427. 

  428. <span class="gp">&gt;&gt;&gt; </span><span class="n">mary</span><span class="o">.</span><span class="n">age</span>                            <span class="c1"># Access the data and log the lookup</span>

  429. <span class="go">INFO:root:Accessing &#39;age&#39; giving 30</span>

  430. <span class="go">30</span>

  431. <span class="gp">&gt;&gt;&gt; </span><span class="n">mary</span><span class="o">.</span><span class="n">birthday</span><span class="p">()</span>                     <span class="c1"># Updates are logged as well</span>

  432. <span class="go">INFO:root:Accessing &#39;age&#39; giving 30</span>

  433. <span class="go">INFO:root:Updating &#39;age&#39; to 31</span>

  434. 

  435. <span class="gp">&gt;&gt;&gt; </span><span class="n">dave</span><span class="o">.</span><span class="n">name</span>                           <span class="c1"># Regular attribute lookup isn&#39;t logged</span>

  436. <span class="go">&#39;David D&#39;</span>

  437. <span class="gp">&gt;&gt;&gt; </span><span class="n">dave</span><span class="o">.</span><span class="n">age</span>                            <span class="c1"># Only the managed attribute is logged</span>

  438. <span class="go">INFO:root:Accessing &#39;age&#39; giving 40</span>

  439. <span class="go">40</span>

  440. </pre></div>

  441. </div>

  442. <p>One major issue with this example is that the private name <em>_age</em> is hardwired in

  443. the <em>LoggedAgeAccess</em> class.  That means that each instance can only have one

  444. logged attribute and that its name is unchangeable.  In the next example,

  445. we’ll fix that problem.</p>

  446. </section>

  447. <section id="customized-names">

  448. <h3><a class="toc-backref" href="#id6" role="doc-backlink">Customized names</a><a class="headerlink" href="#customized-names" title="Link to this heading">¶</a></h3>

  449. <p>When a class uses descriptors, it can inform each descriptor about which

  450. variable name was used.</p>

  451. <p>In this example, the <code class="xref py py-class docutils literal notranslate"><span class="pre">Person</span></code> class has two descriptor instances,

  452. <em>name</em> and <em>age</em>.  When the <code class="xref py py-class docutils literal notranslate"><span class="pre">Person</span></code> class is defined, it makes a

  453. callback to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code> in <em>LoggedAccess</em> so that the field names can

  454. be recorded, giving each descriptor its own <em>public_name</em> and <em>private_name</em>:</p>

  455. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  456. 

  457. <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>

  458. 

  459. <span class="k">class</span> <span class="nc">LoggedAccess</span><span class="p">:</span>

  460. 

  461.     <span class="k">def</span> <span class="nf">__set_name__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  462.         <span class="bp">self</span><span class="o">.</span><span class="n">public_name</span> <span class="o">=</span> <span class="n">name</span>

  463.         <span class="bp">self</span><span class="o">.</span><span class="n">private_name</span> <span class="o">=</span> <span class="s1">&#39;_&#39;</span> <span class="o">+</span> <span class="n">name</span>

  464. 

  465.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  466.         <span class="n">value</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">private_name</span><span class="p">)</span>

  467.         <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Accessing </span><span class="si">%r</span><span class="s1"> giving </span><span class="si">%r</span><span class="s1">&#39;</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">public_name</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  468.         <span class="k">return</span> <span class="n">value</span>

  469. 

  470.     <span class="k">def</span> <span class="fm">__set__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  471.         <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Updating </span><span class="si">%r</span><span class="s1"> to </span><span class="si">%r</span><span class="s1">&#39;</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">public_name</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  472.         <span class="nb">setattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">private_name</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  473. 

  474. <span class="k">class</span> <span class="nc">Person</span><span class="p">:</span>

  475. 

  476.     <span class="n">name</span> <span class="o">=</span> <span class="n">LoggedAccess</span><span class="p">()</span>                <span class="c1"># First descriptor instance</span>

  477.     <span class="n">age</span> <span class="o">=</span> <span class="n">LoggedAccess</span><span class="p">()</span>                 <span class="c1"># Second descriptor instance</span>

  478. 

  479.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">age</span><span class="p">):</span>

  480.         <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>                 <span class="c1"># Calls the first descriptor</span>

  481.         <span class="bp">self</span><span class="o">.</span><span class="n">age</span> <span class="o">=</span> <span class="n">age</span>                   <span class="c1"># Calls the second descriptor</span>

  482. 

  483.     <span class="k">def</span> <span class="nf">birthday</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  484.         <span class="bp">self</span><span class="o">.</span><span class="n">age</span> <span class="o">+=</span> <span class="mi">1</span>

  485. </pre></div>

  486. </div>

  487. <p>An interactive session shows that the <code class="xref py py-class docutils literal notranslate"><span class="pre">Person</span></code> class has called

  488. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code> so that the field names would be recorded.  Here

  489. we call <a class="reference internal" href="../library/functions.html#vars" title="vars"><code class="xref py py-func docutils literal notranslate"><span class="pre">vars()</span></code></a> to look up the descriptor without triggering it:</p>

  490. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="nb">vars</span><span class="p">(</span><span class="n">Person</span><span class="p">)[</span><span class="s1">&#39;name&#39;</span><span class="p">])</span>

  491. <span class="go">{&#39;public_name&#39;: &#39;name&#39;, &#39;private_name&#39;: &#39;_name&#39;}</span>

  492. <span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="nb">vars</span><span class="p">(</span><span class="n">Person</span><span class="p">)[</span><span class="s1">&#39;age&#39;</span><span class="p">])</span>

  493. <span class="go">{&#39;public_name&#39;: &#39;age&#39;, &#39;private_name&#39;: &#39;_age&#39;}</span>

  494. </pre></div>

  495. </div>

  496. <p>The new class now logs access to both <em>name</em> and <em>age</em>:</p>

  497. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">pete</span> <span class="o">=</span> <span class="n">Person</span><span class="p">(</span><span class="s1">&#39;Peter P&#39;</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>

  498. <span class="go">INFO:root:Updating &#39;name&#39; to &#39;Peter P&#39;</span>

  499. <span class="go">INFO:root:Updating &#39;age&#39; to 10</span>

  500. <span class="gp">&gt;&gt;&gt; </span><span class="n">kate</span> <span class="o">=</span> <span class="n">Person</span><span class="p">(</span><span class="s1">&#39;Catherine C&#39;</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>

  501. <span class="go">INFO:root:Updating &#39;name&#39; to &#39;Catherine C&#39;</span>

  502. <span class="go">INFO:root:Updating &#39;age&#39; to 20</span>

  503. </pre></div>

  504. </div>

  505. <p>The two <em>Person</em> instances contain only the private names:</p>

  506. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="n">pete</span><span class="p">)</span>

  507. <span class="go">{&#39;_name&#39;: &#39;Peter P&#39;, &#39;_age&#39;: 10}</span>

  508. <span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="n">kate</span><span class="p">)</span>

  509. <span class="go">{&#39;_name&#39;: &#39;Catherine C&#39;, &#39;_age&#39;: 20}</span>

  510. </pre></div>

  511. </div>

  512. </section>

  513. <section id="closing-thoughts">

  514. <h3><a class="toc-backref" href="#id7" role="doc-backlink">Closing thoughts</a><a class="headerlink" href="#closing-thoughts" title="Link to this heading">¶</a></h3>

  515. <p>A <a class="reference internal" href="../glossary.html#term-descriptor"><span class="xref std std-term">descriptor</span></a> is what we call any object that defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code>,

  516. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code>, or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code>.</p>

  517. <p>Optionally, descriptors can have a <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code> method.  This is only

  518. used in cases where a descriptor needs to know either the class where it was

  519. created or the name of class variable it was assigned to.  (This method, if

  520. present, is called even if the class is not a descriptor.)</p>

  521. <p>Descriptors get invoked by the dot operator during attribute lookup.  If a

  522. descriptor is accessed indirectly with <code class="docutils literal notranslate"><span class="pre">vars(some_class)[descriptor_name]</span></code>,

  523. the descriptor instance is returned without invoking it.</p>

  524. <p>Descriptors only work when used as class variables.  When put in instances,

  525. they have no effect.</p>

  526. <p>The main motivation for descriptors is to provide a hook allowing objects

  527. stored in class variables to control what happens during attribute lookup.</p>

  528. <p>Traditionally, the calling class controls what happens during lookup.

  529. Descriptors invert that relationship and allow the data being looked-up to

  530. have a say in the matter.</p>

  531. <p>Descriptors are used throughout the language.  It is how functions turn into

  532. bound methods.  Common tools like <a class="reference internal" href="../library/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="../library/functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a>,

  533. <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a>, and <a class="reference internal" href="../library/functools.html#functools.cached_property" title="functools.cached_property"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.cached_property()</span></code></a> are all implemented as

  534. descriptors.</p>

  535. </section>

  536. </section>

  537. <section id="complete-practical-example">

  538. <h2><a class="toc-backref" href="#id8" role="doc-backlink">Complete Practical Example</a><a class="headerlink" href="#complete-practical-example" title="Link to this heading">¶</a></h2>

  539. <p>In this example, we create a practical and powerful tool for locating

  540. notoriously hard to find data corruption bugs.</p>

  541. <section id="validator-class">

  542. <h3><a class="toc-backref" href="#id9" role="doc-backlink">Validator class</a><a class="headerlink" href="#validator-class" title="Link to this heading">¶</a></h3>

  543. <p>A validator is a descriptor for managed attribute access.  Prior to storing

  544. any data, it verifies that the new value meets various type and range

  545. restrictions.  If those restrictions aren’t met, it raises an exception to

  546. prevent data corruption at its source.</p>

  547. <p>This <code class="xref py py-class docutils literal notranslate"><span class="pre">Validator</span></code> class is both an <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a> and a

  548. managed attribute descriptor:</p>

  549. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">abc</span> <span class="kn">import</span> <span class="n">ABC</span><span class="p">,</span> <span class="n">abstractmethod</span>

  550. 

  551. <span class="k">class</span> <span class="nc">Validator</span><span class="p">(</span><span class="n">ABC</span><span class="p">):</span>

  552. 

  553.     <span class="k">def</span> <span class="nf">__set_name__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  554.         <span class="bp">self</span><span class="o">.</span><span class="n">private_name</span> <span class="o">=</span> <span class="s1">&#39;_&#39;</span> <span class="o">+</span> <span class="n">name</span>

  555. 

  556.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  557.         <span class="k">return</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">private_name</span><span class="p">)</span>

  558. 

  559.     <span class="k">def</span> <span class="fm">__set__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  560.         <span class="bp">self</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>

  561.         <span class="nb">setattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">private_name</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  562. 

  563.     <span class="nd">@abstractmethod</span>

  564.     <span class="k">def</span> <span class="nf">validate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  565.         <span class="k">pass</span>

  566. </pre></div>

  567. </div>

  568. <p>Custom validators need to inherit from <code class="xref py py-class docutils literal notranslate"><span class="pre">Validator</span></code> and must supply a

  569. <code class="xref py py-meth docutils literal notranslate"><span class="pre">validate()</span></code> method to test various restrictions as needed.</p>

  570. </section>

  571. <section id="custom-validators">

  572. <h3><a class="toc-backref" href="#id10" role="doc-backlink">Custom validators</a><a class="headerlink" href="#custom-validators" title="Link to this heading">¶</a></h3>

  573. <p>Here are three practical data validation utilities:</p>

  574. <ol class="arabic simple">

  575. <li><p><code class="xref py py-class docutils literal notranslate"><span class="pre">OneOf</span></code> verifies that a value is one of a restricted set of options.</p></li>

  576. <li><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Number</span></code> verifies that a value is either an <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> or

  577. <a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>.  Optionally, it verifies that a value is between a given

  578. minimum or maximum.</p></li>

  579. <li><p><code class="xref py py-class docutils literal notranslate"><span class="pre">String</span></code> verifies that a value is a <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>.  Optionally, it

  580. validates a given minimum or maximum length.  It can validate a

  581. user-defined <a class="reference external" href="https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)">predicate</a> as well.</p></li>

  582. </ol>

  583. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">OneOf</span><span class="p">(</span><span class="n">Validator</span><span class="p">):</span>

  584. 

  585.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">options</span><span class="p">):</span>

  586.         <span class="bp">self</span><span class="o">.</span><span class="n">options</span> <span class="o">=</span> <span class="nb">set</span><span class="p">(</span><span class="n">options</span><span class="p">)</span>

  587. 

  588.     <span class="k">def</span> <span class="nf">validate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  589.         <span class="k">if</span> <span class="n">value</span> <span class="ow">not</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">options</span><span class="p">:</span>

  590.             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Expected </span><span class="si">{</span><span class="n">value</span><span class="si">!r}</span><span class="s1"> to be one of </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">options</span><span class="si">!r}</span><span class="s1">&#39;</span><span class="p">)</span>

  591. 

  592. <span class="k">class</span> <span class="nc">Number</span><span class="p">(</span><span class="n">Validator</span><span class="p">):</span>

  593. 

  594.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">minvalue</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">maxvalue</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  595.         <span class="bp">self</span><span class="o">.</span><span class="n">minvalue</span> <span class="o">=</span> <span class="n">minvalue</span>

  596.         <span class="bp">self</span><span class="o">.</span><span class="n">maxvalue</span> <span class="o">=</span> <span class="n">maxvalue</span>

  597. 

  598.     <span class="k">def</span> <span class="nf">validate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  599.         <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="nb">float</span><span class="p">)):</span>

  600.             <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Expected </span><span class="si">{</span><span class="n">value</span><span class="si">!r}</span><span class="s1"> to be an int or float&#39;</span><span class="p">)</span>

  601.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">minvalue</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">value</span> <span class="o">&lt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">minvalue</span><span class="p">:</span>

  602.             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>

  603.                 <span class="sa">f</span><span class="s1">&#39;Expected </span><span class="si">{</span><span class="n">value</span><span class="si">!r}</span><span class="s1"> to be at least </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">minvalue</span><span class="si">!r}</span><span class="s1">&#39;</span>

  604.             <span class="p">)</span>

  605.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">maxvalue</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">value</span> <span class="o">&gt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">maxvalue</span><span class="p">:</span>

  606.             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>

  607.                 <span class="sa">f</span><span class="s1">&#39;Expected </span><span class="si">{</span><span class="n">value</span><span class="si">!r}</span><span class="s1"> to be no more than </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">maxvalue</span><span class="si">!r}</span><span class="s1">&#39;</span>

  608.             <span class="p">)</span>

  609. 

  610. <span class="k">class</span> <span class="nc">String</span><span class="p">(</span><span class="n">Validator</span><span class="p">):</span>

  611. 

  612.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">minsize</span><span class="o">=</span><span class="kc">None</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">predicate</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  613.         <span class="bp">self</span><span class="o">.</span><span class="n">minsize</span> <span class="o">=</span> <span class="n">minsize</span>

  614.         <span class="bp">self</span><span class="o">.</span><span class="n">maxsize</span> <span class="o">=</span> <span class="n">maxsize</span>

  615.         <span class="bp">self</span><span class="o">.</span><span class="n">predicate</span> <span class="o">=</span> <span class="n">predicate</span>

  616. 

  617.     <span class="k">def</span> <span class="nf">validate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  618.         <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>

  619.             <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Expected </span><span class="si">{</span><span class="n">value</span><span class="si">!r}</span><span class="s1"> to be an str&#39;</span><span class="p">)</span>

  620.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">minsize</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">&lt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">minsize</span><span class="p">:</span>

  621.             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>

  622.                 <span class="sa">f</span><span class="s1">&#39;Expected </span><span class="si">{</span><span class="n">value</span><span class="si">!r}</span><span class="s1"> to be no smaller than </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">minsize</span><span class="si">!r}</span><span class="s1">&#39;</span>

  623.             <span class="p">)</span>

  624.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">maxsize</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">&gt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">maxsize</span><span class="p">:</span>

  625.             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>

  626.                 <span class="sa">f</span><span class="s1">&#39;Expected </span><span class="si">{</span><span class="n">value</span><span class="si">!r}</span><span class="s1"> to be no bigger than </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">maxsize</span><span class="si">!r}</span><span class="s1">&#39;</span>

  627.             <span class="p">)</span>

  628.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">predicate</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">predicate</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>

  629.             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>

  630.                 <span class="sa">f</span><span class="s1">&#39;Expected </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">predicate</span><span class="si">}</span><span class="s1"> to be true for </span><span class="si">{</span><span class="n">value</span><span class="si">!r}</span><span class="s1">&#39;</span>

  631.             <span class="p">)</span>

  632. </pre></div>

  633. </div>

  634. </section>

  635. <section id="practical-application">

  636. <h3><a class="toc-backref" href="#id11" role="doc-backlink">Practical application</a><a class="headerlink" href="#practical-application" title="Link to this heading">¶</a></h3>

  637. <p>Here’s how the data validators can be used in a real class:</p>

  638. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Component</span><span class="p">:</span>

  639. 

  640.     <span class="n">name</span> <span class="o">=</span> <span class="n">String</span><span class="p">(</span><span class="n">minsize</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">maxsize</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">predicate</span><span class="o">=</span><span class="nb">str</span><span class="o">.</span><span class="n">isupper</span><span class="p">)</span>

  641.     <span class="n">kind</span> <span class="o">=</span> <span class="n">OneOf</span><span class="p">(</span><span class="s1">&#39;wood&#39;</span><span class="p">,</span> <span class="s1">&#39;metal&#39;</span><span class="p">,</span> <span class="s1">&#39;plastic&#39;</span><span class="p">)</span>

  642.     <span class="n">quantity</span> <span class="o">=</span> <span class="n">Number</span><span class="p">(</span><span class="n">minvalue</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>

  643. 

  644.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">kind</span><span class="p">,</span> <span class="n">quantity</span><span class="p">):</span>

  645.         <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

  646.         <span class="bp">self</span><span class="o">.</span><span class="n">kind</span> <span class="o">=</span> <span class="n">kind</span>

  647.         <span class="bp">self</span><span class="o">.</span><span class="n">quantity</span> <span class="o">=</span> <span class="n">quantity</span>

  648. </pre></div>

  649. </div>

  650. <p>The descriptors prevent invalid instances from being created:</p>

  651. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Component</span><span class="p">(</span><span class="s1">&#39;Widget&#39;</span><span class="p">,</span> <span class="s1">&#39;metal&#39;</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>      <span class="c1"># Blocked: &#39;Widget&#39; is not all uppercase</span>

  652. <span class="gt">Traceback (most recent call last):</span>

  653. <span class="w">    </span><span class="o">...</span>

  654. <span class="gr">ValueError</span>: <span class="n">Expected &lt;method &#39;isupper&#39; of &#39;str&#39; objects&gt; to be true for &#39;Widget&#39;</span>

  655. 

  656. <span class="gp">&gt;&gt;&gt; </span><span class="n">Component</span><span class="p">(</span><span class="s1">&#39;WIDGET&#39;</span><span class="p">,</span> <span class="s1">&#39;metle&#39;</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>      <span class="c1"># Blocked: &#39;metle&#39; is misspelled</span>

  657. <span class="gt">Traceback (most recent call last):</span>

  658. <span class="w">    </span><span class="o">...</span>

  659. <span class="gr">ValueError</span>: <span class="n">Expected &#39;metle&#39; to be one of {&#39;metal&#39;, &#39;plastic&#39;, &#39;wood&#39;}</span>

  660. 

  661. <span class="gp">&gt;&gt;&gt; </span><span class="n">Component</span><span class="p">(</span><span class="s1">&#39;WIDGET&#39;</span><span class="p">,</span> <span class="s1">&#39;metal&#39;</span><span class="p">,</span> <span class="o">-</span><span class="mi">5</span><span class="p">)</span>     <span class="c1"># Blocked: -5 is negative</span>

  662. <span class="gt">Traceback (most recent call last):</span>

  663. <span class="w">    </span><span class="o">...</span>

  664. <span class="gr">ValueError</span>: <span class="n">Expected -5 to be at least 0</span>

  665. <span class="gp">&gt;&gt;&gt; </span><span class="n">Component</span><span class="p">(</span><span class="s1">&#39;WIDGET&#39;</span><span class="p">,</span> <span class="s1">&#39;metal&#39;</span><span class="p">,</span> <span class="s1">&#39;V&#39;</span><span class="p">)</span>    <span class="c1"># Blocked: &#39;V&#39; isn&#39;t a number</span>

  666. <span class="gt">Traceback (most recent call last):</span>

  667. <span class="w">    </span><span class="o">...</span>

  668. <span class="gr">TypeError</span>: <span class="n">Expected &#39;V&#39; to be an int or float</span>

  669. 

  670. <span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Component</span><span class="p">(</span><span class="s1">&#39;WIDGET&#39;</span><span class="p">,</span> <span class="s1">&#39;metal&#39;</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>  <span class="c1"># Allowed:  The inputs are valid</span>

  671. </pre></div>

  672. </div>

  673. </section>

  674. </section>

  675. <section id="technical-tutorial">

  676. <h2><a class="toc-backref" href="#id12" role="doc-backlink">Technical Tutorial</a><a class="headerlink" href="#technical-tutorial" title="Link to this heading">¶</a></h2>

  677. <p>What follows is a more technical tutorial for the mechanics and details of how

  678. descriptors work.</p>

  679. <section id="abstract">

  680. <h3><a class="toc-backref" href="#id13" role="doc-backlink">Abstract</a><a class="headerlink" href="#abstract" title="Link to this heading">¶</a></h3>

  681. <p>Defines descriptors, summarizes the protocol, and shows how descriptors are

  682. called.  Provides an example showing how object relational mappings work.</p>

  683. <p>Learning about descriptors not only provides access to a larger toolset, it

  684. creates a deeper understanding of how Python works.</p>

  685. </section>

  686. <section id="definition-and-introduction">

  687. <h3><a class="toc-backref" href="#id14" role="doc-backlink">Definition and introduction</a><a class="headerlink" href="#definition-and-introduction" title="Link to this heading">¶</a></h3>

  688. <p>In general, a descriptor is an attribute value that has one of the methods in

  689. the descriptor protocol.  Those methods are <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code>,

  690. and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code>.  If any of those methods are defined for an

  691. attribute, it is said to be a <a class="reference internal" href="../glossary.html#term-descriptor"><span class="xref std std-term">descriptor</span></a>.</p>

  692. <p>The default behavior for attribute access is to get, set, or delete the

  693. attribute from an object’s dictionary.  For instance, <code class="docutils literal notranslate"><span class="pre">a.x</span></code> has a lookup chain

  694. starting with <code class="docutils literal notranslate"><span class="pre">a.__dict__['x']</span></code>, then <code class="docutils literal notranslate"><span class="pre">type(a).__dict__['x']</span></code>, and

  695. continuing through the method resolution order of <code class="docutils literal notranslate"><span class="pre">type(a)</span></code>. If the

  696. looked-up value is an object defining one of the descriptor methods, then Python

  697. may override the default behavior and invoke the descriptor method instead.

  698. Where this occurs in the precedence chain depends on which descriptor methods

  699. were defined.</p>

  700. <p>Descriptors are a powerful, general purpose protocol.  They are the mechanism

  701. behind properties, methods, static methods, class methods, and

  702. <a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate"><span class="pre">super()</span></code></a>.  They are used throughout Python itself.  Descriptors

  703. simplify the underlying C code and offer a flexible set of new tools for

  704. everyday Python programs.</p>

  705. </section>

  706. <section id="descriptor-protocol">

  707. <h3><a class="toc-backref" href="#id15" role="doc-backlink">Descriptor protocol</a><a class="headerlink" href="#descriptor-protocol" title="Link to this heading">¶</a></h3>

  708. <p><code class="docutils literal notranslate"><span class="pre">descr.__get__(self,</span> <span class="pre">obj,</span> <span class="pre">type=None)</span></code></p>

  709. <p><code class="docutils literal notranslate"><span class="pre">descr.__set__(self,</span> <span class="pre">obj,</span> <span class="pre">value)</span></code></p>

  710. <p><code class="docutils literal notranslate"><span class="pre">descr.__delete__(self,</span> <span class="pre">obj)</span></code></p>

  711. <p>That is all there is to it.  Define any of these methods and an object is

  712. considered a descriptor and can override default behavior upon being looked up

  713. as an attribute.</p>

  714. <p>If an object defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code>, it is considered

  715. a data descriptor.  Descriptors that only define <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> are called

  716. non-data descriptors (they are often used for methods but other uses are

  717. possible).</p>

  718. <p>Data and non-data descriptors differ in how overrides are calculated with

  719. respect to entries in an instance’s dictionary.  If an instance’s dictionary

  720. has an entry with the same name as a data descriptor, the data descriptor

  721. takes precedence.  If an instance’s dictionary has an entry with the same

  722. name as a non-data descriptor, the dictionary entry takes precedence.</p>

  723. <p>To make a read-only data descriptor, define both <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> and

  724. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code> with the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code> raising an <a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> when

  725. called.  Defining the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code> method with an exception raising

  726. placeholder is enough to make it a data descriptor.</p>

  727. </section>

  728. <section id="overview-of-descriptor-invocation">

  729. <h3><a class="toc-backref" href="#id16" role="doc-backlink">Overview of descriptor invocation</a><a class="headerlink" href="#overview-of-descriptor-invocation" title="Link to this heading">¶</a></h3>

  730. <p>A descriptor can be called directly with <code class="docutils literal notranslate"><span class="pre">desc.__get__(obj)</span></code> or

  731. <code class="docutils literal notranslate"><span class="pre">desc.__get__(None,</span> <span class="pre">cls)</span></code>.</p>

  732. <p>But it is more common for a descriptor to be invoked automatically from

  733. attribute access.</p>

  734. <p>The expression <code class="docutils literal notranslate"><span class="pre">obj.x</span></code> looks up the attribute <code class="docutils literal notranslate"><span class="pre">x</span></code> in the chain of

  735. namespaces for <code class="docutils literal notranslate"><span class="pre">obj</span></code>.  If the search finds a descriptor outside of the

  736. instance <code class="docutils literal notranslate"><span class="pre">__dict__</span></code>, its <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> method is invoked according to the

  737. precedence rules listed below.</p>

  738. <p>The details of invocation depend on whether <code class="docutils literal notranslate"><span class="pre">obj</span></code> is an object, class, or

  739. instance of super.</p>

  740. </section>

  741. <section id="invocation-from-an-instance">

  742. <h3><a class="toc-backref" href="#id17" role="doc-backlink">Invocation from an instance</a><a class="headerlink" href="#invocation-from-an-instance" title="Link to this heading">¶</a></h3>

  743. <p>Instance lookup scans through a chain of namespaces giving data descriptors

  744. the highest priority, followed by instance variables, then non-data

  745. descriptors, then class variables, and lastly <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code> if it is

  746. provided.</p>

  747. <p>If a descriptor is found for <code class="docutils literal notranslate"><span class="pre">a.x</span></code>, then it is invoked with:

  748. <code class="docutils literal notranslate"><span class="pre">desc.__get__(a,</span> <span class="pre">type(a))</span></code>.</p>

  749. <p>The logic for a dotted lookup is in <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__getattribute__()</span></code></a>.  Here is

  750. a pure Python equivalent:</p>

  751. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">find_name_in_mro</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">default</span><span class="p">):</span>

  752.     <span class="s2">&quot;Emulate _PyType_Lookup() in Objects/typeobject.c&quot;</span>

  753.     <span class="k">for</span> <span class="n">base</span> <span class="ow">in</span> <span class="bp">cls</span><span class="o">.</span><span class="vm">__mro__</span><span class="p">:</span>

  754.         <span class="k">if</span> <span class="n">name</span> <span class="ow">in</span> <span class="nb">vars</span><span class="p">(</span><span class="n">base</span><span class="p">):</span>

  755.             <span class="k">return</span> <span class="nb">vars</span><span class="p">(</span><span class="n">base</span><span class="p">)[</span><span class="n">name</span><span class="p">]</span>

  756.     <span class="k">return</span> <span class="n">default</span>

  757. 

  758. <span class="k">def</span> <span class="nf">object_getattribute</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  759.     <span class="s2">&quot;Emulate PyObject_GenericGetAttr() in Objects/object.c&quot;</span>

  760.     <span class="n">null</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  761.     <span class="n">objtype</span> <span class="o">=</span> <span class="nb">type</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span>

  762.     <span class="n">cls_var</span> <span class="o">=</span> <span class="n">find_name_in_mro</span><span class="p">(</span><span class="n">objtype</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">null</span><span class="p">)</span>

  763.     <span class="n">descr_get</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">cls_var</span><span class="p">),</span> <span class="s1">&#39;__get__&#39;</span><span class="p">,</span> <span class="n">null</span><span class="p">)</span>

  764.     <span class="k">if</span> <span class="n">descr_get</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">null</span><span class="p">:</span>

  765.         <span class="k">if</span> <span class="p">(</span><span class="nb">hasattr</span><span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">cls_var</span><span class="p">),</span> <span class="s1">&#39;__set__&#39;</span><span class="p">)</span>

  766.             <span class="ow">or</span> <span class="nb">hasattr</span><span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">cls_var</span><span class="p">),</span> <span class="s1">&#39;__delete__&#39;</span><span class="p">)):</span>

  767.             <span class="k">return</span> <span class="n">descr_get</span><span class="p">(</span><span class="n">cls_var</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="p">)</span>     <span class="c1"># data descriptor</span>

  768.     <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s1">&#39;__dict__&#39;</span><span class="p">)</span> <span class="ow">and</span> <span class="n">name</span> <span class="ow">in</span> <span class="nb">vars</span><span class="p">(</span><span class="n">obj</span><span class="p">):</span>

  769.         <span class="k">return</span> <span class="nb">vars</span><span class="p">(</span><span class="n">obj</span><span class="p">)[</span><span class="n">name</span><span class="p">]</span>                          <span class="c1"># instance variable</span>

  770.     <span class="k">if</span> <span class="n">descr_get</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">null</span><span class="p">:</span>

  771.         <span class="k">return</span> <span class="n">descr_get</span><span class="p">(</span><span class="n">cls_var</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="p">)</span>         <span class="c1"># non-data descriptor</span>

  772.     <span class="k">if</span> <span class="n">cls_var</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">null</span><span class="p">:</span>

  773.         <span class="k">return</span> <span class="n">cls_var</span>                                  <span class="c1"># class variable</span>

  774.     <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>

  775. </pre></div>

  776. </div>

  777. <p>Note, there is no <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code> hook in the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code>

  778. code.  That is why calling <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code> directly or with

  779. <code class="docutils literal notranslate"><span class="pre">super().__getattribute__</span></code> will bypass <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code> entirely.</p>

  780. <p>Instead, it is the dot operator and the <a class="reference internal" href="../library/functions.html#getattr" title="getattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">getattr()</span></code></a> function that are

  781. responsible for invoking <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code> whenever <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code>

  782. raises an <a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.  Their logic is encapsulated in a helper

  783. function:</p>

  784. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">getattr_hook</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  785.     <span class="s2">&quot;Emulate slot_tp_getattr_hook() in Objects/typeobject.c&quot;</span>

  786.     <span class="k">try</span><span class="p">:</span>

  787.         <span class="k">return</span> <span class="n">obj</span><span class="o">.</span><span class="fm">__getattribute__</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>

  788.     <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>

  789.         <span class="k">if</span> <span class="ow">not</span> <span class="nb">hasattr</span><span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">obj</span><span class="p">),</span> <span class="s1">&#39;__getattr__&#39;</span><span class="p">):</span>

  790.             <span class="k">raise</span>

  791.     <span class="k">return</span> <span class="nb">type</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span><span class="o">.</span><span class="fm">__getattr__</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>             <span class="c1"># __getattr__</span>

  792. </pre></div>

  793. </div>

  794. </section>

  795. <section id="invocation-from-a-class">

  796. <h3><a class="toc-backref" href="#id18" role="doc-backlink">Invocation from a class</a><a class="headerlink" href="#invocation-from-a-class" title="Link to this heading">¶</a></h3>

  797. <p>The logic for a dotted lookup such as <code class="docutils literal notranslate"><span class="pre">A.x</span></code> is in

  798. <code class="xref py py-meth docutils literal notranslate"><span class="pre">type.__getattribute__()</span></code>.  The steps are similar to those for

  799. <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__getattribute__()</span></code></a> but the instance dictionary lookup is replaced

  800. by a search through the class’s <a class="reference internal" href="../glossary.html#term-method-resolution-order"><span class="xref std std-term">method resolution order</span></a>.</p>

  801. <p>If a descriptor is found, it is invoked with <code class="docutils literal notranslate"><span class="pre">desc.__get__(None,</span> <span class="pre">A)</span></code>.</p>

  802. <p>The full C implementation can be found in <code class="xref c c-func docutils literal notranslate"><span class="pre">type_getattro()</span></code> and

  803. <code class="xref c c-func docutils literal notranslate"><span class="pre">_PyType_Lookup()</span></code> in <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Objects/typeobject.c">Objects/typeobject.c</a>.</p>

  804. </section>

  805. <section id="invocation-from-super">

  806. <h3><a class="toc-backref" href="#id19" role="doc-backlink">Invocation from super</a><a class="headerlink" href="#invocation-from-super" title="Link to this heading">¶</a></h3>

  807. <p>The logic for super’s dotted lookup is in the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code> method for

  808. object returned by <a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-class docutils literal notranslate"><span class="pre">super()</span></code></a>.</p>

  809. <p>A dotted lookup such as <code class="docutils literal notranslate"><span class="pre">super(A,</span> <span class="pre">obj).m</span></code> searches <code class="docutils literal notranslate"><span class="pre">obj.__class__.__mro__</span></code>

  810. for the base class <code class="docutils literal notranslate"><span class="pre">B</span></code> immediately following <code class="docutils literal notranslate"><span class="pre">A</span></code> and then returns

  811. <code class="docutils literal notranslate"><span class="pre">B.__dict__['m'].__get__(obj,</span> <span class="pre">A)</span></code>.  If not a descriptor, <code class="docutils literal notranslate"><span class="pre">m</span></code> is returned

  812. unchanged.</p>

  813. <p>The full C implementation can be found in <code class="xref c c-func docutils literal notranslate"><span class="pre">super_getattro()</span></code> in

  814. <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Objects/typeobject.c">Objects/typeobject.c</a>.  A pure Python equivalent can be found in

  815. <a class="reference external" href="https://www.python.org/download/releases/2.2.3/descrintro/#cooperation">Guido’s Tutorial</a>.</p>

  816. </section>

  817. <section id="summary-of-invocation-logic">

  818. <h3><a class="toc-backref" href="#id20" role="doc-backlink">Summary of invocation logic</a><a class="headerlink" href="#summary-of-invocation-logic" title="Link to this heading">¶</a></h3>

  819. <p>The mechanism for descriptors is embedded in the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code>

  820. methods for <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>, <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a>, and <a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate"><span class="pre">super()</span></code></a>.</p>

  821. <p>The important points to remember are:</p>

  822. <ul class="simple">

  823. <li><p>Descriptors are invoked by the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code> method.</p></li>

  824. <li><p>Classes inherit this machinery from <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>, <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a>, or

  825. <a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate"><span class="pre">super()</span></code></a>.</p></li>

  826. <li><p>Overriding <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code> prevents automatic descriptor calls

  827. because all the descriptor logic is in that method.</p></li>

  828. <li><p><a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__getattribute__()</span></code></a> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">type.__getattribute__()</span></code> make

  829. different calls to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code>.  The first includes the instance and may

  830. include the class.  The second puts in <code class="docutils literal notranslate"><span class="pre">None</span></code> for the instance and always

  831. includes the class.</p></li>

  832. <li><p>Data descriptors always override instance dictionaries.</p></li>

  833. <li><p>Non-data descriptors may be overridden by instance dictionaries.</p></li>

  834. </ul>

  835. </section>

  836. <section id="automatic-name-notification">

  837. <h3><a class="toc-backref" href="#id21" role="doc-backlink">Automatic name notification</a><a class="headerlink" href="#automatic-name-notification" title="Link to this heading">¶</a></h3>

  838. <p>Sometimes it is desirable for a descriptor to know what class variable name it

  839. was assigned to.  When a new class is created, the <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a> metaclass

  840. scans the dictionary of the new class.  If any of the entries are descriptors

  841. and if they define <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code>, that method is called with two

  842. arguments.  The <em>owner</em> is the class where the descriptor is used, and the

  843. <em>name</em> is the class variable the descriptor was assigned to.</p>

  844. <p>The implementation details are in <code class="xref c c-func docutils literal notranslate"><span class="pre">type_new()</span></code> and

  845. <code class="xref c c-func docutils literal notranslate"><span class="pre">set_names()</span></code> in <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Objects/typeobject.c">Objects/typeobject.c</a>.</p>

  846. <p>Since the update logic is in <code class="xref py py-meth docutils literal notranslate"><span class="pre">type.__new__()</span></code>, notifications only take

  847. place at the time of class creation.  If descriptors are added to the class

  848. afterwards, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code> will need to be called manually.</p>

  849. </section>

  850. <section id="orm-example">

  851. <h3><a class="toc-backref" href="#id22" role="doc-backlink">ORM example</a><a class="headerlink" href="#orm-example" title="Link to this heading">¶</a></h3>

  852. <p>The following code is a simplified skeleton showing how data descriptors could

  853. be used to implement an <a class="reference external" href="https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping">object relational mapping</a>.</p>

  854. <p>The essential idea is that the data is stored in an external database.  The

  855. Python instances only hold keys to the database’s tables.  Descriptors take

  856. care of lookups or updates:</p>

  857. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Field</span><span class="p">:</span>

  858. 

  859.     <span class="k">def</span> <span class="nf">__set_name__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  860.         <span class="bp">self</span><span class="o">.</span><span class="n">fetch</span> <span class="o">=</span> <span class="sa">f</span><span class="s1">&#39;SELECT </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s1"> FROM </span><span class="si">{</span><span class="n">owner</span><span class="o">.</span><span class="n">table</span><span class="si">}</span><span class="s1"> WHERE </span><span class="si">{</span><span class="n">owner</span><span class="o">.</span><span class="n">key</span><span class="si">}</span><span class="s1">=?;&#39;</span>

  861.         <span class="bp">self</span><span class="o">.</span><span class="n">store</span> <span class="o">=</span> <span class="sa">f</span><span class="s1">&#39;UPDATE </span><span class="si">{</span><span class="n">owner</span><span class="o">.</span><span class="n">table</span><span class="si">}</span><span class="s1"> SET </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s1">=? WHERE </span><span class="si">{</span><span class="n">owner</span><span class="o">.</span><span class="n">key</span><span class="si">}</span><span class="s1">=?;&#39;</span>

  862. 

  863.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  864.         <span class="k">return</span> <span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">fetch</span><span class="p">,</span> <span class="p">[</span><span class="n">obj</span><span class="o">.</span><span class="n">key</span><span class="p">])</span><span class="o">.</span><span class="n">fetchone</span><span class="p">()[</span><span class="mi">0</span><span class="p">]</span>

  865. 

  866.     <span class="k">def</span> <span class="fm">__set__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  867.         <span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="p">,</span> <span class="p">[</span><span class="n">value</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">key</span><span class="p">])</span>

  868.         <span class="n">conn</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span>

  869. </pre></div>

  870. </div>

  871. <p>We can use the <code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code> class to define <a class="reference external" href="https://en.wikipedia.org/wiki/Database_model">models</a> that describe the schema for

  872. each table in a database:</p>

  873. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Movie</span><span class="p">:</span>

  874.     <span class="n">table</span> <span class="o">=</span> <span class="s1">&#39;Movies&#39;</span>                    <span class="c1"># Table name</span>

  875.     <span class="n">key</span> <span class="o">=</span> <span class="s1">&#39;title&#39;</span>                       <span class="c1"># Primary key</span>

  876.     <span class="n">director</span> <span class="o">=</span> <span class="n">Field</span><span class="p">()</span>

  877.     <span class="n">year</span> <span class="o">=</span> <span class="n">Field</span><span class="p">()</span>

  878. 

  879.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">):</span>

  880.         <span class="bp">self</span><span class="o">.</span><span class="n">key</span> <span class="o">=</span> <span class="n">key</span>

  881. 

  882. <span class="k">class</span> <span class="nc">Song</span><span class="p">:</span>

  883.     <span class="n">table</span> <span class="o">=</span> <span class="s1">&#39;Music&#39;</span>

  884.     <span class="n">key</span> <span class="o">=</span> <span class="s1">&#39;title&#39;</span>

  885.     <span class="n">artist</span> <span class="o">=</span> <span class="n">Field</span><span class="p">()</span>

  886.     <span class="n">year</span> <span class="o">=</span> <span class="n">Field</span><span class="p">()</span>

  887.     <span class="n">genre</span> <span class="o">=</span> <span class="n">Field</span><span class="p">()</span>

  888. 

  889.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">):</span>

  890.         <span class="bp">self</span><span class="o">.</span><span class="n">key</span> <span class="o">=</span> <span class="n">key</span>

  891. </pre></div>

  892. </div>

  893. <p>To use the models, first connect to the database:</p>

  894. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">sqlite3</span>

  895. <span class="gp">&gt;&gt;&gt; </span><span class="n">conn</span> <span class="o">=</span> <span class="n">sqlite3</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s1">&#39;entertainment.db&#39;</span><span class="p">)</span>

  896. </pre></div>

  897. </div>

  898. <p>An interactive session shows how data is retrieved from the database and how

  899. it can be updated:</p>

  900. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Movie</span><span class="p">(</span><span class="s1">&#39;Star Wars&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">director</span>

  901. <span class="go">&#39;George Lucas&#39;</span>

  902. <span class="gp">&gt;&gt;&gt; </span><span class="n">jaws</span> <span class="o">=</span> <span class="n">Movie</span><span class="p">(</span><span class="s1">&#39;Jaws&#39;</span><span class="p">)</span>

  903. <span class="gp">&gt;&gt;&gt; </span><span class="sa">f</span><span class="s1">&#39;Released in </span><span class="si">{</span><span class="n">jaws</span><span class="o">.</span><span class="n">year</span><span class="si">}</span><span class="s1"> by </span><span class="si">{</span><span class="n">jaws</span><span class="o">.</span><span class="n">director</span><span class="si">}</span><span class="s1">&#39;</span>

  904. <span class="go">&#39;Released in 1975 by Steven Spielberg&#39;</span>

  905. 

  906. <span class="gp">&gt;&gt;&gt; </span><span class="n">Song</span><span class="p">(</span><span class="s1">&#39;Country Roads&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">artist</span>

  907. <span class="go">&#39;John Denver&#39;</span>

  908. 

  909. <span class="gp">&gt;&gt;&gt; </span><span class="n">Movie</span><span class="p">(</span><span class="s1">&#39;Star Wars&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">director</span> <span class="o">=</span> <span class="s1">&#39;J.J. Abrams&#39;</span>

  910. <span class="gp">&gt;&gt;&gt; </span><span class="n">Movie</span><span class="p">(</span><span class="s1">&#39;Star Wars&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">director</span>

  911. <span class="go">&#39;J.J. Abrams&#39;</span>

  912. </pre></div>

  913. </div>

  914. </section>

  915. </section>

  916. <section id="pure-python-equivalents">

  917. <h2><a class="toc-backref" href="#id23" role="doc-backlink">Pure Python Equivalents</a><a class="headerlink" href="#pure-python-equivalents" title="Link to this heading">¶</a></h2>

  918. <p>The descriptor protocol is simple and offers exciting possibilities.  Several

  919. use cases are so common that they have been prepackaged into built-in tools.

  920. Properties, bound methods, static methods, class methods, and __slots__ are

  921. all based on the descriptor protocol.</p>

  922. <section id="properties">

  923. <h3><a class="toc-backref" href="#id24" role="doc-backlink">Properties</a><a class="headerlink" href="#properties" title="Link to this heading">¶</a></h3>

  924. <p>Calling <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a> is a succinct way of building a data descriptor that

  925. triggers a function call upon access to an attribute.  Its signature is:</p>

  926. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">property</span><span class="p">(</span><span class="n">fget</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">fset</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">fdel</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">doc</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">property</span>

  927. </pre></div>

  928. </div>

  929. <p>The documentation shows a typical use to define a managed attribute <code class="docutils literal notranslate"><span class="pre">x</span></code>:</p>

  930. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">C</span><span class="p">:</span>

  931.     <span class="k">def</span> <span class="nf">getx</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">__x</span>

  932.     <span class="k">def</span> <span class="nf">setx</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> <span class="bp">self</span><span class="o">.</span><span class="n">__x</span> <span class="o">=</span> <span class="n">value</span>

  933.     <span class="k">def</span> <span class="nf">delx</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">del</span> <span class="bp">self</span><span class="o">.</span><span class="n">__x</span>

  934.     <span class="n">x</span> <span class="o">=</span> <span class="nb">property</span><span class="p">(</span><span class="n">getx</span><span class="p">,</span> <span class="n">setx</span><span class="p">,</span> <span class="n">delx</span><span class="p">,</span> <span class="s2">&quot;I&#39;m the &#39;x&#39; property.&quot;</span><span class="p">)</span>

  935. </pre></div>

  936. </div>

  937. <p>To see how <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a> is implemented in terms of the descriptor protocol,

  938. here is a pure Python equivalent:</p>

  939. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Property</span><span class="p">:</span>

  940.     <span class="s2">&quot;Emulate PyProperty_Type() in Objects/descrobject.c&quot;</span>

  941. 

  942.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fget</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">fset</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">fdel</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">doc</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  943.         <span class="bp">self</span><span class="o">.</span><span class="n">fget</span> <span class="o">=</span> <span class="n">fget</span>

  944.         <span class="bp">self</span><span class="o">.</span><span class="n">fset</span> <span class="o">=</span> <span class="n">fset</span>

  945.         <span class="bp">self</span><span class="o">.</span><span class="n">fdel</span> <span class="o">=</span> <span class="n">fdel</span>

  946.         <span class="k">if</span> <span class="n">doc</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">fget</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>

  947.             <span class="n">doc</span> <span class="o">=</span> <span class="n">fget</span><span class="o">.</span><span class="vm">__doc__</span>

  948.         <span class="bp">self</span><span class="o">.</span><span class="vm">__doc__</span> <span class="o">=</span> <span class="n">doc</span>

  949.         <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span>

  950. 

  951.     <span class="k">def</span> <span class="nf">__set_name__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  952.         <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="n">name</span>

  953. 

  954.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  955.         <span class="k">if</span> <span class="n">obj</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  956.             <span class="k">return</span> <span class="bp">self</span>

  957.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">fget</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  958.             <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span>

  959.                 <span class="sa">f</span><span class="s1">&#39;property </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_name</span><span class="si">!r}</span><span class="s1"> of </span><span class="si">{</span><span class="nb">type</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span><span class="o">.</span><span class="vm">__name__</span><span class="si">!r}</span><span class="s1"> object has no getter&#39;</span>

  960.              <span class="p">)</span>

  961.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">fget</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span>

  962. 

  963.     <span class="k">def</span> <span class="fm">__set__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  964.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">fset</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  965.             <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span>

  966.                 <span class="sa">f</span><span class="s1">&#39;property </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_name</span><span class="si">!r}</span><span class="s1"> of </span><span class="si">{</span><span class="nb">type</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span><span class="o">.</span><span class="vm">__name__</span><span class="si">!r}</span><span class="s1"> object has no setter&#39;</span>

  967.              <span class="p">)</span>

  968.         <span class="bp">self</span><span class="o">.</span><span class="n">fset</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  969. 

  970.     <span class="k">def</span> <span class="fm">__delete__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">):</span>

  971.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">fdel</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  972.             <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span>

  973.                 <span class="sa">f</span><span class="s1">&#39;property </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_name</span><span class="si">!r}</span><span class="s1"> of </span><span class="si">{</span><span class="nb">type</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span><span class="o">.</span><span class="vm">__name__</span><span class="si">!r}</span><span class="s1"> object has no deleter&#39;</span>

  974.              <span class="p">)</span>

  975.         <span class="bp">self</span><span class="o">.</span><span class="n">fdel</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span>

  976. 

  977.     <span class="k">def</span> <span class="nf">getter</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fget</span><span class="p">):</span>

  978.         <span class="n">prop</span> <span class="o">=</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)(</span><span class="n">fget</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">fset</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">fdel</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__doc__</span><span class="p">)</span>

  979.         <span class="n">prop</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_name</span>

  980.         <span class="k">return</span> <span class="n">prop</span>

  981. 

  982.     <span class="k">def</span> <span class="nf">setter</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fset</span><span class="p">):</span>

  983.         <span class="n">prop</span> <span class="o">=</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)(</span><span class="bp">self</span><span class="o">.</span><span class="n">fget</span><span class="p">,</span> <span class="n">fset</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">fdel</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__doc__</span><span class="p">)</span>

  984.         <span class="n">prop</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_name</span>

  985.         <span class="k">return</span> <span class="n">prop</span>

  986. 

  987.     <span class="k">def</span> <span class="nf">deleter</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fdel</span><span class="p">):</span>

  988.         <span class="n">prop</span> <span class="o">=</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)(</span><span class="bp">self</span><span class="o">.</span><span class="n">fget</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">fset</span><span class="p">,</span> <span class="n">fdel</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__doc__</span><span class="p">)</span>

  989.         <span class="n">prop</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_name</span>

  990.         <span class="k">return</span> <span class="n">prop</span>

  991. </pre></div>

  992. </div>

  993. <p>The <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a> builtin helps whenever a user interface has granted

  994. attribute access and then subsequent changes require the intervention of a

  995. method.</p>

  996. <p>For instance, a spreadsheet class may grant access to a cell value through

  997. <code class="docutils literal notranslate"><span class="pre">Cell('b10').value</span></code>. Subsequent improvements to the program require the cell

  998. to be recalculated on every access; however, the programmer does not want to

  999. affect existing client code accessing the attribute directly.  The solution is

  1000. to wrap access to the value attribute in a property data descriptor:</p>

  1001. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Cell</span><span class="p">:</span>

  1002.     <span class="o">...</span>

  1003. 

  1004.     <span class="nd">@property</span>

  1005.     <span class="k">def</span> <span class="nf">value</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1006.         <span class="s2">&quot;Recalculate the cell before returning value&quot;</span>

  1007.         <span class="bp">self</span><span class="o">.</span><span class="n">recalc</span><span class="p">()</span>

  1008.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_value</span>

  1009. </pre></div>

  1010. </div>

  1011. <p>Either the built-in <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate"><span class="pre">property()</span></code></a> or our <code class="xref py py-func docutils literal notranslate"><span class="pre">Property()</span></code> equivalent would

  1012. work in this example.</p>

  1013. </section>

  1014. <section id="functions-and-methods">

  1015. <h3><a class="toc-backref" href="#id25" role="doc-backlink">Functions and methods</a><a class="headerlink" href="#functions-and-methods" title="Link to this heading">¶</a></h3>

  1016. <p>Python’s object oriented features are built upon a function based environment.

  1017. Using non-data descriptors, the two are merged seamlessly.</p>

  1018. <p>Functions stored in class dictionaries get turned into methods when invoked.

  1019. Methods only differ from regular functions in that the object instance is

  1020. prepended to the other arguments.  By convention, the instance is called

  1021. <em>self</em> but could be called <em>this</em> or any other variable name.</p>

  1022. <p>Methods can be created manually with <a class="reference internal" href="../library/types.html#types.MethodType" title="types.MethodType"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.MethodType</span></code></a> which is

  1023. roughly equivalent to:</p>

  1024. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MethodType</span><span class="p">:</span>

  1025.     <span class="s2">&quot;Emulate PyMethod_Type in Objects/classobject.c&quot;</span>

  1026. 

  1027.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">func</span><span class="p">,</span> <span class="n">obj</span><span class="p">):</span>

  1028.         <span class="bp">self</span><span class="o">.</span><span class="vm">__func__</span> <span class="o">=</span> <span class="n">func</span>

  1029.         <span class="bp">self</span><span class="o">.</span><span class="vm">__self__</span> <span class="o">=</span> <span class="n">obj</span>

  1030. 

  1031.     <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</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">kwargs</span><span class="p">):</span>

  1032.         <span class="n">func</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__func__</span>

  1033.         <span class="n">obj</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__self__</span>

  1034.         <span class="k">return</span> <span class="n">func</span><span class="p">(</span><span class="n">obj</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">kwargs</span><span class="p">)</span>

  1035. </pre></div>

  1036. </div>

  1037. <p>To support automatic creation of methods, functions include the

  1038. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> method for binding methods during attribute access.  This

  1039. means that functions are non-data descriptors that return bound methods

  1040. during dotted lookup from an instance.  Here’s how it works:</p>

  1041. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Function</span><span class="p">:</span>

  1042.     <span class="o">...</span>

  1043. 

  1044.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1045.         <span class="s2">&quot;Simulate func_descr_get() in Objects/funcobject.c&quot;</span>

  1046.         <span class="k">if</span> <span class="n">obj</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1047.             <span class="k">return</span> <span class="bp">self</span>

  1048.         <span class="k">return</span> <span class="n">MethodType</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">)</span>

  1049. </pre></div>

  1050. </div>

  1051. <p>Running the following class in the interpreter shows how the function

  1052. descriptor works in practice:</p>

  1053. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">D</span><span class="p">:</span>

  1054.     <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>

  1055.          <span class="k">return</span> <span class="n">x</span>

  1056. </pre></div>

  1057. </div>

  1058. <p>The function has a <a class="reference internal" href="../glossary.html#term-qualified-name"><span class="xref std std-term">qualified name</span></a> attribute to support introspection:</p>

  1059. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">D</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="vm">__qualname__</span>

  1060. <span class="go">&#39;D.f&#39;</span>

  1061. </pre></div>

  1062. </div>

  1063. <p>Accessing the function through the class dictionary does not invoke

  1064. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code>.  Instead, it just returns the underlying function object:</p>

  1065. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">D</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">[</span><span class="s1">&#39;f&#39;</span><span class="p">]</span>

  1066. <span class="go">&lt;function D.f at 0x00C45070&gt;</span>

  1067. </pre></div>

  1068. </div>

  1069. <p>Dotted access from a class calls <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> which just returns the

  1070. underlying function unchanged:</p>

  1071. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">D</span><span class="o">.</span><span class="n">f</span>

  1072. <span class="go">&lt;function D.f at 0x00C45070&gt;</span>

  1073. </pre></div>

  1074. </div>

  1075. <p>The interesting behavior occurs during dotted access from an instance.  The

  1076. dotted lookup calls <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> which returns a bound method object:</p>

  1077. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="n">D</span><span class="p">()</span>

  1078. <span class="gp">&gt;&gt;&gt; </span><span class="n">d</span><span class="o">.</span><span class="n">f</span>

  1079. <span class="go">&lt;bound method D.f of &lt;__main__.D object at 0x00B18C90&gt;&gt;</span>

  1080. </pre></div>

  1081. </div>

  1082. <p>Internally, the bound method stores the underlying function and the bound

  1083. instance:</p>

  1084. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="vm">__func__</span>

  1085. <span class="go">&lt;function D.f at 0x00C45070&gt;</span>

  1086. 

  1087. <span class="gp">&gt;&gt;&gt; </span><span class="n">d</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="vm">__self__</span>

  1088. <span class="go">&lt;__main__.D object at 0x00B18C90&gt;</span>

  1089. </pre></div>

  1090. </div>

  1091. <p>If you have ever wondered where <em>self</em> comes from in regular methods or where

  1092. <em>cls</em> comes from in class methods, this is it!</p>

  1093. </section>

  1094. <section id="kinds-of-methods">

  1095. <h3><a class="toc-backref" href="#id26" role="doc-backlink">Kinds of methods</a><a class="headerlink" href="#kinds-of-methods" title="Link to this heading">¶</a></h3>

  1096. <p>Non-data descriptors provide a simple mechanism for variations on the usual

  1097. patterns of binding functions into methods.</p>

  1098. <p>To recap, functions have a <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> method so that they can be converted

  1099. to a method when accessed as attributes.  The non-data descriptor transforms an

  1100. <code class="docutils literal notranslate"><span class="pre">obj.f(*args)</span></code> call into <code class="docutils literal notranslate"><span class="pre">f(obj,</span> <span class="pre">*args)</span></code>.  Calling <code class="docutils literal notranslate"><span class="pre">cls.f(*args)</span></code>

  1101. becomes <code class="docutils literal notranslate"><span class="pre">f(*args)</span></code>.</p>

  1102. <p>This chart summarizes the binding and its two most useful variants:</p>

  1103. <blockquote>

  1104. <div><table class="docutils align-default">

  1105. <thead>

  1106. <tr class="row-odd"><th class="head"><p>Transformation</p></th>

  1107. <th class="head"><p>Called from an

  1108. object</p></th>

  1109. <th class="head"><p>Called from a

  1110. class</p></th>

  1111. </tr>

  1112. </thead>

  1113. <tbody>

  1114. <tr class="row-even"><td><p>function</p></td>

  1115. <td><p>f(obj, *args)</p></td>

  1116. <td><p>f(*args)</p></td>

  1117. </tr>

  1118. <tr class="row-odd"><td><p>staticmethod</p></td>

  1119. <td><p>f(*args)</p></td>

  1120. <td><p>f(*args)</p></td>

  1121. </tr>

  1122. <tr class="row-even"><td><p>classmethod</p></td>

  1123. <td><p>f(type(obj), *args)</p></td>

  1124. <td><p>f(cls, *args)</p></td>

  1125. </tr>

  1126. </tbody>

  1127. </table>

  1128. </div></blockquote>

  1129. </section>

  1130. <section id="static-methods">

  1131. <h3><a class="toc-backref" href="#id27" role="doc-backlink">Static methods</a><a class="headerlink" href="#static-methods" title="Link to this heading">¶</a></h3>

  1132. <p>Static methods return the underlying function without changes.  Calling either

  1133. <code class="docutils literal notranslate"><span class="pre">c.f</span></code> or <code class="docutils literal notranslate"><span class="pre">C.f</span></code> is the equivalent of a direct lookup into

  1134. <code class="docutils literal notranslate"><span class="pre">object.__getattribute__(c,</span> <span class="pre">&quot;f&quot;)</span></code> or <code class="docutils literal notranslate"><span class="pre">object.__getattribute__(C,</span> <span class="pre">&quot;f&quot;)</span></code>. As a

  1135. result, the function becomes identically accessible from either an object or a

  1136. class.</p>

  1137. <p>Good candidates for static methods are methods that do not reference the

  1138. <code class="docutils literal notranslate"><span class="pre">self</span></code> variable.</p>

  1139. <p>For instance, a statistics package may include a container class for

  1140. experimental data.  The class provides normal methods for computing the average,

  1141. mean, median, and other descriptive statistics that depend on the data. However,

  1142. there may be useful functions which are conceptually related but do not depend

  1143. on the data.  For instance, <code class="docutils literal notranslate"><span class="pre">erf(x)</span></code> is handy conversion routine that comes up

  1144. in statistical work but does not directly depend on a particular dataset.

  1145. It can be called either from an object or the class:  <code class="docutils literal notranslate"><span class="pre">s.erf(1.5)</span> <span class="pre">--&gt;</span> <span class="pre">.9332</span></code> or

  1146. <code class="docutils literal notranslate"><span class="pre">Sample.erf(1.5)</span> <span class="pre">--&gt;</span> <span class="pre">.9332</span></code>.</p>

  1147. <p>Since static methods return the underlying function with no changes, the

  1148. example calls are unexciting:</p>

  1149. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">E</span><span class="p">:</span>

  1150.     <span class="nd">@staticmethod</span>

  1151.     <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>

  1152.         <span class="k">return</span> <span class="n">x</span> <span class="o">*</span> <span class="mi">10</span>

  1153. </pre></div>

  1154. </div>

  1155. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">E</span><span class="o">.</span><span class="n">f</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  1156. <span class="go">30</span>

  1157. <span class="gp">&gt;&gt;&gt; </span><span class="n">E</span><span class="p">()</span><span class="o">.</span><span class="n">f</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  1158. <span class="go">30</span>

  1159. </pre></div>

  1160. </div>

  1161. <p>Using the non-data descriptor protocol, a pure Python version of

  1162. <a class="reference internal" href="../library/functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a> would look like this:</p>

  1163. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">functools</span>

  1164. 

  1165. <span class="k">class</span> <span class="nc">StaticMethod</span><span class="p">:</span>

  1166.     <span class="s2">&quot;Emulate PyStaticMethod_Type() in Objects/funcobject.c&quot;</span>

  1167. 

  1168.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">f</span><span class="p">):</span>

  1169.         <span class="bp">self</span><span class="o">.</span><span class="n">f</span> <span class="o">=</span> <span class="n">f</span>

  1170.         <span class="n">functools</span><span class="o">.</span><span class="n">update_wrapper</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span>

  1171. 

  1172.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1173.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">f</span>

  1174. 

  1175.     <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</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>

  1176.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</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>

  1177. </pre></div>

  1178. </div>

  1179. <p>The <a class="reference internal" href="../library/functools.html#functools.update_wrapper" title="functools.update_wrapper"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.update_wrapper()</span></code></a> call adds a <code class="docutils literal notranslate"><span class="pre">__wrapped__</span></code> attribute

  1180. that refers to the underlying function.  Also it carries forward

  1181. the attributes necessary to make the wrapper look like the wrapped

  1182. function: <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>, <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>,

  1183. <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>, and <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>.</p>

  1184. </section>

  1185. <section id="class-methods">

  1186. <h3><a class="toc-backref" href="#id28" role="doc-backlink">Class methods</a><a class="headerlink" href="#class-methods" title="Link to this heading">¶</a></h3>

  1187. <p>Unlike static methods, class methods prepend the class reference to the

  1188. argument list before calling the function.  This format is the same

  1189. for whether the caller is an object or a class:</p>

  1190. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">F</span><span class="p">:</span>

  1191.     <span class="nd">@classmethod</span>

  1192.     <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>

  1193.         <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="vm">__name__</span><span class="p">,</span> <span class="n">x</span>

  1194. </pre></div>

  1195. </div>

  1196. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">F</span><span class="o">.</span><span class="n">f</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  1197. <span class="go">(&#39;F&#39;, 3)</span>

  1198. <span class="gp">&gt;&gt;&gt; </span><span class="n">F</span><span class="p">()</span><span class="o">.</span><span class="n">f</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  1199. <span class="go">(&#39;F&#39;, 3)</span>

  1200. </pre></div>

  1201. </div>

  1202. <p>This behavior is useful whenever the method only needs to have a class

  1203. reference and does not rely on data stored in a specific instance.  One use for

  1204. class methods is to create alternate class constructors.  For example, the

  1205. classmethod <a class="reference internal" href="../library/stdtypes.html#dict.fromkeys" title="dict.fromkeys"><code class="xref py py-func docutils literal notranslate"><span class="pre">dict.fromkeys()</span></code></a> creates a new dictionary from a list of

  1206. keys.  The pure Python equivalent is:</p>

  1207. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Dict</span><span class="p">(</span><span class="nb">dict</span><span class="p">):</span>

  1208.     <span class="nd">@classmethod</span>

  1209.     <span class="k">def</span> <span class="nf">fromkeys</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">iterable</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1210.         <span class="s2">&quot;Emulate dict_fromkeys() in Objects/dictobject.c&quot;</span>

  1211.         <span class="n">d</span> <span class="o">=</span> <span class="bp">cls</span><span class="p">()</span>

  1212.         <span class="k">for</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>

  1213.             <span class="n">d</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>

  1214.         <span class="k">return</span> <span class="n">d</span>

  1215. </pre></div>

  1216. </div>

  1217. <p>Now a new dictionary of unique keys can be constructed like this:</p>

  1218. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="n">Dict</span><span class="o">.</span><span class="n">fromkeys</span><span class="p">(</span><span class="s1">&#39;abracadabra&#39;</span><span class="p">)</span>

  1219. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">d</span><span class="p">)</span> <span class="ow">is</span> <span class="n">Dict</span>

  1220. <span class="go">True</span>

  1221. <span class="gp">&gt;&gt;&gt; </span><span class="n">d</span>

  1222. <span class="go">{&#39;a&#39;: None, &#39;b&#39;: None, &#39;r&#39;: None, &#39;c&#39;: None, &#39;d&#39;: None}</span>

  1223. </pre></div>

  1224. </div>

  1225. <p>Using the non-data descriptor protocol, a pure Python version of

  1226. <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">classmethod()</span></code></a> would look like this:</p>

  1227. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">functools</span>

  1228. 

  1229. <span class="k">class</span> <span class="nc">ClassMethod</span><span class="p">:</span>

  1230.     <span class="s2">&quot;Emulate PyClassMethod_Type() in Objects/funcobject.c&quot;</span>

  1231. 

  1232.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">f</span><span class="p">):</span>

  1233.         <span class="bp">self</span><span class="o">.</span><span class="n">f</span> <span class="o">=</span> <span class="n">f</span>

  1234.         <span class="n">functools</span><span class="o">.</span><span class="n">update_wrapper</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span>

  1235. 

  1236.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="bp">cls</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1237.         <span class="k">if</span> <span class="bp">cls</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1238.             <span class="bp">cls</span> <span class="o">=</span> <span class="nb">type</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span>

  1239.         <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">),</span> <span class="s1">&#39;__get__&#39;</span><span class="p">):</span>

  1240.             <span class="c1"># This code path was added in Python 3.9</span>

  1241.             <span class="c1"># and was deprecated in Python 3.11.</span>

  1242.             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="fm">__get__</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="bp">cls</span><span class="p">)</span>

  1243.         <span class="k">return</span> <span class="n">MethodType</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="bp">cls</span><span class="p">)</span>

  1244. </pre></div>

  1245. </div>

  1246. <p>The code path for <code class="docutils literal notranslate"><span class="pre">hasattr(type(self.f),</span> <span class="pre">'__get__')</span></code> was added in

  1247. Python 3.9 and makes it possible for <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">classmethod()</span></code></a> to support

  1248. chained decorators.  For example, a classmethod and property could be

  1249. chained together.  In Python 3.11, this functionality was deprecated.</p>

  1250. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">G</span><span class="p">:</span>

  1251.     <span class="nd">@classmethod</span>

  1252.     <span class="nd">@property</span>

  1253.     <span class="k">def</span> <span class="nf">__doc__</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span>

  1254.         <span class="k">return</span> <span class="sa">f</span><span class="s1">&#39;A doc for </span><span class="si">{</span><span class="bp">cls</span><span class="o">.</span><span class="vm">__name__</span><span class="si">!r}</span><span class="s1">&#39;</span>

  1255. </pre></div>

  1256. </div>

  1257. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">G</span><span class="o">.</span><span class="vm">__doc__</span>

  1258. <span class="go">&quot;A doc for &#39;G&#39;&quot;</span>

  1259. </pre></div>

  1260. </div>

  1261. <p>The <a class="reference internal" href="../library/functools.html#functools.update_wrapper" title="functools.update_wrapper"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.update_wrapper()</span></code></a> call in <code class="docutils literal notranslate"><span class="pre">ClassMethod</span></code> adds a

  1262. <code class="docutils literal notranslate"><span class="pre">__wrapped__</span></code> attribute that refers to the underlying function.  Also

  1263. it carries forward the attributes necessary to make the wrapper look

  1264. like the wrapped function: <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>,

  1265. <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.__doc__" title="function.__doc__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code></a>,

  1266. and <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>.</p>

  1267. </section>

  1268. <section id="member-objects-and-slots">

  1269. <h3><a class="toc-backref" href="#id29" role="doc-backlink">Member objects and __slots__</a><a class="headerlink" href="#member-objects-and-slots" title="Link to this heading">¶</a></h3>

  1270. <p>When a class defines <code class="docutils literal notranslate"><span class="pre">__slots__</span></code>, it replaces instance dictionaries with a

  1271. fixed-length array of slot values.  From a user point of view that has

  1272. several effects:</p>

  1273. <p>1. Provides immediate detection of bugs due to misspelled attribute

  1274. assignments.  Only attribute names specified in <code class="docutils literal notranslate"><span class="pre">__slots__</span></code> are allowed:</p>

  1275. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Vehicle</span><span class="p">:</span>

  1276.     <span class="vm">__slots__</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;id_number&#39;</span><span class="p">,</span> <span class="s1">&#39;make&#39;</span><span class="p">,</span> <span class="s1">&#39;model&#39;</span><span class="p">)</span>

  1277. </pre></div>

  1278. </div>

  1279. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">auto</span> <span class="o">=</span> <span class="n">Vehicle</span><span class="p">()</span>

  1280. <span class="gp">&gt;&gt;&gt; </span><span class="n">auto</span><span class="o">.</span><span class="n">id_nubmer</span> <span class="o">=</span> <span class="s1">&#39;VYE483814LQEX&#39;</span>

  1281. <span class="gt">Traceback (most recent call last):</span>

  1282. <span class="w">    </span><span class="o">...</span>

  1283. <span class="gr">AttributeError</span>: <span class="n">&#39;Vehicle&#39; object has no attribute &#39;id_nubmer&#39;</span>

  1284. </pre></div>

  1285. </div>

  1286. <p>2. Helps create immutable objects where descriptors manage access to private

  1287. attributes stored in <code class="docutils literal notranslate"><span class="pre">__slots__</span></code>:</p>

  1288. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Immutable</span><span class="p">:</span>

  1289. 

  1290.     <span class="vm">__slots__</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;_dept&#39;</span><span class="p">,</span> <span class="s1">&#39;_name&#39;</span><span class="p">)</span>          <span class="c1"># Replace the instance dictionary</span>

  1291. 

  1292.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dept</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  1293.         <span class="bp">self</span><span class="o">.</span><span class="n">_dept</span> <span class="o">=</span> <span class="n">dept</span>                   <span class="c1"># Store to private attribute</span>

  1294.         <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="n">name</span>                   <span class="c1"># Store to private attribute</span>

  1295. 

  1296.     <span class="nd">@property</span>                               <span class="c1"># Read-only descriptor</span>

  1297.     <span class="k">def</span> <span class="nf">dept</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1298.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dept</span>

  1299. 

  1300.     <span class="nd">@property</span>

  1301.     <span class="k">def</span> <span class="nf">name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>                         <span class="c1"># Read-only descriptor</span>

  1302.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_name</span>

  1303. </pre></div>

  1304. </div>

  1305. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mark</span> <span class="o">=</span> <span class="n">Immutable</span><span class="p">(</span><span class="s1">&#39;Botany&#39;</span><span class="p">,</span> <span class="s1">&#39;Mark Watney&#39;</span><span class="p">)</span>

  1306. <span class="gp">&gt;&gt;&gt; </span><span class="n">mark</span><span class="o">.</span><span class="n">dept</span>

  1307. <span class="go">&#39;Botany&#39;</span>

  1308. <span class="gp">&gt;&gt;&gt; </span><span class="n">mark</span><span class="o">.</span><span class="n">dept</span> <span class="o">=</span> <span class="s1">&#39;Space Pirate&#39;</span>

  1309. <span class="gt">Traceback (most recent call last):</span>

  1310. <span class="w">    </span><span class="o">...</span>

  1311. <span class="gr">AttributeError</span>: <span class="n">property &#39;dept&#39; of &#39;Immutable&#39; object has no setter</span>

  1312. <span class="gp">&gt;&gt;&gt; </span><span class="n">mark</span><span class="o">.</span><span class="n">location</span> <span class="o">=</span> <span class="s1">&#39;Mars&#39;</span>

  1313. <span class="gt">Traceback (most recent call last):</span>

  1314. <span class="w">    </span><span class="o">...</span>

  1315. <span class="gr">AttributeError</span>: <span class="n">&#39;Immutable&#39; object has no attribute &#39;location&#39;</span>

  1316. </pre></div>

  1317. </div>

  1318. <p>3. Saves memory.  On a 64-bit Linux build, an instance with two attributes

  1319. takes 48 bytes with <code class="docutils literal notranslate"><span class="pre">__slots__</span></code> and 152 bytes without.  This <a class="reference external" href="https://en.wikipedia.org/wiki/Flyweight_pattern">flyweight

  1320. design pattern</a> likely only

  1321. matters when a large number of instances are going to be created.</p>

  1322. <p>4. Improves speed.  Reading instance variables is 35% faster with

  1323. <code class="docutils literal notranslate"><span class="pre">__slots__</span></code> (as measured with Python 3.10 on an Apple M1 processor).</p>

  1324. <p>5. Blocks tools like <a class="reference internal" href="../library/functools.html#functools.cached_property" title="functools.cached_property"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.cached_property()</span></code></a> which require an

  1325. instance dictionary to function correctly:</p>

  1326. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">functools</span> <span class="kn">import</span> <span class="n">cached_property</span>

  1327. 

  1328. <span class="k">class</span> <span class="nc">CP</span><span class="p">:</span>

  1329.     <span class="vm">__slots__</span> <span class="o">=</span> <span class="p">()</span>                          <span class="c1"># Eliminates the instance dict</span>

  1330. 

  1331.     <span class="nd">@cached_property</span>                        <span class="c1"># Requires an instance dict</span>

  1332.     <span class="k">def</span> <span class="nf">pi</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1333.         <span class="k">return</span> <span class="mi">4</span> <span class="o">*</span> <span class="nb">sum</span><span class="p">((</span><span class="o">-</span><span class="mf">1.0</span><span class="p">)</span><span class="o">**</span><span class="n">n</span> <span class="o">/</span> <span class="p">(</span><span class="mf">2.0</span><span class="o">*</span><span class="n">n</span> <span class="o">+</span> <span class="mf">1.0</span><span class="p">)</span>

  1334.                        <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">reversed</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">100_000</span><span class="p">)))</span>

  1335. </pre></div>

  1336. </div>

  1337. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">CP</span><span class="p">()</span><span class="o">.</span><span class="n">pi</span>

  1338. <span class="gt">Traceback (most recent call last):</span>

  1339. <span class="w">  </span><span class="c">...</span>

  1340. <span class="gr">TypeError</span>: <span class="n">No &#39;__dict__&#39; attribute on &#39;CP&#39; instance to cache &#39;pi&#39; property.</span>

  1341. </pre></div>

  1342. </div>

  1343. <p>It is not possible to create an exact drop-in pure Python version of

  1344. <code class="docutils literal notranslate"><span class="pre">__slots__</span></code> because it requires direct access to C structures and control

  1345. over object memory allocation.  However, we can build a mostly faithful

  1346. simulation where the actual C structure for slots is emulated by a private

  1347. <code class="docutils literal notranslate"><span class="pre">_slotvalues</span></code> list.  Reads and writes to that private structure are managed

  1348. by member descriptors:</p>

  1349. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">null</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1350. 

  1351. <span class="k">class</span> <span class="nc">Member</span><span class="p">:</span>

  1352. 

  1353.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">clsname</span><span class="p">,</span> <span class="n">offset</span><span class="p">):</span>

  1354.         <span class="s1">&#39;Emulate PyMemberDef in Include/structmember.h&#39;</span>

  1355.         <span class="c1"># Also see descr_new() in Objects/descrobject.c</span>

  1356.         <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

  1357.         <span class="bp">self</span><span class="o">.</span><span class="n">clsname</span> <span class="o">=</span> <span class="n">clsname</span>

  1358.         <span class="bp">self</span><span class="o">.</span><span class="n">offset</span> <span class="o">=</span> <span class="n">offset</span>

  1359. 

  1360.     <span class="k">def</span> <span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">objtype</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1361.         <span class="s1">&#39;Emulate member_get() in Objects/descrobject.c&#39;</span>

  1362.         <span class="c1"># Also see PyMember_GetOne() in Python/structmember.c</span>

  1363.         <span class="k">if</span> <span class="n">obj</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1364.             <span class="k">return</span> <span class="bp">self</span>

  1365.         <span class="n">value</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">_slotvalues</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">offset</span><span class="p">]</span>

  1366.         <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="n">null</span><span class="p">:</span>

  1367.             <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  1368.         <span class="k">return</span> <span class="n">value</span>

  1369. 

  1370.     <span class="k">def</span> <span class="fm">__set__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  1371.         <span class="s1">&#39;Emulate member_set() in Objects/descrobject.c&#39;</span>

  1372.         <span class="n">obj</span><span class="o">.</span><span class="n">_slotvalues</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">offset</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>

  1373. 

  1374.     <span class="k">def</span> <span class="fm">__delete__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">):</span>

  1375.         <span class="s1">&#39;Emulate member_delete() in Objects/descrobject.c&#39;</span>

  1376.         <span class="n">value</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">_slotvalues</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">offset</span><span class="p">]</span>

  1377.         <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="n">null</span><span class="p">:</span>

  1378.             <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  1379.         <span class="n">obj</span><span class="o">.</span><span class="n">_slotvalues</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">offset</span><span class="p">]</span> <span class="o">=</span> <span class="n">null</span>

  1380. 

  1381.     <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1382.         <span class="s1">&#39;Emulate member_repr() in Objects/descrobject.c&#39;</span>

  1383.         <span class="k">return</span> <span class="sa">f</span><span class="s1">&#39;&lt;Member </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">!r}</span><span class="s1"> of </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">clsname</span><span class="si">!r}</span><span class="s1">&gt;&#39;</span>

  1384. </pre></div>

  1385. </div>

  1386. <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">type.__new__()</span></code> method takes care of adding member objects to class

  1387. variables:</p>

  1388. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Type</span><span class="p">(</span><span class="nb">type</span><span class="p">):</span>

  1389.     <span class="s1">&#39;Simulate how the type metaclass adds member objects for slots&#39;</span>

  1390. 

  1391.     <span class="k">def</span> <span class="fm">__new__</span><span class="p">(</span><span class="n">mcls</span><span class="p">,</span> <span class="n">clsname</span><span class="p">,</span> <span class="n">bases</span><span class="p">,</span> <span class="n">mapping</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1392.         <span class="s1">&#39;Emulate type_new() in Objects/typeobject.c&#39;</span>

  1393.         <span class="c1"># type_new() calls PyTypeReady() which calls add_methods()</span>

  1394.         <span class="n">slot_names</span> <span class="o">=</span> <span class="n">mapping</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;slot_names&#39;</span><span class="p">,</span> <span class="p">[])</span>

  1395.         <span class="k">for</span> <span class="n">offset</span><span class="p">,</span> <span class="n">name</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">slot_names</span><span class="p">):</span>

  1396.             <span class="n">mapping</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">Member</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">clsname</span><span class="p">,</span> <span class="n">offset</span><span class="p">)</span>

  1397.         <span class="k">return</span> <span class="nb">type</span><span class="o">.</span><span class="fm">__new__</span><span class="p">(</span><span class="n">mcls</span><span class="p">,</span> <span class="n">clsname</span><span class="p">,</span> <span class="n">bases</span><span class="p">,</span> <span class="n">mapping</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  1398. </pre></div>

  1399. </div>

  1400. <p>The <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__new__()</span></code></a> method takes care of creating instances that have

  1401. slots instead of an instance dictionary.  Here is a rough simulation in pure

  1402. Python:</p>

  1403. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Object</span><span class="p">:</span>

  1404.     <span class="s1">&#39;Simulate how object.__new__() allocates memory for __slots__&#39;</span>

  1405. 

  1406.     <span class="k">def</span> <span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</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">kwargs</span><span class="p">):</span>

  1407.         <span class="s1">&#39;Emulate object_new() in Objects/typeobject.c&#39;</span>

  1408.         <span class="n">inst</span> <span class="o">=</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">)</span>

  1409.         <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="s1">&#39;slot_names&#39;</span><span class="p">):</span>

  1410.             <span class="n">empty_slots</span> <span class="o">=</span> <span class="p">[</span><span class="n">null</span><span class="p">]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="bp">cls</span><span class="o">.</span><span class="n">slot_names</span><span class="p">)</span>

  1411.             <span class="nb">object</span><span class="o">.</span><span class="fm">__setattr__</span><span class="p">(</span><span class="n">inst</span><span class="p">,</span> <span class="s1">&#39;_slotvalues&#39;</span><span class="p">,</span> <span class="n">empty_slots</span><span class="p">)</span>

  1412.         <span class="k">return</span> <span class="n">inst</span>

  1413. 

  1414.     <span class="k">def</span> <span class="fm">__setattr__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  1415.         <span class="s1">&#39;Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c&#39;</span>

  1416.         <span class="bp">cls</span> <span class="o">=</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>

  1417.         <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="s1">&#39;slot_names&#39;</span><span class="p">)</span> <span class="ow">and</span> <span class="n">name</span> <span class="ow">not</span> <span class="ow">in</span> <span class="bp">cls</span><span class="o">.</span><span class="n">slot_names</span><span class="p">:</span>

  1418.             <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span>

  1419.                 <span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="bp">cls</span><span class="o">.</span><span class="vm">__name__</span><span class="si">!r}</span><span class="s1"> object has no attribute </span><span class="si">{</span><span class="n">name</span><span class="si">!r}</span><span class="s1">&#39;</span>

  1420.             <span class="p">)</span>

  1421.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__setattr__</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  1422. 

  1423.     <span class="k">def</span> <span class="fm">__delattr__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  1424.         <span class="s1">&#39;Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c&#39;</span>

  1425.         <span class="bp">cls</span> <span class="o">=</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>

  1426.         <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="s1">&#39;slot_names&#39;</span><span class="p">)</span> <span class="ow">and</span> <span class="n">name</span> <span class="ow">not</span> <span class="ow">in</span> <span class="bp">cls</span><span class="o">.</span><span class="n">slot_names</span><span class="p">:</span>

  1427.             <span class="k">raise</span> <span class="ne">AttributeError</span><span class="p">(</span>

  1428.                 <span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="bp">cls</span><span class="o">.</span><span class="vm">__name__</span><span class="si">!r}</span><span class="s1"> object has no attribute </span><span class="si">{</span><span class="n">name</span><span class="si">!r}</span><span class="s1">&#39;</span>

  1429.             <span class="p">)</span>

  1430.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__delattr__</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>

  1431. </pre></div>

  1432. </div>

  1433. <p>To use the simulation in a real class, just inherit from <code class="xref py py-class docutils literal notranslate"><span class="pre">Object</span></code> and

  1434. set the <a class="reference internal" href="../glossary.html#term-metaclass"><span class="xref std std-term">metaclass</span></a> to <code class="xref py py-class docutils literal notranslate"><span class="pre">Type</span></code>:</p>

  1435. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">H</span><span class="p">(</span><span class="n">Object</span><span class="p">,</span> <span class="n">metaclass</span><span class="o">=</span><span class="n">Type</span><span class="p">):</span>

  1436.     <span class="s1">&#39;Instance variables stored in slots&#39;</span>

  1437. 

  1438.     <span class="n">slot_names</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;x&#39;</span><span class="p">,</span> <span class="s1">&#39;y&#39;</span><span class="p">]</span>

  1439. 

  1440.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>

  1441.         <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">x</span>

  1442.         <span class="bp">self</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="n">y</span>

  1443. </pre></div>

  1444. </div>

  1445. <p>At this point, the metaclass has loaded member objects for <em>x</em> and <em>y</em>:</p>

  1446. <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="nn">pprint</span> <span class="kn">import</span> <span class="n">pp</span>

  1447. <span class="gp">&gt;&gt;&gt; </span><span class="n">pp</span><span class="p">(</span><span class="nb">dict</span><span class="p">(</span><span class="nb">vars</span><span class="p">(</span><span class="n">H</span><span class="p">)))</span>

  1448. <span class="go">{&#39;__module__&#39;: &#39;__main__&#39;,</span>

  1449. <span class="go"> &#39;__doc__&#39;: &#39;Instance variables stored in slots&#39;,</span>

  1450. <span class="go"> &#39;slot_names&#39;: [&#39;x&#39;, &#39;y&#39;],</span>

  1451. <span class="go"> &#39;__init__&#39;: &lt;function H.__init__ at 0x7fb5d302f9d0&gt;,</span>

  1452. <span class="go"> &#39;x&#39;: &lt;Member &#39;x&#39; of &#39;H&#39;&gt;,</span>

  1453. <span class="go"> &#39;y&#39;: &lt;Member &#39;y&#39; of &#39;H&#39;&gt;}</span>

  1454. </pre></div>

  1455. </div>

  1456. <p>When instances are created, they have a <code class="docutils literal notranslate"><span class="pre">slot_values</span></code> list where the

  1457. attributes are stored:</p>

  1458. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">h</span> <span class="o">=</span> <span class="n">H</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>

  1459. <span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>

  1460. <span class="go">{&#39;_slotvalues&#39;: [10, 20]}</span>

  1461. <span class="gp">&gt;&gt;&gt; </span><span class="n">h</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="mi">55</span>

  1462. <span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>

  1463. <span class="go">{&#39;_slotvalues&#39;: [55, 20]}</span>

  1464. </pre></div>

  1465. </div>

  1466. <p>Misspelled or unassigned attributes will raise an exception:</p>

  1467. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">h</span><span class="o">.</span><span class="n">xz</span>

  1468. <span class="gt">Traceback (most recent call last):</span>

  1469. <span class="w">    </span><span class="o">...</span>

  1470. <span class="gr">AttributeError</span>: <span class="n">&#39;H&#39; object has no attribute &#39;xz&#39;</span>

  1471. </pre></div>

  1472. </div>

  1473. </section>

  1474. </section>

  1475. </section>

  1476. 

  1477. 

  1478.             <div class="clearer"></div>

  1479.           </div>

  1480.         </div>

  1481.       </div>

  1482.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  1483.         <div class="sphinxsidebarwrapper">

  1484.   <div>

  1485.     <h3><a href="../contents.html">Table of Contents</a></h3>

  1486.     <ul>

  1487. <li><a class="reference internal" href="#">Descriptor Guide</a><ul>

  1488. <li><a class="reference internal" href="#primer">Primer</a><ul>

  1489. <li><a class="reference internal" href="#simple-example-a-descriptor-that-returns-a-constant">Simple example: A descriptor that returns a constant</a></li>

  1490. <li><a class="reference internal" href="#dynamic-lookups">Dynamic lookups</a></li>

  1491. <li><a class="reference internal" href="#managed-attributes">Managed attributes</a></li>

  1492. <li><a class="reference internal" href="#customized-names">Customized names</a></li>

  1493. <li><a class="reference internal" href="#closing-thoughts">Closing thoughts</a></li>

  1494. </ul>

  1495. </li>

  1496. <li><a class="reference internal" href="#complete-practical-example">Complete Practical Example</a><ul>

  1497. <li><a class="reference internal" href="#validator-class">Validator class</a></li>

  1498. <li><a class="reference internal" href="#custom-validators">Custom validators</a></li>

  1499. <li><a class="reference internal" href="#practical-application">Practical application</a></li>

  1500. </ul>

  1501. </li>

  1502. <li><a class="reference internal" href="#technical-tutorial">Technical Tutorial</a><ul>

  1503. <li><a class="reference internal" href="#abstract">Abstract</a></li>

  1504. <li><a class="reference internal" href="#definition-and-introduction">Definition and introduction</a></li>

  1505. <li><a class="reference internal" href="#descriptor-protocol">Descriptor protocol</a></li>

  1506. <li><a class="reference internal" href="#overview-of-descriptor-invocation">Overview of descriptor invocation</a></li>

  1507. <li><a class="reference internal" href="#invocation-from-an-instance">Invocation from an instance</a></li>

  1508. <li><a class="reference internal" href="#invocation-from-a-class">Invocation from a class</a></li>

  1509. <li><a class="reference internal" href="#invocation-from-super">Invocation from super</a></li>

  1510. <li><a class="reference internal" href="#summary-of-invocation-logic">Summary of invocation logic</a></li>

  1511. <li><a class="reference internal" href="#automatic-name-notification">Automatic name notification</a></li>

  1512. <li><a class="reference internal" href="#orm-example">ORM example</a></li>

  1513. </ul>

  1514. </li>

  1515. <li><a class="reference internal" href="#pure-python-equivalents">Pure Python Equivalents</a><ul>

  1516. <li><a class="reference internal" href="#properties">Properties</a></li>

  1517. <li><a class="reference internal" href="#functions-and-methods">Functions and methods</a></li>

  1518. <li><a class="reference internal" href="#kinds-of-methods">Kinds of methods</a></li>

  1519. <li><a class="reference internal" href="#static-methods">Static methods</a></li>

  1520. <li><a class="reference internal" href="#class-methods">Class methods</a></li>

  1521. <li><a class="reference internal" href="#member-objects-and-slots">Member objects and __slots__</a></li>

  1522. </ul>

  1523. </li>

  1524. </ul>

  1525. </li>

  1526. </ul>

  1527. 

  1528.   </div>

  1529.   <div>

  1530.     <h4>Previous topic</h4>

  1531.     <p class="topless"><a href="curses.html"

  1532.                           title="previous chapter">Curses Programming with Python</a></p>

  1533.   </div>

  1534.   <div>

  1535.     <h4>Next topic</h4>

  1536.     <p class="topless"><a href="gdb_helpers.html"

  1537.                           title="next chapter">Debugging C API extensions and CPython Internals with GDB</a></p>

  1538.   </div>

  1539.   <div role="note" aria-label="source link">

  1540.     <h3>This Page</h3>

  1541.     <ul class="this-page-menu">

  1542.       <li><a href="../bugs.html">Report a Bug</a></li>

  1543.       <li>

  1544.         <a href="https://github.com/python/cpython/blob/main/Doc/howto/descriptor.rst"

  1545.             rel="nofollow">Show Source

  1546.         </a>

  1547.       </li>

  1548.     </ul>

  1549.   </div>

  1550.         </div>

  1551. <div id="sidebarbutton" title="Collapse sidebar">

  1552. <span>«</span>

  1553. </div>

  1554. 

  1555.       </div>

  1556.       <div class="clearer"></div>

  1557.     </div>  

  1558.     <div class="related" role="navigation" aria-label="related navigation">

  1559.       <h3>Navigation</h3>

  1560.       <ul>

  1561.         <li class="right" style="margin-right: 10px">

  1562.           <a href="../genindex.html" title="General Index"

  1563.              >index</a></li>

  1564.         <li class="right" >

  1565.           <a href="../py-modindex.html" title="Python Module Index"

  1566.              >modules</a> |</li>

  1567.         <li class="right" >

  1568.           <a href="gdb_helpers.html" title="Debugging C API extensions and CPython Internals with GDB"

  1569.              >next</a> |</li>

  1570.         <li class="right" >

  1571.           <a href="curses.html" title="Curses Programming with Python"

  1572.              >previous</a> |</li>

  1573. 

  1574.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  1575.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  1576.           <li class="switchers">

  1577.             <div class="language_switcher_placeholder"></div>

  1578.             <div class="version_switcher_placeholder"></div>

  1579.           </li>

  1580.           <li>

  1581.               

  1582.           </li>

  1583.     <li id="cpython-language-and-version">

  1584.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  1585.     </li>

  1586. 

  1587.           <li class="nav-item nav-item-1"><a href="index.html" >Python HOWTOs</a> &#187;</li>

  1588.         <li class="nav-item nav-item-this"><a href="">Descriptor Guide</a></li>

  1589.                 <li class="right">

  1590.                     

  1591. 

  1592.     <div class="inline-search" role="search">

  1593.         <form class="inline-search" action="../search.html" method="get">

  1594.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  1595.           <input type="submit" value="Go" />

  1596.         </form>

  1597.     </div>

  1598.                      |

  1599.                 </li>

  1600.             <li class="right">

  1601. <label class="theme-selector-label">

  1602.     Theme

  1603.     <select class="theme-selector" oninput="activateTheme(this.value)">

  1604.         <option value="auto" selected>Auto</option>

  1605.         <option value="light">Light</option>

  1606.         <option value="dark">Dark</option>

  1607.     </select>

  1608. </label> |</li>

  1609.             

  1610.       </ul>

  1611.     </div>  

  1612.     <div class="footer">

  1613.     &copy; 

  1614.       <a href="../copyright.html">

  1615.     

  1616.     Copyright

  1617.     

  1618.       </a>

  1619.      2001-2024, Python Software Foundation.

  1620.     <br />

  1621.     This page is licensed under the Python Software Foundation License Version 2.

  1622.     <br />

  1623.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  1624.     <br />

  1625.     

  1626.       See <a href="/license.html">History and License</a> for more information.<br />

  1627.     

  1628.     

  1629.     <br />

  1630. 

  1631.     The Python Software Foundation is a non-profit corporation.

  1632. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  1633. <br />

  1634.     <br />

  1635.       Last updated on Apr 09, 2024 (13:47 UTC).

  1636.     

  1637.       <a href="/bugs.html">Found a bug</a>?

  1638.     

  1639.     <br />

  1640. 

  1641.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  1642.     </div>

  1643. 

  1644.   </body>

  1645. </html>
上海开阖软件有限公司 沪ICP备12045867号-1