Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
關注 1
收藏 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
目錄樹: 0f75e31513
分支列表 標籤
${ item.name }
建立分支 ${ searchTerm }
從 '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/reference/datamodel.html

3657 line
395KB
原始文件 Blame 歷史記錄 

  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="3. Data model" />

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

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

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

  11. <meta property="og:description" content="Objects, values and types: Objects are Python’s abstraction for data. All data in a Python program is represented by objects or by relations between objects. (In a sense, and in conformance to Von ..." />

  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="Objects, values and types: Objects are Python’s abstraction for data. All data in a Python program is represented by objects or by relations between objects. (In a sense, and in conformance to Von ..." />

  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>3. Data model &#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="4. Execution model" href="executionmodel.html" />

  39.     <link rel="prev" title="2. Lexical analysis" href="lexical_analysis.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/reference/datamodel.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="#">3. Data model</a><ul>

  99. <li><a class="reference internal" href="#objects-values-and-types">3.1. Objects, values and types</a></li>

  100. <li><a class="reference internal" href="#the-standard-type-hierarchy">3.2. The standard type hierarchy</a><ul>

  101. <li><a class="reference internal" href="#none">3.2.1. None</a></li>

  102. <li><a class="reference internal" href="#notimplemented">3.2.2. NotImplemented</a></li>

  103. <li><a class="reference internal" href="#ellipsis">3.2.3. Ellipsis</a></li>

  104. <li><a class="reference internal" href="#numbers-number">3.2.4. <code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Number</span></code></a><ul>

  105. <li><a class="reference internal" href="#numbers-integral">3.2.4.1. <code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Integral</span></code></a></li>

  106. <li><a class="reference internal" href="#numbers-real-float">3.2.4.2. <code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Real</span></code> (<code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code>)</a></li>

  107. <li><a class="reference internal" href="#numbers-complex-complex">3.2.4.3. <code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Complex</span></code> (<code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code>)</a></li>

  108. </ul>

  109. </li>

  110. <li><a class="reference internal" href="#sequences">3.2.5. Sequences</a><ul>

  111. <li><a class="reference internal" href="#immutable-sequences">3.2.5.1. Immutable sequences</a></li>

  112. <li><a class="reference internal" href="#mutable-sequences">3.2.5.2. Mutable sequences</a></li>

  113. </ul>

  114. </li>

  115. <li><a class="reference internal" href="#set-types">3.2.6. Set types</a></li>

  116. <li><a class="reference internal" href="#mappings">3.2.7. Mappings</a><ul>

  117. <li><a class="reference internal" href="#dictionaries">3.2.7.1. Dictionaries</a></li>

  118. </ul>

  119. </li>

  120. <li><a class="reference internal" href="#callable-types">3.2.8. Callable types</a><ul>

  121. <li><a class="reference internal" href="#user-defined-functions">3.2.8.1. User-defined functions</a><ul>

  122. <li><a class="reference internal" href="#special-read-only-attributes">3.2.8.1.1. Special read-only attributes</a></li>

  123. <li><a class="reference internal" href="#special-writable-attributes">3.2.8.1.2. Special writable attributes</a></li>

  124. </ul>

  125. </li>

  126. <li><a class="reference internal" href="#instance-methods">3.2.8.2. Instance methods</a></li>

  127. <li><a class="reference internal" href="#generator-functions">3.2.8.3. Generator functions</a></li>

  128. <li><a class="reference internal" href="#coroutine-functions">3.2.8.4. Coroutine functions</a></li>

  129. <li><a class="reference internal" href="#asynchronous-generator-functions">3.2.8.5. Asynchronous generator functions</a></li>

  130. <li><a class="reference internal" href="#built-in-functions">3.2.8.6. Built-in functions</a></li>

  131. <li><a class="reference internal" href="#built-in-methods">3.2.8.7. Built-in methods</a></li>

  132. <li><a class="reference internal" href="#classes">3.2.8.8. Classes</a></li>

  133. <li><a class="reference internal" href="#class-instances">3.2.8.9. Class Instances</a></li>

  134. </ul>

  135. </li>

  136. <li><a class="reference internal" href="#modules">3.2.9. Modules</a></li>

  137. <li><a class="reference internal" href="#custom-classes">3.2.10. Custom classes</a></li>

  138. <li><a class="reference internal" href="#id3">3.2.11. Class instances</a></li>

  139. <li><a class="reference internal" href="#i-o-objects-also-known-as-file-objects">3.2.12. I/O objects (also known as file objects)</a></li>

  140. <li><a class="reference internal" href="#internal-types">3.2.13. Internal types</a><ul>

  141. <li><a class="reference internal" href="#code-objects">3.2.13.1. Code objects</a><ul>

  142. <li><a class="reference internal" href="#index-58">3.2.13.1.1. Special read-only attributes</a></li>

  143. <li><a class="reference internal" href="#methods-on-code-objects">3.2.13.1.2. Methods on code objects</a></li>

  144. </ul>

  145. </li>

  146. <li><a class="reference internal" href="#frame-objects">3.2.13.2. Frame objects</a><ul>

  147. <li><a class="reference internal" href="#index-64">3.2.13.2.1. Special read-only attributes</a></li>

  148. <li><a class="reference internal" href="#index-65">3.2.13.2.2. Special writable attributes</a></li>

  149. <li><a class="reference internal" href="#frame-object-methods">3.2.13.2.3. Frame object methods</a></li>

  150. </ul>

  151. </li>

  152. <li><a class="reference internal" href="#traceback-objects">3.2.13.3. Traceback objects</a></li>

  153. <li><a class="reference internal" href="#slice-objects">3.2.13.4. Slice objects</a></li>

  154. <li><a class="reference internal" href="#static-method-objects">3.2.13.5. Static method objects</a></li>

  155. <li><a class="reference internal" href="#class-method-objects">3.2.13.6. Class method objects</a></li>

  156. </ul>

  157. </li>

  158. </ul>

  159. </li>

  160. <li><a class="reference internal" href="#special-method-names">3.3. Special method names</a><ul>

  161. <li><a class="reference internal" href="#basic-customization">3.3.1. Basic customization</a></li>

  162. <li><a class="reference internal" href="#customizing-attribute-access">3.3.2. Customizing attribute access</a><ul>

  163. <li><a class="reference internal" href="#customizing-module-attribute-access">3.3.2.1. Customizing module attribute access</a></li>

  164. <li><a class="reference internal" href="#implementing-descriptors">3.3.2.2. Implementing Descriptors</a></li>

  165. <li><a class="reference internal" href="#invoking-descriptors">3.3.2.3. Invoking Descriptors</a></li>

  166. <li><a class="reference internal" href="#slots">3.3.2.4. __slots__</a></li>

  167. </ul>

  168. </li>

  169. <li><a class="reference internal" href="#customizing-class-creation">3.3.3. Customizing class creation</a><ul>

  170. <li><a class="reference internal" href="#metaclasses">3.3.3.1. Metaclasses</a></li>

  171. <li><a class="reference internal" href="#resolving-mro-entries">3.3.3.2. Resolving MRO entries</a></li>

  172. <li><a class="reference internal" href="#determining-the-appropriate-metaclass">3.3.3.3. Determining the appropriate metaclass</a></li>

  173. <li><a class="reference internal" href="#preparing-the-class-namespace">3.3.3.4. Preparing the class namespace</a></li>

  174. <li><a class="reference internal" href="#executing-the-class-body">3.3.3.5. Executing the class body</a></li>

  175. <li><a class="reference internal" href="#creating-the-class-object">3.3.3.6. Creating the class object</a></li>

  176. <li><a class="reference internal" href="#uses-for-metaclasses">3.3.3.7. Uses for metaclasses</a></li>

  177. </ul>

  178. </li>

  179. <li><a class="reference internal" href="#customizing-instance-and-subclass-checks">3.3.4. Customizing instance and subclass checks</a></li>

  180. <li><a class="reference internal" href="#emulating-generic-types">3.3.5. Emulating generic types</a><ul>

  181. <li><a class="reference internal" href="#the-purpose-of-class-getitem">3.3.5.1. The purpose of <em>__class_getitem__</em></a></li>

  182. <li><a class="reference internal" href="#class-getitem-versus-getitem">3.3.5.2. <em>__class_getitem__</em> versus <em>__getitem__</em></a></li>

  183. </ul>

  184. </li>

  185. <li><a class="reference internal" href="#emulating-callable-objects">3.3.6. Emulating callable objects</a></li>

  186. <li><a class="reference internal" href="#emulating-container-types">3.3.7. Emulating container types</a></li>

  187. <li><a class="reference internal" href="#emulating-numeric-types">3.3.8. Emulating numeric types</a></li>

  188. <li><a class="reference internal" href="#with-statement-context-managers">3.3.9. With Statement Context Managers</a></li>

  189. <li><a class="reference internal" href="#customizing-positional-arguments-in-class-pattern-matching">3.3.10. Customizing positional arguments in class pattern matching</a></li>

  190. <li><a class="reference internal" href="#emulating-buffer-types">3.3.11. Emulating buffer types</a></li>

  191. <li><a class="reference internal" href="#special-method-lookup">3.3.12. Special method lookup</a></li>

  192. </ul>

  193. </li>

  194. <li><a class="reference internal" href="#coroutines">3.4. Coroutines</a><ul>

  195. <li><a class="reference internal" href="#awaitable-objects">3.4.1. Awaitable Objects</a></li>

  196. <li><a class="reference internal" href="#coroutine-objects">3.4.2. Coroutine Objects</a></li>

  197. <li><a class="reference internal" href="#asynchronous-iterators">3.4.3. Asynchronous Iterators</a></li>

  198. <li><a class="reference internal" href="#asynchronous-context-managers">3.4.4. Asynchronous Context Managers</a></li>

  199. </ul>

  200. </li>

  201. </ul>

  202. </li>

  203. </ul>

  204. 

  205.   </div>

  206.   <div>

  207.     <h4>Previous topic</h4>

  208.     <p class="topless"><a href="lexical_analysis.html"

  209.                           title="previous chapter"><span class="section-number">2. </span>Lexical analysis</a></p>

  210.   </div>

  211.   <div>

  212.     <h4>Next topic</h4>

  213.     <p class="topless"><a href="executionmodel.html"

  214.                           title="next chapter"><span class="section-number">4. </span>Execution model</a></p>

  215.   </div>

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

  217.     <h3>This Page</h3>

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

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

  220.       <li>

  221.         <a href="https://github.com/python/cpython/blob/main/Doc/reference/datamodel.rst"

  222.             rel="nofollow">Show Source

  223.         </a>

  224.       </li>

  225.     </ul>

  226.   </div>

  227.         </nav>

  228.     </div>

  229. </div>

  230. 

  231.   

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

  233.       <h3>Navigation</h3>

  234.       <ul>

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

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

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

  238.         <li class="right" >

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

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

  241.         <li class="right" >

  242.           <a href="executionmodel.html" title="4. Execution model"

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

  244.         <li class="right" >

  245.           <a href="lexical_analysis.html" title="2. Lexical analysis"

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

  247. 

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

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

  250.           <li class="switchers">

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

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

  253.           </li>

  254.           <li>

  255.               

  256.           </li>

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

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

  259.     </li>

  260. 

  261.           <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Python Language Reference</a> &#187;</li>

  262.         <li class="nav-item nav-item-this"><a href=""><span class="section-number">3. </span>Data model</a></li>

  263.                 <li class="right">

  264.                     

  265. 

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

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

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

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

  270.         </form>

  271.     </div>

  272.                      |

  273.                 </li>

  274.             <li class="right">

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

  276.     Theme

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

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

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

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

  281.     </select>

  282. </label> |</li>

  283.             

  284.       </ul>

  285.     </div>    

  286. 

  287.     <div class="document">

  288.       <div class="documentwrapper">

  289.         <div class="bodywrapper">

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

  291.             

  292.   <section id="data-model">

  293. <span id="datamodel"></span><h1><span class="section-number">3. </span>Data model<a class="headerlink" href="#data-model" title="Link to this heading">¶</a></h1>

  294. <section id="objects-values-and-types">

  295. <span id="objects"></span><h2><span class="section-number">3.1. </span>Objects, values and types<a class="headerlink" href="#objects-values-and-types" title="Link to this heading">¶</a></h2>

  296. <p id="index-0"><em class="dfn">Objects</em> are Python’s abstraction for data.  All data in a Python program

  297. is represented by objects or by relations between objects. (In a sense, and in

  298. conformance to Von Neumann’s model of a “stored program computer”, code is also

  299. represented by objects.)</p>

  300. <span class="target" id="index-1"></span><p>Every object has an identity, a type and a value.  An object’s <em>identity</em> never

  301. changes once it has been created; you may think of it as the object’s address in

  302. memory.  The <a class="reference internal" href="expressions.html#is"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span></code></a> operator compares the identity of two objects; the

  303. <a class="reference internal" href="../library/functions.html#id" title="id"><code class="xref py py-func docutils literal notranslate"><span class="pre">id()</span></code></a> function returns an integer representing its identity.</p>

  304. <div class="impl-detail compound">

  305. <p><strong>CPython implementation detail:</strong> For CPython, <code class="docutils literal notranslate"><span class="pre">id(x)</span></code> is the memory address where <code class="docutils literal notranslate"><span class="pre">x</span></code> is stored.</p>

  306. </div>

  307. <p>An object’s type determines the operations that the object supports (e.g., “does

  308. it have a length?”) and also defines the possible values for objects of that

  309. type.  The <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal notranslate"><span class="pre">type()</span></code></a> function returns an object’s type (which is an object

  310. itself).  Like its identity, an object’s <em class="dfn">type</em> is also unchangeable.

  311. <a class="footnote-reference brackets" href="#id17" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p>

  312. <p>The <em>value</em> of some objects can change.  Objects whose value can

  313. change are said to be <em>mutable</em>; objects whose value is unchangeable once they

  314. are created are called <em>immutable</em>. (The value of an immutable container object

  315. that contains a reference to a mutable object can change when the latter’s value

  316. is changed; however the container is still considered immutable, because the

  317. collection of objects it contains cannot be changed.  So, immutability is not

  318. strictly the same as having an unchangeable value, it is more subtle.) An

  319. object’s mutability is determined by its type; for instance, numbers, strings

  320. and tuples are immutable, while dictionaries and lists are mutable.</p>

  321. <p id="index-2">Objects are never explicitly destroyed; however, when they become unreachable

  322. they may be garbage-collected.  An implementation is allowed to postpone garbage

  323. collection or omit it altogether — it is a matter of implementation quality

  324. how garbage collection is implemented, as long as no objects are collected that

  325. are still reachable.</p>

  326. <div class="impl-detail compound">

  327. <p><strong>CPython implementation detail:</strong> CPython currently uses a reference-counting scheme with (optional) delayed

  328. detection of cyclically linked garbage, which collects most objects as soon

  329. as they become unreachable, but is not guaranteed to collect garbage

  330. containing circular references.  See the documentation of the <a class="reference internal" href="../library/gc.html#module-gc" title="gc: Interface to the cycle-detecting garbage collector."><code class="xref py py-mod docutils literal notranslate"><span class="pre">gc</span></code></a>

  331. module for information on controlling the collection of cyclic garbage.

  332. Other implementations act differently and CPython may change.

  333. Do not depend on immediate finalization of objects when they become

  334. unreachable (so you should always close files explicitly).</p>

  335. </div>

  336. <p>Note that the use of the implementation’s tracing or debugging facilities may

  337. keep objects alive that would normally be collectable. Also note that catching

  338. an exception with a <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a>…<a class="reference internal" href="compound_stmts.html#except"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except</span></code></a> statement may keep

  339. objects alive.</p>

  340. <p>Some objects contain references to “external” resources such as open files or

  341. windows.  It is understood that these resources are freed when the object is

  342. garbage-collected, but since garbage collection is not guaranteed to happen,

  343. such objects also provide an explicit way to release the external resource,

  344. usually a <code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code> method. Programs are strongly recommended to explicitly

  345. close such objects.  The <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a>…<a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> statement

  346. and the <a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement provide convenient ways to do this.</p>

  347. <p id="index-3">Some objects contain references to other objects; these are called <em>containers</em>.

  348. Examples of containers are tuples, lists and dictionaries.  The references are

  349. part of a container’s value.  In most cases, when we talk about the value of a

  350. container, we imply the values, not the identities of the contained objects;

  351. however, when we talk about the mutability of a container, only the identities

  352. of the immediately contained objects are implied.  So, if an immutable container

  353. (like a tuple) contains a reference to a mutable object, its value changes if

  354. that mutable object is changed.</p>

  355. <p>Types affect almost all aspects of object behavior.  Even the importance of

  356. object identity is affected in some sense: for immutable types, operations that

  357. compute new values may actually return a reference to any existing object with

  358. the same type and value, while for mutable objects this is not allowed.  E.g.,

  359. after <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">1;</span> <span class="pre">b</span> <span class="pre">=</span> <span class="pre">1</span></code>, <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> may or may not refer to the same object

  360. with the value one, depending on the implementation, but after <code class="docutils literal notranslate"><span class="pre">c</span> <span class="pre">=</span> <span class="pre">[];</span> <span class="pre">d</span> <span class="pre">=</span>

  361. <span class="pre">[]</span></code>, <code class="docutils literal notranslate"><span class="pre">c</span></code> and <code class="docutils literal notranslate"><span class="pre">d</span></code> are guaranteed to refer to two different, unique, newly

  362. created empty lists. (Note that <code class="docutils literal notranslate"><span class="pre">c</span> <span class="pre">=</span> <span class="pre">d</span> <span class="pre">=</span> <span class="pre">[]</span></code> assigns the same object to both

  363. <code class="docutils literal notranslate"><span class="pre">c</span></code> and <code class="docutils literal notranslate"><span class="pre">d</span></code>.)</p>

  364. </section>

  365. <section id="the-standard-type-hierarchy">

  366. <span id="types"></span><h2><span class="section-number">3.2. </span>The standard type hierarchy<a class="headerlink" href="#the-standard-type-hierarchy" title="Link to this heading">¶</a></h2>

  367. <p id="index-4">Below is a list of the types that are built into Python.  Extension modules

  368. (written in C, Java, or other languages, depending on the implementation) can

  369. define additional types.  Future versions of Python may add types to the type

  370. hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.),

  371. although such additions will often be provided via the standard library instead.</p>

  372. <p id="index-5">Some of the type descriptions below contain a paragraph listing ‘special

  373. attributes.’  These are attributes that provide access to the implementation and

  374. are not intended for general use.  Their definition may change in the future.</p>

  375. <section id="none">

  376. <h3><span class="section-number">3.2.1. </span>None<a class="headerlink" href="#none" title="Link to this heading">¶</a></h3>

  377. <p id="index-6">This type has a single value.  There is a single object with this value. This

  378. object is accessed through the built-in name <code class="docutils literal notranslate"><span class="pre">None</span></code>. It is used to signify the

  379. absence of a value in many situations, e.g., it is returned from functions that

  380. don’t explicitly return anything. Its truth value is false.</p>

  381. </section>

  382. <section id="notimplemented">

  383. <h3><span class="section-number">3.2.2. </span>NotImplemented<a class="headerlink" href="#notimplemented" title="Link to this heading">¶</a></h3>

  384. <p id="index-7">This type has a single value.  There is a single object with this value. This

  385. object is accessed through the built-in name <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a>. Numeric methods

  386. and rich comparison methods should return this value if they do not implement the

  387. operation for the operands provided.  (The interpreter will then try the

  388. reflected operation, or some other fallback, depending on the operator.)  It

  389. should not be evaluated in a boolean context.</p>

  390. <p>See

  391. <a class="reference internal" href="../library/numbers.html#implementing-the-arithmetic-operations"><span class="std std-ref">Implementing the arithmetic operations</span></a>

  392. for more details.</p>

  393. <div class="versionchanged">

  394. <p><span class="versionmodified changed">Changed in version 3.9: </span>Evaluating <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a> in a boolean context is deprecated. While

  395. it currently evaluates as true, it will emit a <a class="reference internal" href="../library/exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a>.

  396. It will raise a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> in a future version of Python.</p>

  397. </div>

  398. </section>

  399. <section id="ellipsis">

  400. <h3><span class="section-number">3.2.3. </span>Ellipsis<a class="headerlink" href="#ellipsis" title="Link to this heading">¶</a></h3>

  401. <p id="index-8">This type has a single value.  There is a single object with this value. This

  402. object is accessed through the literal <code class="docutils literal notranslate"><span class="pre">...</span></code> or the built-in name

  403. <code class="docutils literal notranslate"><span class="pre">Ellipsis</span></code>.  Its truth value is true.</p>

  404. </section>

  405. <section id="numbers-number">

  406. <h3><span class="section-number">3.2.4. </span><a class="reference internal" href="../library/numbers.html#numbers.Number" title="numbers.Number"><code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Number</span></code></a><a class="headerlink" href="#numbers-number" title="Link to this heading">¶</a></h3>

  407. <p id="index-9">These are created by numeric literals and returned as results by arithmetic

  408. operators and arithmetic built-in functions.  Numeric objects are immutable;

  409. once created their value never changes.  Python numbers are of course strongly

  410. related to mathematical numbers, but subject to the limitations of numerical

  411. representation in computers.</p>

  412. <p>The string representations of the numeric classes, computed by

  413. <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a> and <a class="reference internal" href="#object.__str__" title="object.__str__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code></a>, have the following

  414. properties:</p>

  415. <ul class="simple">

  416. <li><p>They are valid numeric literals which, when passed to their

  417. class constructor, produce an object having the value of the

  418. original numeric.</p></li>

  419. <li><p>The representation is in base 10, when possible.</p></li>

  420. <li><p>Leading zeros, possibly excepting a single zero before a

  421. decimal point, are not shown.</p></li>

  422. <li><p>Trailing zeros, possibly excepting a single zero after a

  423. decimal point, are not shown.</p></li>

  424. <li><p>A sign is shown only when the number is negative.</p></li>

  425. </ul>

  426. <p>Python distinguishes between integers, floating point numbers, and complex

  427. numbers:</p>

  428. <section id="numbers-integral">

  429. <h4><span class="section-number">3.2.4.1. </span><a class="reference internal" href="../library/numbers.html#numbers.Integral" title="numbers.Integral"><code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Integral</span></code></a><a class="headerlink" href="#numbers-integral" title="Link to this heading">¶</a></h4>

  430. <p id="index-10">These represent elements from the mathematical set of integers (positive and

  431. negative).</p>

  432. <div class="admonition note">

  433. <p class="admonition-title">Note</p>

  434. <p id="index-11">The rules for integer representation are intended to give the most meaningful

  435. interpretation of shift and mask operations involving negative integers.</p>

  436. </div>

  437. <p>There are two types of integers:</p>

  438. <dl>

  439. <dt>Integers (<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>)</dt><dd><p>These represent numbers in an unlimited range, subject to available (virtual)

  440. memory only.  For the purpose of shift and mask operations, a binary

  441. representation is assumed, and negative numbers are represented in a variant of

  442. 2’s complement which gives the illusion of an infinite string of sign bits

  443. extending to the left.</p>

  444. </dd>

  445. <dt>Booleans (<a class="reference internal" href="../library/functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a>)</dt><dd><p id="index-12">These represent the truth values False and True.  The two objects representing

  446. the values <code class="docutils literal notranslate"><span class="pre">False</span></code> and <code class="docutils literal notranslate"><span class="pre">True</span></code> are the only Boolean objects. The Boolean type is a

  447. subtype of the integer type, and Boolean values behave like the values 0 and 1,

  448. respectively, in almost all contexts, the exception being that when converted to

  449. a string, the strings <code class="docutils literal notranslate"><span class="pre">&quot;False&quot;</span></code> or <code class="docutils literal notranslate"><span class="pre">&quot;True&quot;</span></code> are returned, respectively.</p>

  450. </dd>

  451. </dl>

  452. </section>

  453. <section id="numbers-real-float">

  454. <h4><span class="section-number">3.2.4.2. </span><a class="reference internal" href="../library/numbers.html#numbers.Real" title="numbers.Real"><code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Real</span></code></a> (<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>)<a class="headerlink" href="#numbers-real-float" title="Link to this heading">¶</a></h4>

  455. <p id="index-13">These represent machine-level double precision floating point numbers. You are

  456. at the mercy of the underlying machine architecture (and C or Java

  457. implementation) for the accepted range and handling of overflow. Python does not

  458. support single-precision floating point numbers; the savings in processor and

  459. memory usage that are usually the reason for using these are dwarfed by the

  460. overhead of using objects in Python, so there is no reason to complicate the

  461. language with two kinds of floating point numbers.</p>

  462. </section>

  463. <section id="numbers-complex-complex">

  464. <h4><span class="section-number">3.2.4.3. </span><a class="reference internal" href="../library/numbers.html#numbers.Complex" title="numbers.Complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Complex</span></code></a> (<a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a>)<a class="headerlink" href="#numbers-complex-complex" title="Link to this heading">¶</a></h4>

  465. <p id="index-14">These represent complex numbers as a pair of machine-level double precision

  466. floating point numbers.  The same caveats apply as for floating point numbers.

  467. The real and imaginary parts of a complex number <code class="docutils literal notranslate"><span class="pre">z</span></code> can be retrieved through

  468. the read-only attributes <code class="docutils literal notranslate"><span class="pre">z.real</span></code> and <code class="docutils literal notranslate"><span class="pre">z.imag</span></code>.</p>

  469. </section>

  470. </section>

  471. <section id="sequences">

  472. <h3><span class="section-number">3.2.5. </span>Sequences<a class="headerlink" href="#sequences" title="Link to this heading">¶</a></h3>

  473. <p id="index-15">These represent finite ordered sets indexed by non-negative numbers. The

  474. built-in function <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a> returns the number of items of a sequence. When

  475. the length of a sequence is <em>n</em>, the index set contains the numbers 0, 1,

  476. …, <em>n</em>-1.  Item <em>i</em> of sequence <em>a</em> is selected by <code class="docutils literal notranslate"><span class="pre">a[i]</span></code>. Some sequences,

  477. including built-in sequences, interpret negative subscripts by adding the

  478. sequence length. For example, <code class="docutils literal notranslate"><span class="pre">a[-2]</span></code> equals <code class="docutils literal notranslate"><span class="pre">a[n-2]</span></code>, the second to last

  479. item of sequence a with length <code class="docutils literal notranslate"><span class="pre">n</span></code>.</p>

  480. <p id="index-16">Sequences also support slicing: <code class="docutils literal notranslate"><span class="pre">a[i:j]</span></code> selects all items with index <em>k</em> such

  481. that <em>i</em> <code class="docutils literal notranslate"><span class="pre">&lt;=</span></code> <em>k</em> <code class="docutils literal notranslate"><span class="pre">&lt;</span></code> <em>j</em>.  When used as an expression, a slice is a

  482. sequence of the same type. The comment above about negative indexes also applies

  483. to negative slice positions.</p>

  484. <p>Some sequences also support “extended slicing” with a third “step” parameter:

  485. <code class="docutils literal notranslate"><span class="pre">a[i:j:k]</span></code> selects all items of <em>a</em> with index <em>x</em> where <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">i</span> <span class="pre">+</span> <span class="pre">n*k</span></code>, <em>n</em>

  486. <code class="docutils literal notranslate"><span class="pre">&gt;=</span></code> <code class="docutils literal notranslate"><span class="pre">0</span></code> and <em>i</em> <code class="docutils literal notranslate"><span class="pre">&lt;=</span></code> <em>x</em> <code class="docutils literal notranslate"><span class="pre">&lt;</span></code> <em>j</em>.</p>

  487. <p>Sequences are distinguished according to their mutability:</p>

  488. <section id="immutable-sequences">

  489. <h4><span class="section-number">3.2.5.1. </span>Immutable sequences<a class="headerlink" href="#immutable-sequences" title="Link to this heading">¶</a></h4>

  490. <p id="index-17">An object of an immutable sequence type cannot change once it is created.  (If

  491. the object contains references to other objects, these other objects may be

  492. mutable and may be changed; however, the collection of objects directly

  493. referenced by an immutable object cannot change.)</p>

  494. <p>The following types are immutable sequences:</p>

  495. <dl id="index-18">

  496. <dt>Strings</dt><dd><p id="index-19">A string is a sequence of values that represent Unicode code points.

  497. All the code points in the range <code class="docutils literal notranslate"><span class="pre">U+0000</span> <span class="pre">-</span> <span class="pre">U+10FFFF</span></code> can be

  498. represented in a string.  Python doesn’t have a <span class="c-expr sig sig-inline c"><span class="kt">char</span></span> type;

  499. instead, every code point in the string is represented as a string

  500. object with length <code class="docutils literal notranslate"><span class="pre">1</span></code>.  The built-in function <a class="reference internal" href="../library/functions.html#ord" title="ord"><code class="xref py py-func docutils literal notranslate"><span class="pre">ord()</span></code></a>

  501. converts a code point from its string form to an integer in the

  502. range <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">-</span> <span class="pre">10FFFF</span></code>; <a class="reference internal" href="../library/functions.html#chr" title="chr"><code class="xref py py-func docutils literal notranslate"><span class="pre">chr()</span></code></a> converts an integer in the range

  503. <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">-</span> <span class="pre">10FFFF</span></code> to the corresponding length <code class="docutils literal notranslate"><span class="pre">1</span></code> string object.

  504. <a class="reference internal" href="../library/stdtypes.html#str.encode" title="str.encode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.encode()</span></code></a> can be used to convert 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> to

  505. <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> using the given text encoding, and

  506. <a class="reference internal" href="../library/stdtypes.html#bytes.decode" title="bytes.decode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bytes.decode()</span></code></a> can be used to achieve the opposite.</p>

  507. </dd>

  508. <dt>Tuples</dt><dd><p id="index-20">The items of a tuple are arbitrary Python objects. Tuples of two or

  509. more items are formed by comma-separated lists of expressions.  A tuple

  510. of one item (a ‘singleton’) can be formed by affixing a comma to an

  511. expression (an expression by itself does not create a tuple, since

  512. parentheses must be usable for grouping of expressions).  An empty

  513. tuple can be formed by an empty pair of parentheses.</p>

  514. </dd>

  515. <dt>Bytes</dt><dd><p id="index-21">A bytes object is an immutable array.  The items are 8-bit bytes,

  516. represented by integers in the range 0 &lt;= x &lt; 256.  Bytes literals

  517. (like <code class="docutils literal notranslate"><span class="pre">b'abc'</span></code>) and the built-in <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-func docutils literal notranslate"><span class="pre">bytes()</span></code></a> constructor

  518. can be used to create bytes objects.  Also, bytes objects can be

  519. decoded to strings via the <a class="reference internal" href="../library/stdtypes.html#bytes.decode" title="bytes.decode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">decode()</span></code></a> method.</p>

  520. </dd>

  521. </dl>

  522. </section>

  523. <section id="mutable-sequences">

  524. <h4><span class="section-number">3.2.5.2. </span>Mutable sequences<a class="headerlink" href="#mutable-sequences" title="Link to this heading">¶</a></h4>

  525. <p id="index-22">Mutable sequences can be changed after they are created.  The subscription and

  526. slicing notations can be used as the target of assignment and <a class="reference internal" href="simple_stmts.html#del"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">del</span></code></a>

  527. (delete) statements.</p>

  528. <div class="admonition note">

  529. <p class="admonition-title">Note</p>

  530. <p id="index-24"><span id="index-23"></span>The <a class="reference internal" href="../library/collections.html#module-collections" title="collections: Container datatypes"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections</span></code></a> and <a class="reference internal" href="../library/array.html#module-array" title="array: Space efficient arrays of uniformly typed numeric values."><code class="xref py py-mod docutils literal notranslate"><span class="pre">array</span></code></a> module provide

  531. additional examples of mutable sequence types.</p>

  532. </div>

  533. <p>There are currently two intrinsic mutable sequence types:</p>

  534. <dl>

  535. <dt>Lists</dt><dd><p id="index-25">The items of a list are arbitrary Python objects.  Lists are formed by

  536. placing a comma-separated list of expressions in square brackets. (Note

  537. that there are no special cases needed to form lists of length 0 or 1.)</p>

  538. </dd>

  539. <dt>Byte Arrays</dt><dd><p id="index-26">A bytearray object is a mutable array. They are created by the built-in

  540. <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-func docutils literal notranslate"><span class="pre">bytearray()</span></code></a> constructor.  Aside from being mutable

  541. (and hence unhashable), byte arrays otherwise provide the same interface

  542. and functionality as immutable <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> objects.</p>

  543. </dd>

  544. </dl>

  545. </section>

  546. </section>

  547. <section id="set-types">

  548. <h3><span class="section-number">3.2.6. </span>Set types<a class="headerlink" href="#set-types" title="Link to this heading">¶</a></h3>

  549. <p id="index-27">These represent unordered, finite sets of unique, immutable objects. As such,

  550. they cannot be indexed by any subscript. However, they can be iterated over, and

  551. the built-in function <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a> returns the number of items in a set. Common

  552. uses for sets are fast membership testing, removing duplicates from a sequence,

  553. and computing mathematical operations such as intersection, union, difference,

  554. and symmetric difference.</p>

  555. <p>For set elements, the same immutability rules apply as for dictionary keys. Note

  556. that numeric types obey the normal rules for numeric comparison: if two numbers

  557. compare equal (e.g., <code class="docutils literal notranslate"><span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">1.0</span></code>), only one of them can be contained in a

  558. set.</p>

  559. <p>There are currently two intrinsic set types:</p>

  560. <dl>

  561. <dt>Sets</dt><dd><p id="index-28">These represent a mutable set. They are created by the built-in <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-func docutils literal notranslate"><span class="pre">set()</span></code></a>

  562. constructor and can be modified afterwards by several methods, such as

  563. <code class="xref py py-meth docutils literal notranslate"><span class="pre">add()</span></code>.</p>

  564. </dd>

  565. <dt>Frozen sets</dt><dd><p id="index-29">These represent an immutable set.  They are created by the built-in

  566. <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-func docutils literal notranslate"><span class="pre">frozenset()</span></code></a> constructor.  As a frozenset is immutable and

  567. <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a>, it can be used again as an element of another set, or as

  568. a dictionary key.</p>

  569. </dd>

  570. </dl>

  571. </section>

  572. <section id="mappings">

  573. <h3><span class="section-number">3.2.7. </span>Mappings<a class="headerlink" href="#mappings" title="Link to this heading">¶</a></h3>

  574. <p id="index-30">These represent finite sets of objects indexed by arbitrary index sets. The

  575. subscript notation <code class="docutils literal notranslate"><span class="pre">a[k]</span></code> selects the item indexed by <code class="docutils literal notranslate"><span class="pre">k</span></code> from the mapping

  576. <code class="docutils literal notranslate"><span class="pre">a</span></code>; this can be used in expressions and as the target of assignments or

  577. <a class="reference internal" href="simple_stmts.html#del"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">del</span></code></a> statements. The built-in function <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a> returns the number

  578. of items in a mapping.</p>

  579. <p>There is currently a single intrinsic mapping type:</p>

  580. <section id="dictionaries">

  581. <h4><span class="section-number">3.2.7.1. </span>Dictionaries<a class="headerlink" href="#dictionaries" title="Link to this heading">¶</a></h4>

  582. <p id="index-31">These represent finite sets of objects indexed by nearly arbitrary values.  The

  583. only types of values not acceptable as keys are values containing lists or

  584. dictionaries or other mutable types that are compared by value rather than by

  585. object identity, the reason being that the efficient implementation of

  586. dictionaries requires a key’s hash value to remain constant. Numeric types used

  587. for keys obey the normal rules for numeric comparison: if two numbers compare

  588. equal (e.g., <code class="docutils literal notranslate"><span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">1.0</span></code>) then they can be used interchangeably to index

  589. the same dictionary entry.</p>

  590. <p>Dictionaries preserve insertion order, meaning that keys will be produced

  591. in the same order they were added sequentially over the dictionary.

  592. Replacing an existing key does not change the order, however removing a key

  593. and re-inserting it will add it to the end instead of keeping its old place.</p>

  594. <p>Dictionaries are mutable; they can be created by the <code class="docutils literal notranslate"><span class="pre">{...}</span></code> notation (see

  595. section <a class="reference internal" href="expressions.html#dict"><span class="std std-ref">Dictionary displays</span></a>).</p>

  596. <p id="index-32">The extension modules <a class="reference internal" href="../library/dbm.html#module-dbm.ndbm" title="dbm.ndbm: The New Database Manager (Unix)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code></a> and <a class="reference internal" href="../library/dbm.html#module-dbm.gnu" title="dbm.gnu: GNU database manager (Unix)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code></a> provide

  597. additional examples of mapping types, as does the <a class="reference internal" href="../library/collections.html#module-collections" title="collections: Container datatypes"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections</span></code></a>

  598. module.</p>

  599. <div class="versionchanged">

  600. <p><span class="versionmodified changed">Changed in version 3.7: </span>Dictionaries did not preserve insertion order in versions of Python before 3.6.

  601. In CPython 3.6, insertion order was preserved, but it was considered

  602. an implementation detail at that time rather than a language guarantee.</p>

  603. </div>

  604. </section>

  605. </section>

  606. <section id="callable-types">

  607. <h3><span class="section-number">3.2.8. </span>Callable types<a class="headerlink" href="#callable-types" title="Link to this heading">¶</a></h3>

  608. <p id="index-33">These are the types to which the function call operation (see section

  609. <a class="reference internal" href="expressions.html#calls"><span class="std std-ref">Calls</span></a>) can be applied:</p>

  610. <section id="user-defined-functions">

  611. <span id="user-defined-funcs"></span><h4><span class="section-number">3.2.8.1. </span>User-defined functions<a class="headerlink" href="#user-defined-functions" title="Link to this heading">¶</a></h4>

  612. <p id="index-34">A user-defined function object is created by a function definition (see

  613. section <a class="reference internal" href="compound_stmts.html#function"><span class="std std-ref">Function definitions</span></a>).  It should be called with an argument list

  614. containing the same number of items as the function’s formal parameter

  615. list.</p>

  616. <section id="special-read-only-attributes">

  617. <h5><span class="section-number">3.2.8.1.1. </span>Special read-only attributes<a class="headerlink" href="#special-read-only-attributes" title="Link to this heading">¶</a></h5>

  618. <table class="docutils align-default" id="index-35">

  619. <thead>

  620. <tr class="row-odd"><th class="head"><p>Attribute</p></th>

  621. <th class="head"><p>Meaning</p></th>

  622. </tr>

  623. </thead>

  624. <tbody>

  625. <tr class="row-even"><td><dl class="py attribute">

  626. <dt class="sig sig-object py" id="function.__globals__">

  627. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__globals__</span></span><a class="headerlink" href="#function.__globals__" title="Link to this definition">¶</a></dt>

  628. <dd></dd></dl>

  629. 

  630. </td>

  631. <td><p>A reference to the <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dictionary</span></code></a> that holds the function’s

  632. <a class="reference internal" href="executionmodel.html#naming"><span class="std std-ref">global variables</span></a> – the global namespace of the module

  633. in which the function was defined.</p></td>

  634. </tr>

  635. <tr class="row-odd"><td><dl class="py attribute">

  636. <dt class="sig sig-object py" id="function.__closure__">

  637. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__closure__</span></span><a class="headerlink" href="#function.__closure__" title="Link to this definition">¶</a></dt>

  638. <dd></dd></dl>

  639. 

  640. </td>

  641. <td><p><code class="docutils literal notranslate"><span class="pre">None</span></code> or a <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> of cells that contain bindings for the

  642. function’s free variables.</p>

  643. <p>A cell object has the attribute <code class="docutils literal notranslate"><span class="pre">cell_contents</span></code>.

  644. This can be used to get the value of the cell, as well as set the value.</p>

  645. </td>

  646. </tr>

  647. </tbody>

  648. </table>

  649. </section>

  650. <section id="special-writable-attributes">

  651. <h5><span class="section-number">3.2.8.1.2. </span>Special writable attributes<a class="headerlink" href="#special-writable-attributes" title="Link to this heading">¶</a></h5>

  652. <p id="index-36">Most of these attributes check the type of the assigned value:</p>

  653. <table class="docutils align-default">

  654. <thead>

  655. <tr class="row-odd"><th class="head"><p>Attribute</p></th>

  656. <th class="head"><p>Meaning</p></th>

  657. </tr>

  658. </thead>

  659. <tbody>

  660. <tr class="row-even"><td><dl class="py attribute">

  661. <dt class="sig sig-object py" id="function.__doc__">

  662. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__doc__</span></span><a class="headerlink" href="#function.__doc__" title="Link to this definition">¶</a></dt>

  663. <dd></dd></dl>

  664. 

  665. </td>

  666. <td><p>The function’s documentation string, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if unavailable.

  667. Not inherited by subclasses.</p></td>

  668. </tr>

  669. <tr class="row-odd"><td><dl class="py attribute">

  670. <dt class="sig sig-object py" id="function.__name__">

  671. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__name__</span></span><a class="headerlink" href="#function.__name__" title="Link to this definition">¶</a></dt>

  672. <dd></dd></dl>

  673. 

  674. </td>

  675. <td><p>The function’s name.

  676. See also: <a class="reference internal" href="../library/stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span> <span class="pre">attributes</span></code></a>.</p></td>

  677. </tr>

  678. <tr class="row-even"><td><dl class="py attribute">

  679. <dt class="sig sig-object py" id="function.__qualname__">

  680. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__qualname__</span></span><a class="headerlink" href="#function.__qualname__" title="Link to this definition">¶</a></dt>

  681. <dd></dd></dl>

  682. 

  683. </td>

  684. <td><p>The function’s <a class="reference internal" href="../glossary.html#term-qualified-name"><span class="xref std std-term">qualified name</span></a>.

  685. See also: <a class="reference internal" href="../library/stdtypes.html#definition.__qualname__" title="definition.__qualname__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__qualname__</span> <span class="pre">attributes</span></code></a>.</p>

  686. <div class="versionadded">

  687. <p><span class="versionmodified added">New in version 3.3.</span></p>

  688. </div>

  689. </td>

  690. </tr>

  691. <tr class="row-odd"><td><dl class="py attribute">

  692. <dt class="sig sig-object py" id="function.__module__">

  693. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__module__</span></span><a class="headerlink" href="#function.__module__" title="Link to this definition">¶</a></dt>

  694. <dd></dd></dl>

  695. 

  696. </td>

  697. <td><p>The name of the module the function was defined in,

  698. or <code class="docutils literal notranslate"><span class="pre">None</span></code> if unavailable.</p></td>

  699. </tr>

  700. <tr class="row-even"><td><dl class="py attribute">

  701. <dt class="sig sig-object py" id="function.__defaults__">

  702. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__defaults__</span></span><a class="headerlink" href="#function.__defaults__" title="Link to this definition">¶</a></dt>

  703. <dd></dd></dl>

  704. 

  705. </td>

  706. <td><p>A <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> containing default <a class="reference internal" href="../glossary.html#term-parameter"><span class="xref std std-term">parameter</span></a> values

  707. for those parameters that have defaults,

  708. or <code class="docutils literal notranslate"><span class="pre">None</span></code> if no parameters have a default value.</p></td>

  709. </tr>

  710. <tr class="row-odd"><td><dl class="py attribute">

  711. <dt class="sig sig-object py" id="function.__code__">

  712. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__code__</span></span><a class="headerlink" href="#function.__code__" title="Link to this definition">¶</a></dt>

  713. <dd></dd></dl>

  714. 

  715. </td>

  716. <td><p>The <a class="reference internal" href="#code-objects"><span class="std std-ref">code object</span></a> representing

  717. the compiled function body.</p></td>

  718. </tr>

  719. <tr class="row-even"><td><dl class="py attribute">

  720. <dt class="sig sig-object py" id="function.__dict__">

  721. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__dict__</span></span><a class="headerlink" href="#function.__dict__" title="Link to this definition">¶</a></dt>

  722. <dd></dd></dl>

  723. 

  724. </td>

  725. <td><p>The namespace supporting arbitrary function attributes.

  726. See also: <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span> <span class="pre">attributes</span></code></a>.</p></td>

  727. </tr>

  728. <tr class="row-odd"><td><dl class="py attribute">

  729. <dt class="sig sig-object py" id="function.__annotations__">

  730. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__annotations__</span></span><a class="headerlink" href="#function.__annotations__" title="Link to this definition">¶</a></dt>

  731. <dd></dd></dl>

  732. 

  733. </td>

  734. <td><p>A <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dictionary</span></code></a> containing annotations of

  735. <a class="reference internal" href="../glossary.html#term-parameter"><span class="xref std std-term">parameters</span></a>.

  736. The keys of the dictionary are the parameter names,

  737. and <code class="docutils literal notranslate"><span class="pre">'return'</span></code> for the return annotation, if provided.

  738. See also: <a class="reference internal" href="../howto/annotations.html#annotations-howto"><span class="std std-ref">Annotations Best Practices</span></a>.</p></td>

  739. </tr>

  740. <tr class="row-even"><td><dl class="py attribute">

  741. <dt class="sig sig-object py" id="function.__kwdefaults__">

  742. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__kwdefaults__</span></span><a class="headerlink" href="#function.__kwdefaults__" title="Link to this definition">¶</a></dt>

  743. <dd></dd></dl>

  744. 

  745. </td>

  746. <td><p>A <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dictionary</span></code></a> containing defaults for keyword-only

  747. <a class="reference internal" href="../glossary.html#term-parameter"><span class="xref std std-term">parameters</span></a>.</p></td>

  748. </tr>

  749. <tr class="row-odd"><td><dl class="py attribute">

  750. <dt class="sig sig-object py" id="function.__type_params__">

  751. <span class="sig-prename descclassname"><span class="pre">function.</span></span><span class="sig-name descname"><span class="pre">__type_params__</span></span><a class="headerlink" href="#function.__type_params__" title="Link to this definition">¶</a></dt>

  752. <dd></dd></dl>

  753. 

  754. </td>

  755. <td><p>A <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> containing the <a class="reference internal" href="compound_stmts.html#type-params"><span class="std std-ref">type parameters</span></a> of

  756. a <a class="reference internal" href="compound_stmts.html#generic-functions"><span class="std std-ref">generic function</span></a>.</p>

  757. <div class="versionadded">

  758. <p><span class="versionmodified added">New in version 3.12.</span></p>

  759. </div>

  760. </td>

  761. </tr>

  762. </tbody>

  763. </table>

  764. <p>Function objects also support getting and setting arbitrary attributes, which

  765. can be used, for example, to attach metadata to functions.  Regular attribute

  766. dot-notation is used to get and set such attributes.</p>

  767. <div class="impl-detail compound">

  768. <p><strong>CPython implementation detail:</strong> CPython’s current implementation only supports function attributes

  769. on user-defined functions. Function attributes on

  770. <a class="reference internal" href="#builtin-functions"><span class="std std-ref">built-in functions</span></a> may be supported in the

  771. future.</p>

  772. </div>

  773. <p>Additional information about a function’s definition can be retrieved from its

  774. <a class="reference internal" href="#code-objects"><span class="std std-ref">code object</span></a>

  775. (accessible via the <a class="reference internal" href="#function.__code__" title="function.__code__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__code__</span></code></a> attribute).</p>

  776. </section>

  777. </section>

  778. <section id="instance-methods">

  779. <span id="id2"></span><h4><span class="section-number">3.2.8.2. </span>Instance methods<a class="headerlink" href="#instance-methods" title="Link to this heading">¶</a></h4>

  780. <p id="index-37">An instance method object combines a class, a class instance and any

  781. callable object (normally a user-defined function).</p>

  782. <p id="index-38">Special read-only attributes:</p>

  783. <table class="docutils align-default">

  784. <tbody>

  785. <tr class="row-odd"><td><dl class="py attribute">

  786. <dt class="sig sig-object py" id="method.__self__">

  787. <span class="sig-prename descclassname"><span class="pre">method.</span></span><span class="sig-name descname"><span class="pre">__self__</span></span><a class="headerlink" href="#method.__self__" title="Link to this definition">¶</a></dt>

  788. <dd></dd></dl>

  789. 

  790. </td>

  791. <td><p>Refers to the class instance object to which the method is

  792. <a class="reference internal" href="#method-binding"><span class="std std-ref">bound</span></a></p></td>

  793. </tr>

  794. <tr class="row-even"><td><dl class="py attribute">

  795. <dt class="sig sig-object py" id="method.__func__">

  796. <span class="sig-prename descclassname"><span class="pre">method.</span></span><span class="sig-name descname"><span class="pre">__func__</span></span><a class="headerlink" href="#method.__func__" title="Link to this definition">¶</a></dt>

  797. <dd></dd></dl>

  798. 

  799. </td>

  800. <td><p>Refers to the original <a class="reference internal" href="#user-defined-funcs"><span class="std std-ref">function object</span></a></p></td>

  801. </tr>

  802. <tr class="row-odd"><td><dl class="py attribute">

  803. <dt class="sig sig-object py" id="method.__doc__">

  804. <span class="sig-prename descclassname"><span class="pre">method.</span></span><span class="sig-name descname"><span class="pre">__doc__</span></span><a class="headerlink" href="#method.__doc__" title="Link to this definition">¶</a></dt>

  805. <dd></dd></dl>

  806. 

  807. </td>

  808. <td><p>The method’s documentation

  809. (same as <a class="reference internal" href="#function.__doc__" title="function.__doc__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">method.__func__.__doc__</span></code></a>).

  810. A <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">string</span></code></a> if the original function had a docstring, else

  811. <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></td>

  812. </tr>

  813. <tr class="row-even"><td><dl class="py attribute">

  814. <dt class="sig sig-object py" id="method.__name__">

  815. <span class="sig-prename descclassname"><span class="pre">method.</span></span><span class="sig-name descname"><span class="pre">__name__</span></span><a class="headerlink" href="#method.__name__" title="Link to this definition">¶</a></dt>

  816. <dd></dd></dl>

  817. 

  818. </td>

  819. <td><p>The name of the method

  820. (same as <a class="reference internal" href="#function.__name__" title="function.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">method.__func__.__name__</span></code></a>)</p></td>

  821. </tr>

  822. <tr class="row-odd"><td><dl class="py attribute">

  823. <dt class="sig sig-object py" id="method.__module__">

  824. <span class="sig-prename descclassname"><span class="pre">method.</span></span><span class="sig-name descname"><span class="pre">__module__</span></span><a class="headerlink" href="#method.__module__" title="Link to this definition">¶</a></dt>

  825. <dd></dd></dl>

  826. 

  827. </td>

  828. <td><p>The name of the module the method was defined in, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if

  829. unavailable.</p></td>

  830. </tr>

  831. </tbody>

  832. </table>

  833. <p>Methods also support accessing (but not setting) the arbitrary function

  834. attributes on the underlying <a class="reference internal" href="#user-defined-funcs"><span class="std std-ref">function object</span></a>.</p>

  835. <p>User-defined method objects may be created when getting an attribute of a

  836. class (perhaps via an instance of that class), if that attribute is a

  837. user-defined <a class="reference internal" href="#user-defined-funcs"><span class="std std-ref">function object</span></a> or a

  838. <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-class docutils literal notranslate"><span class="pre">classmethod</span></code></a> object.</p>

  839. <p id="method-binding">When an instance method object is created by retrieving a user-defined

  840. <a class="reference internal" href="#user-defined-funcs"><span class="std std-ref">function object</span></a> from a class via one of its

  841. instances, its <a class="reference internal" href="#method.__self__" title="method.__self__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__self__</span></code></a> attribute is the instance, and the

  842. method object is said to be <em>bound</em>.  The new method’s <a class="reference internal" href="#method.__func__" title="method.__func__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__func__</span></code></a>

  843. attribute is the original function object.</p>

  844. <p>When an instance method object is created by retrieving a <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-class docutils literal notranslate"><span class="pre">classmethod</span></code></a>

  845. object from a class or instance, its <a class="reference internal" href="#method.__self__" title="method.__self__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__self__</span></code></a> attribute is the

  846. class itself, and its <a class="reference internal" href="#method.__func__" title="method.__func__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__func__</span></code></a> attribute is the function object

  847. underlying the class method.</p>

  848. <p>When an instance method object is called, the underlying function

  849. (<a class="reference internal" href="#method.__func__" title="method.__func__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__func__</span></code></a>) is called, inserting the class instance

  850. (<a class="reference internal" href="#method.__self__" title="method.__self__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__self__</span></code></a>) in front of the argument list.  For instance, when

  851. <code class="xref py py-class docutils literal notranslate"><span class="pre">C</span></code> is a class which contains a definition for a function

  852. <code class="xref py py-meth docutils literal notranslate"><span class="pre">f()</span></code>, and <code class="docutils literal notranslate"><span class="pre">x</span></code> is an instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">C</span></code>, calling <code class="docutils literal notranslate"><span class="pre">x.f(1)</span></code> is

  853. equivalent to calling <code class="docutils literal notranslate"><span class="pre">C.f(x,</span> <span class="pre">1)</span></code>.</p>

  854. <p>When an instance method object is derived from a <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-class docutils literal notranslate"><span class="pre">classmethod</span></code></a> object, the

  855. “class instance” stored in <a class="reference internal" href="#method.__self__" title="method.__self__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__self__</span></code></a> will actually be the class

  856. itself, so that calling either <code class="docutils literal notranslate"><span class="pre">x.f(1)</span></code> or <code class="docutils literal notranslate"><span class="pre">C.f(1)</span></code> is equivalent to

  857. calling <code class="docutils literal notranslate"><span class="pre">f(C,1)</span></code> where <code class="docutils literal notranslate"><span class="pre">f</span></code> is the underlying function.</p>

  858. <p>Note that the transformation from <a class="reference internal" href="#user-defined-funcs"><span class="std std-ref">function object</span></a>

  859. to instance method

  860. object happens each time the attribute is retrieved from the instance.  In

  861. some cases, a fruitful optimization is to assign the attribute to a local

  862. variable and call that local variable. Also notice that this

  863. transformation only happens for user-defined functions; other callable

  864. objects (and all non-callable objects) are retrieved without

  865. transformation.  It is also important to note that user-defined functions

  866. which are attributes of a class instance are not converted to bound

  867. methods; this <em>only</em> happens when the function is an attribute of the

  868. class.</p>

  869. </section>

  870. <section id="generator-functions">

  871. <h4><span class="section-number">3.2.8.3. </span>Generator functions<a class="headerlink" href="#generator-functions" title="Link to this heading">¶</a></h4>

  872. <p id="index-39">A function or method which uses the <a class="reference internal" href="simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> statement (see section

  873. <a class="reference internal" href="simple_stmts.html#yield"><span class="std std-ref">The yield statement</span></a>) is called a <em class="dfn">generator function</em>.  Such a function, when

  874. called, always returns an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> object which can be used to

  875. execute the body of the function:  calling the iterator’s

  876. <a class="reference internal" href="../library/stdtypes.html#iterator.__next__" title="iterator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">iterator.__next__()</span></code></a> method will cause the function to execute until

  877. it provides a value using the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code> statement.  When the

  878. function executes a <a class="reference internal" href="simple_stmts.html#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a> statement or falls off the end, a

  879. <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> exception is raised and the iterator will have

  880. reached the end of the set of values to be returned.</p>

  881. </section>

  882. <section id="coroutine-functions">

  883. <h4><span class="section-number">3.2.8.4. </span>Coroutine functions<a class="headerlink" href="#coroutine-functions" title="Link to this heading">¶</a></h4>

  884. <p id="index-40">A function or method which is defined using <a class="reference internal" href="compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> is called

  885. a <em class="dfn">coroutine function</em>.  Such a function, when called, returns a

  886. <a class="reference internal" href="../glossary.html#term-coroutine"><span class="xref std std-term">coroutine</span></a> object.  It may contain <a class="reference internal" href="expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a> expressions,

  887. as well as <a class="reference internal" href="compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a> and <a class="reference internal" href="compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a> statements. See

  888. also the <a class="reference internal" href="#coroutine-objects"><span class="std std-ref">Coroutine Objects</span></a> section.</p>

  889. </section>

  890. <section id="asynchronous-generator-functions">

  891. <h4><span class="section-number">3.2.8.5. </span>Asynchronous generator functions<a class="headerlink" href="#asynchronous-generator-functions" title="Link to this heading">¶</a></h4>

  892. <p id="index-41">A function or method which is defined using <a class="reference internal" href="compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> and

  893. which uses the <a class="reference internal" href="simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a> statement is called a

  894. <em class="dfn">asynchronous generator function</em>.  Such a function, when called,

  895. returns an <a class="reference internal" href="../glossary.html#term-asynchronous-iterator"><span class="xref std std-term">asynchronous iterator</span></a> object which can be used in an

  896. <a class="reference internal" href="compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a> statement to execute the body of the function.</p>

  897. <p>Calling the asynchronous iterator’s

  898. <a class="reference internal" href="#object.__anext__" title="object.__anext__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">aiterator.__anext__</span></code></a> method

  899. will return an <a class="reference internal" href="../glossary.html#term-awaitable"><span class="xref std std-term">awaitable</span></a> which when awaited

  900. will execute until it provides a value using the <a class="reference internal" href="simple_stmts.html#yield"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">yield</span></code></a>

  901. expression.  When the function executes an empty <a class="reference internal" href="simple_stmts.html#return"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">return</span></code></a>

  902. statement or falls off the end, a <a class="reference internal" href="../library/exceptions.html#StopAsyncIteration" title="StopAsyncIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopAsyncIteration</span></code></a> exception

  903. is raised and the asynchronous iterator will have reached the end of

  904. the set of values to be yielded.</p>

  905. </section>

  906. <section id="built-in-functions">

  907. <span id="builtin-functions"></span><h4><span class="section-number">3.2.8.6. </span>Built-in functions<a class="headerlink" href="#built-in-functions" title="Link to this heading">¶</a></h4>

  908. <p id="index-42">A built-in function object is a wrapper around a C function.  Examples of

  909. built-in functions are <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a> and <a class="reference internal" href="../library/math.html#math.sin" title="math.sin"><code class="xref py py-func docutils literal notranslate"><span class="pre">math.sin()</span></code></a> (<a class="reference internal" href="../library/math.html#module-math" title="math: Mathematical functions (sin() etc.)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">math</span></code></a> is a

  910. standard built-in module). The number and type of the arguments are

  911. determined by the C function. Special read-only attributes:</p>

  912. <ul class="simple">

  913. <li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code> is the function’s documentation string, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if

  914. unavailable. See <a class="reference internal" href="#function.__doc__" title="function.__doc__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">function.__doc__</span></code></a>.</p></li>

  915. <li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code> is the function’s name. See <a class="reference internal" href="#function.__name__" title="function.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">function.__name__</span></code></a>.</p></li>

  916. <li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">__self__</span></code> is set to <code class="docutils literal notranslate"><span class="pre">None</span></code> (but see the next item).</p></li>

  917. <li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">__module__</span></code> is the name of

  918. the module the function was defined in or <code class="docutils literal notranslate"><span class="pre">None</span></code> if unavailable.

  919. See <a class="reference internal" href="#function.__module__" title="function.__module__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">function.__module__</span></code></a>.</p></li>

  920. </ul>

  921. </section>

  922. <section id="built-in-methods">

  923. <span id="builtin-methods"></span><h4><span class="section-number">3.2.8.7. </span>Built-in methods<a class="headerlink" href="#built-in-methods" title="Link to this heading">¶</a></h4>

  924. <p id="index-43">This is really a different disguise of a built-in function, this time containing

  925. an object passed to the C function as an implicit extra argument.  An example of

  926. a built-in method is <code class="docutils literal notranslate"><span class="pre">alist.append()</span></code>, assuming <em>alist</em> is a list object. In

  927. this case, the special read-only attribute <code class="xref py py-attr docutils literal notranslate"><span class="pre">__self__</span></code> is set to the object

  928. denoted by <em>alist</em>. (The attribute has the same semantics as it does with

  929. <a class="reference internal" href="#method.__self__" title="method.__self__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">other</span> <span class="pre">instance</span> <span class="pre">methods</span></code></a>.)</p>

  930. </section>

  931. <section id="classes">

  932. <h4><span class="section-number">3.2.8.8. </span>Classes<a class="headerlink" href="#classes" title="Link to this heading">¶</a></h4>

  933. <p>Classes are callable.  These objects normally act as factories for new

  934. instances of themselves, but variations are possible for class types that

  935. override <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a>.  The arguments of the call are passed to

  936. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> and, in the typical case, to <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> to

  937. initialize the new instance.</p>

  938. </section>

  939. <section id="class-instances">

  940. <h4><span class="section-number">3.2.8.9. </span>Class Instances<a class="headerlink" href="#class-instances" title="Link to this heading">¶</a></h4>

  941. <p>Instances of arbitrary classes can be made callable by defining a

  942. <a class="reference internal" href="#object.__call__" title="object.__call__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code></a> method in their class.</p>

  943. </section>

  944. </section>

  945. <section id="modules">

  946. <h3><span class="section-number">3.2.9. </span>Modules<a class="headerlink" href="#modules" title="Link to this heading">¶</a></h3>

  947. <p id="index-44">Modules are a basic organizational unit of Python code, and are created by

  948. the <a class="reference internal" href="import.html#importsystem"><span class="std std-ref">import system</span></a> as invoked either by the

  949. <a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement, or by calling

  950. functions such as <a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.import_module()</span></code></a> and built-in

  951. <a class="reference internal" href="../library/functions.html#import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a>.  A module object has a namespace implemented by a

  952. <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dictionary</span></code></a> object (this is the dictionary referenced by the

  953. <a class="reference internal" href="#function.__globals__" title="function.__globals__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__globals__</span></code></a>

  954. attribute of functions defined in the module).  Attribute references are

  955. translated to lookups in this dictionary, e.g., <code class="docutils literal notranslate"><span class="pre">m.x</span></code> is equivalent to

  956. <code class="docutils literal notranslate"><span class="pre">m.__dict__[&quot;x&quot;]</span></code>. A module object does not contain the code object used

  957. to initialize the module (since it isn’t needed once the initialization is

  958. done).</p>

  959. <p>Attribute assignment updates the module’s namespace dictionary, e.g.,

  960. <code class="docutils literal notranslate"><span class="pre">m.x</span> <span class="pre">=</span> <span class="pre">1</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">m.__dict__[&quot;x&quot;]</span> <span class="pre">=</span> <span class="pre">1</span></code>.</p>

  961. <p id="index-45">Predefined (writable) attributes:</p>

  962. <blockquote>

  963. <div><dl class="simple">

  964. <dt><a class="reference internal" href="import.html#name__" title="__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a></dt><dd><p>The module’s name.</p>

  965. </dd>

  966. <dt><code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code></dt><dd><p>The module’s documentation string, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if

  967. unavailable.</p>

  968. </dd>

  969. <dt><a class="reference internal" href="import.html#file__" title="__file__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code></a></dt><dd><p>The pathname of the file from which the

  970. module was loaded, if it was loaded from a file.

  971. The <a class="reference internal" href="import.html#file__" title="__file__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code></a>

  972. attribute may be missing for certain types of modules, such as C modules

  973. that are statically linked into the interpreter.  For extension modules

  974. loaded dynamically from a shared library, it’s the pathname of the shared

  975. library file.</p>

  976. </dd>

  977. <dt><code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code></dt><dd><p>A dictionary containing

  978. <a class="reference internal" href="../glossary.html#term-variable-annotation"><span class="xref std std-term">variable annotations</span></a> collected during

  979. module body execution.  For best practices on working

  980. with <code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code>, please see <a class="reference internal" href="../howto/annotations.html#annotations-howto"><span class="std std-ref">Annotations Best Practices</span></a>.</p>

  981. </dd>

  982. </dl>

  983. </div></blockquote>

  984. <p id="index-46">Special read-only attribute: <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> is the module’s

  985. namespace as a dictionary object.</p>

  986. <div class="impl-detail compound">

  987. <p><strong>CPython implementation detail:</strong> Because of the way CPython clears module dictionaries, the module

  988. dictionary will be cleared when the module falls out of scope even if the

  989. dictionary still has live references.  To avoid this, copy the dictionary

  990. or keep the module around while using its dictionary directly.</p>

  991. </div>

  992. </section>

  993. <section id="custom-classes">

  994. <h3><span class="section-number">3.2.10. </span>Custom classes<a class="headerlink" href="#custom-classes" title="Link to this heading">¶</a></h3>

  995. <p>Custom class types are typically created by class definitions (see section

  996. <a class="reference internal" href="compound_stmts.html#class"><span class="std std-ref">Class definitions</span></a>).  A class has a namespace implemented by a dictionary object.

  997. Class attribute references are translated to lookups in this dictionary, e.g.,

  998. <code class="docutils literal notranslate"><span class="pre">C.x</span></code> is translated to <code class="docutils literal notranslate"><span class="pre">C.__dict__[&quot;x&quot;]</span></code> (although there are a number of

  999. hooks which allow for other means of locating attributes). When the attribute

  1000. name is not found there, the attribute search continues in the base classes.

  1001. This search of the base classes uses the C3 method resolution order which

  1002. behaves correctly even in the presence of ‘diamond’ inheritance structures

  1003. where there are multiple inheritance paths leading back to a common ancestor.

  1004. Additional details on the C3 MRO used by Python can be found in the

  1005. documentation accompanying the 2.3 release at

  1006. <a class="reference external" href="https://www.python.org/download/releases/2.3/mro/">https://www.python.org/download/releases/2.3/mro/</a>.</p>

  1007. <p id="index-47">When a class attribute reference (for class <code class="xref py py-class docutils literal notranslate"><span class="pre">C</span></code>, say) would yield a

  1008. class method object, it is transformed into an instance method object whose

  1009. <a class="reference internal" href="#method.__self__" title="method.__self__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__self__</span></code></a> attribute is <code class="xref py py-class docutils literal notranslate"><span class="pre">C</span></code>.

  1010. When it would yield a <a class="reference internal" href="../library/functions.html#staticmethod" title="staticmethod"><code class="xref py py-class docutils literal notranslate"><span class="pre">staticmethod</span></code></a> object,

  1011. it is transformed into the object wrapped by the static method

  1012. object. See section <a class="reference internal" href="#descriptors"><span class="std std-ref">Implementing Descriptors</span></a> for another way in which attributes

  1013. retrieved from a class may differ from those actually contained in its

  1014. <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>.</p>

  1015. <p id="index-48">Class attribute assignments update the class’s dictionary, never the dictionary

  1016. of a base class.</p>

  1017. <p id="index-49">A class object can be called (see above) to yield a class instance (see below).</p>

  1018. <p id="index-50">Special attributes:</p>

  1019. <blockquote>

  1020. <div><dl class="simple">

  1021. <dt><a class="reference internal" href="../library/stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a></dt><dd><p>The class name.</p>

  1022. </dd>

  1023. <dt><code class="xref py py-attr docutils literal notranslate"><span class="pre">__module__</span></code></dt><dd><p>The name of the module in which the class was defined.</p>

  1024. </dd>

  1025. <dt><a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a></dt><dd><p>The dictionary containing the class’s namespace.</p>

  1026. </dd>

  1027. <dt><a class="reference internal" href="../library/stdtypes.html#class.__bases__" title="class.__bases__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__bases__</span></code></a></dt><dd><p>A tuple containing the base classes, in the order of

  1028. their occurrence in the base class list.</p>

  1029. </dd>

  1030. <dt><code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code></dt><dd><p>The class’s documentation string, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if undefined.</p>

  1031. </dd>

  1032. <dt><code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code></dt><dd><p>A dictionary containing

  1033. <a class="reference internal" href="../glossary.html#term-variable-annotation"><span class="xref std std-term">variable annotations</span></a>

  1034. collected during class body execution.  For best practices on

  1035. working with <code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code>, please see

  1036. <a class="reference internal" href="../howto/annotations.html#annotations-howto"><span class="std std-ref">Annotations Best Practices</span></a>.</p>

  1037. </dd>

  1038. <dt><code class="xref py py-attr docutils literal notranslate"><span class="pre">__type_params__</span></code></dt><dd><p>A tuple containing the <a class="reference internal" href="compound_stmts.html#type-params"><span class="std std-ref">type parameters</span></a> of

  1039. a <a class="reference internal" href="compound_stmts.html#generic-classes"><span class="std std-ref">generic class</span></a>.</p>

  1040. </dd>

  1041. </dl>

  1042. </div></blockquote>

  1043. </section>

  1044. <section id="id3">

  1045. <h3><span class="section-number">3.2.11. </span>Class instances<a class="headerlink" href="#id3" title="Link to this heading">¶</a></h3>

  1046. <p id="index-51">A class instance is created by calling a class object (see above).  A class

  1047. instance has a namespace implemented as a dictionary which is the first place

  1048. in which attribute references are searched.  When an attribute is not found

  1049. there, and the instance’s class has an attribute by that name, the search

  1050. continues with the class attributes.  If a class attribute is found that is a

  1051. user-defined function object, it is transformed into an instance method

  1052. object whose <a class="reference internal" href="#method.__self__" title="method.__self__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__self__</span></code></a> attribute is the instance.  Static method and

  1053. class method objects are also transformed; see above under “Classes”.  See

  1054. section <a class="reference internal" href="#descriptors"><span class="std std-ref">Implementing Descriptors</span></a> for another way in which attributes of a class

  1055. retrieved via its instances may differ from the objects actually stored in

  1056. the class’s <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>.  If no class attribute is found, and the

  1057. object’s class has a <a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code></a> method, that is called to satisfy

  1058. the lookup.</p>

  1059. <p id="index-52">Attribute assignments and deletions update the instance’s dictionary, never a

  1060. class’s dictionary.  If the class has a <a class="reference internal" href="#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setattr__()</span></code></a> or

  1061. <a class="reference internal" href="#object.__delattr__" title="object.__delattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delattr__()</span></code></a> method, this is called instead of updating the instance

  1062. dictionary directly.</p>

  1063. <p id="index-53">Class instances can pretend to be numbers, sequences, or mappings if they have

  1064. methods with certain special names.  See section <a class="reference internal" href="#specialnames"><span class="std std-ref">Special method names</span></a>.</p>

  1065. <p id="index-54">Special attributes: <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> is the attribute dictionary;

  1066. <a class="reference internal" href="../library/stdtypes.html#instance.__class__" title="instance.__class__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__class__</span></code></a> is the instance’s class.</p>

  1067. </section>

  1068. <section id="i-o-objects-also-known-as-file-objects">

  1069. <h3><span class="section-number">3.2.12. </span>I/O objects (also known as file objects)<a class="headerlink" href="#i-o-objects-also-known-as-file-objects" title="Link to this heading">¶</a></h3>

  1070. <p id="index-55">A <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> represents an open file.  Various shortcuts are

  1071. available to create file objects: the <a class="reference internal" href="../library/functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> built-in function, and

  1072. also <a class="reference internal" href="../library/os.html#os.popen" title="os.popen"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.popen()</span></code></a>, <a class="reference internal" href="../library/os.html#os.fdopen" title="os.fdopen"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fdopen()</span></code></a>, and the

  1073. <a class="reference internal" href="../library/socket.html#socket.socket.makefile" title="socket.socket.makefile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">makefile()</span></code></a> method of socket objects (and perhaps by

  1074. other functions or methods provided by extension modules).</p>

  1075. <p>The objects <code class="docutils literal notranslate"><span class="pre">sys.stdin</span></code>, <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> are

  1076. initialized to file objects corresponding to the interpreter’s standard

  1077. input, output and error streams; they are all open in text mode and

  1078. therefore follow the interface defined by the <a class="reference internal" href="../library/io.html#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOBase</span></code></a>

  1079. abstract class.</p>

  1080. </section>

  1081. <section id="internal-types">

  1082. <h3><span class="section-number">3.2.13. </span>Internal types<a class="headerlink" href="#internal-types" title="Link to this heading">¶</a></h3>

  1083. <p id="index-56">A few types used internally by the interpreter are exposed to the user. Their

  1084. definitions may change with future versions of the interpreter, but they are

  1085. mentioned here for completeness.</p>

  1086. <section id="code-objects">

  1087. <span id="id4"></span><h4><span class="section-number">3.2.13.1. </span>Code objects<a class="headerlink" href="#code-objects" title="Link to this heading">¶</a></h4>

  1088. <p id="index-57">Code objects represent <em>byte-compiled</em> executable Python code, or <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a>.

  1089. The difference between a code object and a function object is that the function

  1090. object contains an explicit reference to the function’s globals (the module in

  1091. which it was defined), while a code object contains no context; also the default

  1092. argument values are stored in the function object, not in the code object

  1093. (because they represent values calculated at run-time).  Unlike function

  1094. objects, code objects are immutable and contain no references (directly or

  1095. indirectly) to mutable objects.</p>

  1096. <section id="index-58">

  1097. <span id="id5"></span><h5><span class="section-number">3.2.13.1.1. </span>Special read-only attributes<a class="headerlink" href="#index-58" title="Link to this heading">¶</a></h5>

  1098. <table class="docutils align-default">

  1099. <tbody>

  1100. <tr class="row-odd"><td><dl class="py attribute">

  1101. <dt class="sig sig-object py" id="codeobject.co_name">

  1102. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_name</span></span><a class="headerlink" href="#codeobject.co_name" title="Link to this definition">¶</a></dt>

  1103. <dd></dd></dl>

  1104. 

  1105. </td>

  1106. <td><p>The function name</p></td>

  1107. </tr>

  1108. <tr class="row-even"><td><dl class="py attribute">

  1109. <dt class="sig sig-object py" id="codeobject.co_qualname">

  1110. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_qualname</span></span><a class="headerlink" href="#codeobject.co_qualname" title="Link to this definition">¶</a></dt>

  1111. <dd></dd></dl>

  1112. 

  1113. </td>

  1114. <td><p>The fully qualified function name</p>

  1115. <div class="versionadded">

  1116. <p><span class="versionmodified added">New in version 3.11.</span></p>

  1117. </div>

  1118. </td>

  1119. </tr>

  1120. <tr class="row-odd"><td><dl class="py attribute">

  1121. <dt class="sig sig-object py" id="codeobject.co_argcount">

  1122. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_argcount</span></span><a class="headerlink" href="#codeobject.co_argcount" title="Link to this definition">¶</a></dt>

  1123. <dd></dd></dl>

  1124. 

  1125. </td>

  1126. <td><p>The total number of positional <a class="reference internal" href="../glossary.html#term-parameter"><span class="xref std std-term">parameters</span></a>

  1127. (including positional-only parameters and parameters with default values)

  1128. that the function has</p></td>

  1129. </tr>

  1130. <tr class="row-even"><td><dl class="py attribute">

  1131. <dt class="sig sig-object py" id="codeobject.co_posonlyargcount">

  1132. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_posonlyargcount</span></span><a class="headerlink" href="#codeobject.co_posonlyargcount" title="Link to this definition">¶</a></dt>

  1133. <dd></dd></dl>

  1134. 

  1135. </td>

  1136. <td><p>The number of positional-only <a class="reference internal" href="../glossary.html#term-parameter"><span class="xref std std-term">parameters</span></a>

  1137. (including arguments with default values) that the function has</p></td>

  1138. </tr>

  1139. <tr class="row-odd"><td><dl class="py attribute">

  1140. <dt class="sig sig-object py" id="codeobject.co_kwonlyargcount">

  1141. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_kwonlyargcount</span></span><a class="headerlink" href="#codeobject.co_kwonlyargcount" title="Link to this definition">¶</a></dt>

  1142. <dd></dd></dl>

  1143. 

  1144. </td>

  1145. <td><p>The number of keyword-only <a class="reference internal" href="../glossary.html#term-parameter"><span class="xref std std-term">parameters</span></a>

  1146. (including arguments with default values) that the function has</p></td>

  1147. </tr>

  1148. <tr class="row-even"><td><dl class="py attribute">

  1149. <dt class="sig sig-object py" id="codeobject.co_nlocals">

  1150. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_nlocals</span></span><a class="headerlink" href="#codeobject.co_nlocals" title="Link to this definition">¶</a></dt>

  1151. <dd></dd></dl>

  1152. 

  1153. </td>

  1154. <td><p>The number of <a class="reference internal" href="executionmodel.html#naming"><span class="std std-ref">local variables</span></a> used by the function

  1155. (including parameters)</p></td>

  1156. </tr>

  1157. <tr class="row-odd"><td><dl class="py attribute">

  1158. <dt class="sig sig-object py" id="codeobject.co_varnames">

  1159. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_varnames</span></span><a class="headerlink" href="#codeobject.co_varnames" title="Link to this definition">¶</a></dt>

  1160. <dd></dd></dl>

  1161. 

  1162. </td>

  1163. <td><p>A <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> containing the names of the local variables in the

  1164. function (starting with the parameter names)</p></td>

  1165. </tr>

  1166. <tr class="row-even"><td><dl class="py attribute">

  1167. <dt class="sig sig-object py" id="codeobject.co_cellvars">

  1168. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_cellvars</span></span><a class="headerlink" href="#codeobject.co_cellvars" title="Link to this definition">¶</a></dt>

  1169. <dd></dd></dl>

  1170. 

  1171. </td>

  1172. <td><p>A <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> containing the names of <a class="reference internal" href="executionmodel.html#naming"><span class="std std-ref">local variables</span></a>

  1173. that are referenced by nested functions inside the function</p></td>

  1174. </tr>

  1175. <tr class="row-odd"><td><dl class="py attribute">

  1176. <dt class="sig sig-object py" id="codeobject.co_freevars">

  1177. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_freevars</span></span><a class="headerlink" href="#codeobject.co_freevars" title="Link to this definition">¶</a></dt>

  1178. <dd></dd></dl>

  1179. 

  1180. </td>

  1181. <td><p>A <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> containing the names of free variables in the function</p></td>

  1182. </tr>

  1183. <tr class="row-even"><td><dl class="py attribute">

  1184. <dt class="sig sig-object py" id="codeobject.co_code">

  1185. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_code</span></span><a class="headerlink" href="#codeobject.co_code" title="Link to this definition">¶</a></dt>

  1186. <dd></dd></dl>

  1187. 

  1188. </td>

  1189. <td><p>A string representing the sequence of <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> instructions in

  1190. the function</p></td>

  1191. </tr>

  1192. <tr class="row-odd"><td><dl class="py attribute">

  1193. <dt class="sig sig-object py" id="codeobject.co_consts">

  1194. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_consts</span></span><a class="headerlink" href="#codeobject.co_consts" title="Link to this definition">¶</a></dt>

  1195. <dd></dd></dl>

  1196. 

  1197. </td>

  1198. <td><p>A <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> containing the literals used by the <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> in

  1199. the function</p></td>

  1200. </tr>

  1201. <tr class="row-even"><td><dl class="py attribute">

  1202. <dt class="sig sig-object py" id="codeobject.co_names">

  1203. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_names</span></span><a class="headerlink" href="#codeobject.co_names" title="Link to this definition">¶</a></dt>

  1204. <dd></dd></dl>

  1205. 

  1206. </td>

  1207. <td><p>A <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> containing the names used by the <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> in

  1208. the function</p></td>

  1209. </tr>

  1210. <tr class="row-odd"><td><dl class="py attribute">

  1211. <dt class="sig sig-object py" id="codeobject.co_filename">

  1212. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_filename</span></span><a class="headerlink" href="#codeobject.co_filename" title="Link to this definition">¶</a></dt>

  1213. <dd></dd></dl>

  1214. 

  1215. </td>

  1216. <td><p>The name of the file from which the code was compiled</p></td>

  1217. </tr>

  1218. <tr class="row-even"><td><dl class="py attribute">

  1219. <dt class="sig sig-object py" id="codeobject.co_firstlineno">

  1220. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_firstlineno</span></span><a class="headerlink" href="#codeobject.co_firstlineno" title="Link to this definition">¶</a></dt>

  1221. <dd></dd></dl>

  1222. 

  1223. </td>

  1224. <td><p>The line number of the first line of the function</p></td>

  1225. </tr>

  1226. <tr class="row-odd"><td><dl class="py attribute">

  1227. <dt class="sig sig-object py" id="codeobject.co_lnotab">

  1228. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_lnotab</span></span><a class="headerlink" href="#codeobject.co_lnotab" title="Link to this definition">¶</a></dt>

  1229. <dd></dd></dl>

  1230. 

  1231. </td>

  1232. <td><p>A string encoding the mapping from <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> offsets to line

  1233. numbers. For details, see the source code of the interpreter.</p>

  1234. <div class="deprecated">

  1235. <p><span class="versionmodified deprecated">Deprecated since version 3.12: </span>This attribute of code objects is deprecated, and may be removed in

  1236. Python 3.14.</p>

  1237. </div>

  1238. </td>

  1239. </tr>

  1240. <tr class="row-even"><td><dl class="py attribute">

  1241. <dt class="sig sig-object py" id="codeobject.co_stacksize">

  1242. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_stacksize</span></span><a class="headerlink" href="#codeobject.co_stacksize" title="Link to this definition">¶</a></dt>

  1243. <dd></dd></dl>

  1244. 

  1245. </td>

  1246. <td><p>The required stack size of the code object</p></td>

  1247. </tr>

  1248. <tr class="row-odd"><td><dl class="py attribute">

  1249. <dt class="sig sig-object py" id="codeobject.co_flags">

  1250. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_flags</span></span><a class="headerlink" href="#codeobject.co_flags" title="Link to this definition">¶</a></dt>

  1251. <dd></dd></dl>

  1252. 

  1253. </td>

  1254. <td><p>An <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">integer</span></code></a> encoding a number of flags for the

  1255. interpreter.</p></td>

  1256. </tr>

  1257. </tbody>

  1258. </table>

  1259. <p id="index-59">The following flag bits are defined for <a class="reference internal" href="#codeobject.co_flags" title="codeobject.co_flags"><code class="xref py py-attr docutils literal notranslate"><span class="pre">co_flags</span></code></a>:

  1260. bit <code class="docutils literal notranslate"><span class="pre">0x04</span></code> is set if

  1261. the function uses the <code class="docutils literal notranslate"><span class="pre">*arguments</span></code> syntax to accept an arbitrary number of

  1262. positional arguments; bit <code class="docutils literal notranslate"><span class="pre">0x08</span></code> is set if the function uses the

  1263. <code class="docutils literal notranslate"><span class="pre">**keywords</span></code> syntax to accept arbitrary keyword arguments; bit <code class="docutils literal notranslate"><span class="pre">0x20</span></code> is set

  1264. if the function is a generator. See <a class="reference internal" href="../library/inspect.html#inspect-module-co-flags"><span class="std std-ref">Code Objects Bit Flags</span></a> for details

  1265. on the semantics of each flags that might be present.</p>

  1266. <p>Future feature declarations (<code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span> <span class="pre">division</span></code>) also use bits

  1267. in <a class="reference internal" href="#codeobject.co_flags" title="codeobject.co_flags"><code class="xref py py-attr docutils literal notranslate"><span class="pre">co_flags</span></code></a> to indicate whether a code object was compiled with a

  1268. particular feature enabled: bit <code class="docutils literal notranslate"><span class="pre">0x2000</span></code> is set if the function was compiled

  1269. with future division enabled; bits <code class="docutils literal notranslate"><span class="pre">0x10</span></code> and <code class="docutils literal notranslate"><span class="pre">0x1000</span></code> were used in earlier

  1270. versions of Python.</p>

  1271. <p>Other bits in <a class="reference internal" href="#codeobject.co_flags" title="codeobject.co_flags"><code class="xref py py-attr docutils literal notranslate"><span class="pre">co_flags</span></code></a> are reserved for internal use.</p>

  1272. <p id="index-60">If a code object represents a function, the first item in

  1273. <a class="reference internal" href="#codeobject.co_consts" title="codeobject.co_consts"><code class="xref py py-attr docutils literal notranslate"><span class="pre">co_consts</span></code></a> is

  1274. the documentation string of the function, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if undefined.</p>

  1275. </section>

  1276. <section id="methods-on-code-objects">

  1277. <h5><span class="section-number">3.2.13.1.2. </span>Methods on code objects<a class="headerlink" href="#methods-on-code-objects" title="Link to this heading">¶</a></h5>

  1278. <dl class="py method">

  1279. <dt class="sig sig-object py" id="codeobject.co_positions">

  1280. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_positions</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#codeobject.co_positions" title="Link to this definition">¶</a></dt>

  1281. <dd><p>Returns an iterable over the source code positions of each <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a>

  1282. instruction in the code object.</p>

  1283. <p>The iterator returns <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>s containing the <code class="docutils literal notranslate"><span class="pre">(start_line,</span> <span class="pre">end_line,</span>

  1284. <span class="pre">start_column,</span> <span class="pre">end_column)</span></code>. The <em>i-th</em> tuple corresponds to the

  1285. position of the source code that compiled to the <em>i-th</em> instruction.

  1286. Column information is 0-indexed utf-8 byte offsets on the given source

  1287. line.</p>

  1288. <p>This positional information can be missing. A non-exhaustive lists of

  1289. cases where this may happen:</p>

  1290. <ul class="simple">

  1291. <li><p>Running the interpreter with <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span></code></a> <code class="docutils literal notranslate"><span class="pre">no_debug_ranges</span></code>.</p></li>

  1292. <li><p>Loading a pyc file compiled while using <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span></code></a> <code class="docutils literal notranslate"><span class="pre">no_debug_ranges</span></code>.</p></li>

  1293. <li><p>Position tuples corresponding to artificial instructions.</p></li>

  1294. <li><p>Line and column numbers that can’t be represented due to

  1295. implementation specific limitations.</p></li>

  1296. </ul>

  1297. <p>When this occurs, some or all of the tuple elements can be

  1298. <a class="reference internal" href="../library/constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.</p>

  1299. <div class="versionadded">

  1300. <p><span class="versionmodified added">New in version 3.11.</span></p>

  1301. </div>

  1302. <div class="admonition note">

  1303. <p class="admonition-title">Note</p>

  1304. <p>This feature requires storing column positions in code objects which may

  1305. result in a small increase of disk usage of compiled Python files or

  1306. interpreter memory usage. To avoid storing the extra information and/or

  1307. deactivate printing the extra traceback information, the

  1308. <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span></code></a> <code class="docutils literal notranslate"><span class="pre">no_debug_ranges</span></code> command line flag or the <span class="target" id="index-61"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONNODEBUGRANGES"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONNODEBUGRANGES</span></code></a>

  1309. environment variable can be used.</p>

  1310. </div>

  1311. </dd></dl>

  1312. 

  1313. <dl class="py method">

  1314. <dt class="sig sig-object py" id="codeobject.co_lines">

  1315. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">co_lines</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#codeobject.co_lines" title="Link to this definition">¶</a></dt>

  1316. <dd><p>Returns an iterator that yields information about successive ranges of

  1317. <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a>s. Each item yielded is a <code class="docutils literal notranslate"><span class="pre">(start,</span> <span class="pre">end,</span> <span class="pre">lineno)</span></code>

  1318. <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>:</p>

  1319. <ul class="simple">

  1320. <li><p><code class="docutils literal notranslate"><span class="pre">start</span></code> (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>) represents the offset (inclusive) of the start

  1321. of the <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> range</p></li>

  1322. <li><p><code class="docutils literal notranslate"><span class="pre">end</span></code> (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>) represents the offset (exclusive) of the end of

  1323. the <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> range</p></li>

  1324. <li><p><code class="docutils literal notranslate"><span class="pre">lineno</span></code> is 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> representing the line number of the

  1325. <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> range, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the bytecodes in the given range

  1326. have no line number</p></li>

  1327. </ul>

  1328. <p>The items yielded will have the following properties:</p>

  1329. <ul class="simple">

  1330. <li><p>The first range yielded will have a <code class="docutils literal notranslate"><span class="pre">start</span></code> of 0.</p></li>

  1331. <li><p>The <code class="docutils literal notranslate"><span class="pre">(start,</span> <span class="pre">end)</span></code> ranges will be non-decreasing and consecutive. That

  1332. is, for any pair of <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>s, the <code class="docutils literal notranslate"><span class="pre">start</span></code> of the second will be

  1333. equal to the <code class="docutils literal notranslate"><span class="pre">end</span></code> of the first.</p></li>

  1334. <li><p>No range will be backwards: <code class="docutils literal notranslate"><span class="pre">end</span> <span class="pre">&gt;=</span> <span class="pre">start</span></code> for all triples.</p></li>

  1335. <li><p>The last <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> yielded will have <code class="docutils literal notranslate"><span class="pre">end</span></code> equal to the size of the

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

  1337. </ul>

  1338. <p>Zero-width ranges, where <code class="docutils literal notranslate"><span class="pre">start</span> <span class="pre">==</span> <span class="pre">end</span></code>, are allowed. Zero-width ranges

  1339. are used for lines that are present in the source code, but have been

  1340. eliminated by the <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> compiler.</p>

  1341. <div class="versionadded">

  1342. <p><span class="versionmodified added">New in version 3.10.</span></p>

  1343. </div>

  1344. <div class="admonition seealso">

  1345. <p class="admonition-title">See also</p>

  1346. <dl class="simple">

  1347. <dt><span class="target" id="index-62"></span><a class="pep reference external" href="https://peps.python.org/pep-0626/"><strong>PEP 626</strong></a> - Precise line numbers for debugging and other tools.</dt><dd><p>The PEP that introduced the <code class="xref py py-meth docutils literal notranslate"><span class="pre">co_lines()</span></code> method.</p>

  1348. </dd>

  1349. </dl>

  1350. </div>

  1351. </dd></dl>

  1352. 

  1353. <dl class="py method">

  1354. <dt class="sig sig-object py" id="codeobject.replace">

  1355. <span class="sig-prename descclassname"><span class="pre">codeobject.</span></span><span class="sig-name descname"><span class="pre">replace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#codeobject.replace" title="Link to this definition">¶</a></dt>

  1356. <dd><p>Return a copy of the code object with new values for the specified fields.</p>

  1357. <div class="versionadded">

  1358. <p><span class="versionmodified added">New in version 3.8.</span></p>

  1359. </div>

  1360. </dd></dl>

  1361. 

  1362. </section>

  1363. </section>

  1364. <section id="frame-objects">

  1365. <span id="id6"></span><h4><span class="section-number">3.2.13.2. </span>Frame objects<a class="headerlink" href="#frame-objects" title="Link to this heading">¶</a></h4>

  1366. <p id="index-63">Frame objects represent execution frames.  They may occur in

  1367. <a class="reference internal" href="#traceback-objects"><span class="std std-ref">traceback objects</span></a>,

  1368. and are also passed to registered trace functions.</p>

  1369. <section id="index-64">

  1370. <span id="id7"></span><h5><span class="section-number">3.2.13.2.1. </span>Special read-only attributes<a class="headerlink" href="#index-64" title="Link to this heading">¶</a></h5>

  1371. <table class="docutils align-default">

  1372. <tbody>

  1373. <tr class="row-odd"><td><dl class="py attribute">

  1374. <dt class="sig sig-object py" id="frame.f_back">

  1375. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_back</span></span><a class="headerlink" href="#frame.f_back" title="Link to this definition">¶</a></dt>

  1376. <dd></dd></dl>

  1377. 

  1378. </td>

  1379. <td><p>Points to the previous stack frame (towards the caller),

  1380. or <code class="docutils literal notranslate"><span class="pre">None</span></code> if this is the bottom stack frame</p></td>

  1381. </tr>

  1382. <tr class="row-even"><td><dl class="py attribute">

  1383. <dt class="sig sig-object py" id="frame.f_code">

  1384. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_code</span></span><a class="headerlink" href="#frame.f_code" title="Link to this definition">¶</a></dt>

  1385. <dd></dd></dl>

  1386. 

  1387. </td>

  1388. <td><p>The <a class="reference internal" href="#code-objects"><span class="std std-ref">code object</span></a> being executed in this frame.

  1389. Accessing this attribute raises an <a class="reference internal" href="../library/sys.html#auditing"><span class="std std-ref">auditing event</span></a>

  1390. <code class="docutils literal notranslate"><span class="pre">object.__getattr__</span></code> with arguments <code class="docutils literal notranslate"><span class="pre">obj</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;f_code&quot;</span></code>.</p></td>

  1391. </tr>

  1392. <tr class="row-odd"><td><dl class="py attribute">

  1393. <dt class="sig sig-object py" id="frame.f_locals">

  1394. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_locals</span></span><a class="headerlink" href="#frame.f_locals" title="Link to this definition">¶</a></dt>

  1395. <dd></dd></dl>

  1396. 

  1397. </td>

  1398. <td><p>The dictionary used by the frame to look up

  1399. <a class="reference internal" href="executionmodel.html#naming"><span class="std std-ref">local variables</span></a></p></td>

  1400. </tr>

  1401. <tr class="row-even"><td><dl class="py attribute">

  1402. <dt class="sig sig-object py" id="frame.f_globals">

  1403. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_globals</span></span><a class="headerlink" href="#frame.f_globals" title="Link to this definition">¶</a></dt>

  1404. <dd></dd></dl>

  1405. 

  1406. </td>

  1407. <td><p>The dictionary used by the frame to look up

  1408. <a class="reference internal" href="executionmodel.html#naming"><span class="std std-ref">global variables</span></a></p></td>

  1409. </tr>

  1410. <tr class="row-odd"><td><dl class="py attribute">

  1411. <dt class="sig sig-object py" id="frame.f_builtins">

  1412. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_builtins</span></span><a class="headerlink" href="#frame.f_builtins" title="Link to this definition">¶</a></dt>

  1413. <dd></dd></dl>

  1414. 

  1415. </td>

  1416. <td><p>The dictionary used by the frame to look up

  1417. <a class="reference internal" href="executionmodel.html#naming"><span class="std std-ref">built-in (intrinsic) names</span></a></p></td>

  1418. </tr>

  1419. <tr class="row-even"><td><dl class="py attribute">

  1420. <dt class="sig sig-object py" id="frame.f_lasti">

  1421. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_lasti</span></span><a class="headerlink" href="#frame.f_lasti" title="Link to this definition">¶</a></dt>

  1422. <dd></dd></dl>

  1423. 

  1424. </td>

  1425. <td><p>The “precise instruction” of the frame object

  1426. (this is an index into the <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> string of the

  1427. <a class="reference internal" href="#code-objects"><span class="std std-ref">code object</span></a>)</p></td>

  1428. </tr>

  1429. </tbody>

  1430. </table>

  1431. </section>

  1432. <section id="index-65">

  1433. <span id="id8"></span><h5><span class="section-number">3.2.13.2.2. </span>Special writable attributes<a class="headerlink" href="#index-65" title="Link to this heading">¶</a></h5>

  1434. <table class="docutils align-default">

  1435. <tbody>

  1436. <tr class="row-odd"><td><dl class="py attribute">

  1437. <dt class="sig sig-object py" id="frame.f_trace">

  1438. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_trace</span></span><a class="headerlink" href="#frame.f_trace" title="Link to this definition">¶</a></dt>

  1439. <dd></dd></dl>

  1440. 

  1441. </td>

  1442. <td><p>If not <code class="docutils literal notranslate"><span class="pre">None</span></code>, this is a function called for various events during

  1443. code execution (this is used by debuggers). Normally an event is

  1444. triggered for each new source line (see <a class="reference internal" href="#frame.f_trace_lines" title="frame.f_trace_lines"><code class="xref py py-attr docutils literal notranslate"><span class="pre">f_trace_lines</span></code></a>).</p></td>

  1445. </tr>

  1446. <tr class="row-even"><td><dl class="py attribute">

  1447. <dt class="sig sig-object py" id="frame.f_trace_lines">

  1448. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_trace_lines</span></span><a class="headerlink" href="#frame.f_trace_lines" title="Link to this definition">¶</a></dt>

  1449. <dd></dd></dl>

  1450. 

  1451. </td>

  1452. <td><p>Set this attribute to <a class="reference internal" href="../library/constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> to disable triggering a tracing

  1453. event for each source line.</p></td>

  1454. </tr>

  1455. <tr class="row-odd"><td><dl class="py attribute">

  1456. <dt class="sig sig-object py" id="frame.f_trace_opcodes">

  1457. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_trace_opcodes</span></span><a class="headerlink" href="#frame.f_trace_opcodes" title="Link to this definition">¶</a></dt>

  1458. <dd></dd></dl>

  1459. 

  1460. </td>

  1461. <td><p>Set this attribute to <a class="reference internal" href="../library/constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> to allow per-opcode events to be

  1462. requested. Note that this may lead to

  1463. undefined interpreter behaviour if exceptions raised by the trace

  1464. function escape to the function being traced.</p></td>

  1465. </tr>

  1466. <tr class="row-even"><td><dl class="py attribute">

  1467. <dt class="sig sig-object py" id="frame.f_lineno">

  1468. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">f_lineno</span></span><a class="headerlink" href="#frame.f_lineno" title="Link to this definition">¶</a></dt>

  1469. <dd></dd></dl>

  1470. 

  1471. </td>

  1472. <td><p>The current line number of the frame – writing to this

  1473. from within a trace function jumps to the given line (only for the bottom-most

  1474. frame).  A debugger can implement a Jump command (aka Set Next Statement)

  1475. by writing to this attribute.</p></td>

  1476. </tr>

  1477. </tbody>

  1478. </table>

  1479. </section>

  1480. <section id="frame-object-methods">

  1481. <h5><span class="section-number">3.2.13.2.3. </span>Frame object methods<a class="headerlink" href="#frame-object-methods" title="Link to this heading">¶</a></h5>

  1482. <p>Frame objects support one method:</p>

  1483. <dl class="py method">

  1484. <dt class="sig sig-object py" id="frame.clear">

  1485. <span class="sig-prename descclassname"><span class="pre">frame.</span></span><span class="sig-name descname"><span class="pre">clear</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#frame.clear" title="Link to this definition">¶</a></dt>

  1486. <dd><p>This method clears all references to <a class="reference internal" href="executionmodel.html#naming"><span class="std std-ref">local variables</span></a> held by the

  1487. frame.  Also, if the frame belonged to a <a class="reference internal" href="../glossary.html#term-generator"><span class="xref std std-term">generator</span></a>, the generator

  1488. is finalized.  This helps break reference cycles involving frame

  1489. objects (for example when catching an <a class="reference internal" href="../library/exceptions.html#bltin-exceptions"><span class="std std-ref">exception</span></a>

  1490. and storing its <a class="reference internal" href="#traceback-objects"><span class="std std-ref">traceback</span></a> for later use).</p>

  1491. <p><a class="reference internal" href="../library/exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is raised if the frame is currently executing.</p>

  1492. <div class="versionadded">

  1493. <p><span class="versionmodified added">New in version 3.4.</span></p>

  1494. </div>

  1495. </dd></dl>

  1496. 

  1497. </section>

  1498. </section>

  1499. <section id="traceback-objects">

  1500. <span id="id9"></span><h4><span class="section-number">3.2.13.3. </span>Traceback objects<a class="headerlink" href="#traceback-objects" title="Link to this heading">¶</a></h4>

  1501. <p id="index-66">Traceback objects represent the stack trace of an <a class="reference internal" href="../tutorial/errors.html#tut-errors"><span class="std std-ref">exception</span></a>.

  1502. A traceback object

  1503. is implicitly created when an exception occurs, and may also be explicitly

  1504. created by calling <a class="reference internal" href="../library/types.html#types.TracebackType" title="types.TracebackType"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.TracebackType</span></code></a>.</p>

  1505. <div class="versionchanged">

  1506. <p><span class="versionmodified changed">Changed in version 3.7: </span>Traceback objects can now be explicitly instantiated from Python code.</p>

  1507. </div>

  1508. <p>For implicitly created tracebacks, when the search for an exception handler

  1509. unwinds the execution stack, at each unwound level a traceback object is

  1510. inserted in front of the current traceback.  When an exception handler is

  1511. entered, the stack trace is made available to the program. (See section

  1512. <a class="reference internal" href="compound_stmts.html#try"><span class="std std-ref">The try statement</span></a>.) It is accessible as the third item of the

  1513. tuple returned by <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>, and as the

  1514. <a class="reference internal" href="../library/exceptions.html#BaseException.__traceback__" title="BaseException.__traceback__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__traceback__</span></code></a> attribute

  1515. of the caught exception.</p>

  1516. <p>When the program contains no suitable

  1517. handler, the stack trace is written (nicely formatted) to the standard error

  1518. stream; if the interpreter is interactive, it is also made available to the user

  1519. as <a class="reference internal" href="../library/sys.html#sys.last_traceback" title="sys.last_traceback"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.last_traceback</span></code></a>.</p>

  1520. <p>For explicitly created tracebacks, it is up to the creator of the traceback

  1521. to determine how the <a class="reference internal" href="#traceback.tb_next" title="traceback.tb_next"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tb_next</span></code></a> attributes should be linked to

  1522. form a full stack trace.</p>

  1523. <p id="index-67">Special read-only attributes:</p>

  1524. <table class="docutils align-default">

  1525. <tbody>

  1526. <tr class="row-odd"><td><dl class="py attribute">

  1527. <dt class="sig sig-object py" id="traceback.tb_frame">

  1528. <span class="sig-prename descclassname"><span class="pre">traceback.</span></span><span class="sig-name descname"><span class="pre">tb_frame</span></span><a class="headerlink" href="#traceback.tb_frame" title="Link to this definition">¶</a></dt>

  1529. <dd></dd></dl>

  1530. 

  1531. </td>

  1532. <td><p>Points to the execution <a class="reference internal" href="#frame-objects"><span class="std std-ref">frame</span></a> of the current

  1533. level.</p>

  1534. <p>Accessing this attribute raises an

  1535. <a class="reference internal" href="../library/sys.html#auditing"><span class="std std-ref">auditing event</span></a> <code class="docutils literal notranslate"><span class="pre">object.__getattr__</span></code> with arguments

  1536. <code class="docutils literal notranslate"><span class="pre">obj</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;tb_frame&quot;</span></code>.</p>

  1537. </td>

  1538. </tr>

  1539. <tr class="row-even"><td><dl class="py attribute">

  1540. <dt class="sig sig-object py" id="traceback.tb_lineno">

  1541. <span class="sig-prename descclassname"><span class="pre">traceback.</span></span><span class="sig-name descname"><span class="pre">tb_lineno</span></span><a class="headerlink" href="#traceback.tb_lineno" title="Link to this definition">¶</a></dt>

  1542. <dd></dd></dl>

  1543. 

  1544. </td>

  1545. <td><p>Gives the line number where the exception occurred</p></td>

  1546. </tr>

  1547. <tr class="row-odd"><td><dl class="py attribute">

  1548. <dt class="sig sig-object py" id="traceback.tb_lasti">

  1549. <span class="sig-prename descclassname"><span class="pre">traceback.</span></span><span class="sig-name descname"><span class="pre">tb_lasti</span></span><a class="headerlink" href="#traceback.tb_lasti" title="Link to this definition">¶</a></dt>

  1550. <dd></dd></dl>

  1551. 

  1552. </td>

  1553. <td><p>Indicates the “precise instruction”.</p></td>

  1554. </tr>

  1555. </tbody>

  1556. </table>

  1557. <p>The line number and last instruction in the traceback may differ from the

  1558. line number of its <a class="reference internal" href="#frame-objects"><span class="std std-ref">frame object</span></a> if the exception

  1559. occurred in a

  1560. <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> statement with no matching except clause or with a

  1561. <a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">finally</span></code></a> clause.</p>

  1562. <dl class="py attribute" id="index-68">

  1563. <dt class="sig sig-object py" id="traceback.tb_next">

  1564. <span class="sig-prename descclassname"><span class="pre">traceback.</span></span><span class="sig-name descname"><span class="pre">tb_next</span></span><a class="headerlink" href="#traceback.tb_next" title="Link to this definition">¶</a></dt>

  1565. <dd><p>The special writable attribute <code class="xref py py-attr docutils literal notranslate"><span class="pre">tb_next</span></code> is the next level in the

  1566. stack trace (towards the frame where the exception occurred), or <code class="docutils literal notranslate"><span class="pre">None</span></code> if

  1567. there is no next level.</p>

  1568. <div class="versionchanged">

  1569. <p><span class="versionmodified changed">Changed in version 3.7: </span>This attribute is now writable</p>

  1570. </div>

  1571. </dd></dl>

  1572. 

  1573. </section>

  1574. <section id="slice-objects">

  1575. <h4><span class="section-number">3.2.13.4. </span>Slice objects<a class="headerlink" href="#slice-objects" title="Link to this heading">¶</a></h4>

  1576. <p id="index-69">Slice objects are used to represent slices for

  1577. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>

  1578. methods.  They are also created by the built-in <a class="reference internal" href="../library/functions.html#slice" title="slice"><code class="xref py py-func docutils literal notranslate"><span class="pre">slice()</span></code></a> function.</p>

  1579. <p id="index-70">Special read-only attributes: <a class="reference internal" href="../library/functions.html#slice.start" title="slice.start"><code class="xref py py-attr docutils literal notranslate"><span class="pre">start</span></code></a> is the lower bound;

  1580. <a class="reference internal" href="../library/functions.html#slice.stop" title="slice.stop"><code class="xref py py-attr docutils literal notranslate"><span class="pre">stop</span></code></a> is the upper bound; <a class="reference internal" href="../library/functions.html#slice.step" title="slice.step"><code class="xref py py-attr docutils literal notranslate"><span class="pre">step</span></code></a> is the step

  1581. value; each is <code class="docutils literal notranslate"><span class="pre">None</span></code> if omitted.  These attributes can have any type.</p>

  1582. <p>Slice objects support one method:</p>

  1583. <dl class="py method">

  1584. <dt class="sig sig-object py" id="slice.indices">

  1585. <span class="sig-prename descclassname"><span class="pre">slice.</span></span><span class="sig-name descname"><span class="pre">indices</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">length</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#slice.indices" title="Link to this definition">¶</a></dt>

  1586. <dd><p>This method takes a single integer argument <em>length</em> and computes

  1587. information about the slice that the slice object would describe if

  1588. applied to a sequence of <em>length</em> items.  It returns a tuple of three

  1589. integers; respectively these are the <em>start</em> and <em>stop</em> indices and the

  1590. <em>step</em> or stride length of the slice. Missing or out-of-bounds indices

  1591. are handled in a manner consistent with regular slices.</p>

  1592. </dd></dl>

  1593. 

  1594. </section>

  1595. <section id="static-method-objects">

  1596. <h4><span class="section-number">3.2.13.5. </span>Static method objects<a class="headerlink" href="#static-method-objects" title="Link to this heading">¶</a></h4>

  1597. <p>Static method objects provide a way of defeating the transformation of function

  1598. objects to method objects described above. A static method object is a wrapper

  1599. around any other object, usually a user-defined method object. When a static

  1600. method object is retrieved from a class or a class instance, the object actually

  1601. returned is the wrapped object, which is not subject to any further

  1602. transformation. Static method objects are also callable. Static method

  1603. objects are created by the built-in <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> constructor.</p>

  1604. </section>

  1605. <section id="class-method-objects">

  1606. <h4><span class="section-number">3.2.13.6. </span>Class method objects<a class="headerlink" href="#class-method-objects" title="Link to this heading">¶</a></h4>

  1607. <p>A class method object, like a static method object, is a wrapper around another

  1608. object that alters the way in which that object is retrieved from classes and

  1609. class instances. The behaviour of class method objects upon such retrieval is

  1610. described above, under <a class="reference internal" href="#instance-methods"><span class="std std-ref">“instance methods”</span></a>. Class method objects are created

  1611. by the built-in <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> constructor.</p>

  1612. </section>

  1613. </section>

  1614. </section>

  1615. <section id="special-method-names">

  1616. <span id="specialnames"></span><h2><span class="section-number">3.3. </span>Special method names<a class="headerlink" href="#special-method-names" title="Link to this heading">¶</a></h2>

  1617. <p id="index-71">A class can implement certain operations that are invoked by special syntax

  1618. (such as arithmetic operations or subscripting and slicing) by defining methods

  1619. with special names. This is Python’s approach to <em class="dfn">operator overloading</em>,

  1620. allowing classes to define their own behavior with respect to language

  1621. operators.  For instance, if a class defines a method named

  1622. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>,

  1623. and <code class="docutils literal notranslate"><span class="pre">x</span></code> is an instance of this class, then <code class="docutils literal notranslate"><span class="pre">x[i]</span></code> is roughly equivalent

  1624. to <code class="docutils literal notranslate"><span class="pre">type(x).__getitem__(x,</span> <span class="pre">i)</span></code>.  Except where mentioned, attempts to execute an

  1625. operation raise an exception when no appropriate method is defined (typically

  1626. <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> or <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>).</p>

  1627. <p>Setting a special method to <code class="docutils literal notranslate"><span class="pre">None</span></code> indicates that the corresponding

  1628. operation is not available.  For example, if a class sets

  1629. <a class="reference internal" href="#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> to <code class="docutils literal notranslate"><span class="pre">None</span></code>, the class is not iterable, so calling

  1630. <a class="reference internal" href="../library/functions.html#iter" title="iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">iter()</span></code></a> on its instances will raise a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> (without

  1631. falling back to <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>). <a class="footnote-reference brackets" href="#id18" id="id10" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p>

  1632. <p>When implementing a class that emulates any built-in type, it is important that

  1633. the emulation only be implemented to the degree that it makes sense for the

  1634. object being modelled.  For example, some sequences may work well with retrieval

  1635. of individual elements, but extracting a slice may not make sense.  (One example

  1636. of this is the <code class="xref py py-class docutils literal notranslate"><span class="pre">NodeList</span></code> interface in the W3C’s Document

  1637. Object Model.)</p>

  1638. <section id="basic-customization">

  1639. <span id="customization"></span><h3><span class="section-number">3.3.1. </span>Basic customization<a class="headerlink" href="#basic-customization" title="Link to this heading">¶</a></h3>

  1640. <dl class="py method">

  1641. <dt class="sig sig-object py" id="object.__new__">

  1642. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__new__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cls</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">...</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#object.__new__" title="Link to this definition">¶</a></dt>

  1643. <dd><p id="index-72">Called to create a new instance of class <em>cls</em>.  <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> is a static

  1644. method (special-cased so you need not declare it as such) that takes the class

  1645. of which an instance was requested as its first argument.  The remaining

  1646. arguments are those passed to the object constructor expression (the call to the

  1647. class).  The return value of <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> should be the new object instance

  1648. (usually an instance of <em>cls</em>).</p>

  1649. <p>Typical implementations create a new instance of the class by invoking the

  1650. superclass’s <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> method using <code class="docutils literal notranslate"><span class="pre">super().__new__(cls[,</span> <span class="pre">...])</span></code>

  1651. with appropriate arguments and then modifying the newly created instance

  1652. as necessary before returning it.</p>

  1653. <p>If <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> is invoked during object construction and it returns an

  1654. instance of <em>cls</em>, then the new instance’s <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method

  1655. will be invoked like <code class="docutils literal notranslate"><span class="pre">__init__(self[,</span> <span class="pre">...])</span></code>, where <em>self</em> is the new instance

  1656. and the remaining arguments are the same as were passed to the object constructor.</p>

  1657. <p>If <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> does not return an instance of <em>cls</em>, then the new instance’s

  1658. <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method will not be invoked.</p>

  1659. <p><a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> is intended mainly to allow subclasses of immutable types (like

  1660. int, str, or tuple) to customize instance creation.  It is also commonly

  1661. overridden in custom metaclasses in order to customize class creation.</p>

  1662. </dd></dl>

  1663. 

  1664. <dl class="py method">

  1665. <dt class="sig sig-object py" id="object.__init__">

  1666. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">...</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#object.__init__" title="Link to this definition">¶</a></dt>

  1667. <dd><p id="index-73">Called after the instance has been created (by <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a>), but before

  1668. it is returned to the caller.  The arguments are those passed to the

  1669. class constructor expression.  If a base class has an <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>

  1670. method, the derived class’s <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method, if any, must explicitly

  1671. call it to ensure proper initialization of the base class part of the

  1672. instance; for example: <code class="docutils literal notranslate"><span class="pre">super().__init__([args...])</span></code>.</p>

  1673. <p>Because <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> and <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> work together in constructing

  1674. objects (<a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> to create it, and <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> to customize it),

  1675. no non-<code class="docutils literal notranslate"><span class="pre">None</span></code> value may be returned by <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>; doing so will

  1676. cause a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> to be raised at runtime.</p>

  1677. </dd></dl>

  1678. 

  1679. <dl class="py method">

  1680. <dt class="sig sig-object py" id="object.__del__">

  1681. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__del__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__del__" title="Link to this definition">¶</a></dt>

  1682. <dd><p id="index-74">Called when the instance is about to be destroyed.  This is also called a

  1683. finalizer or (improperly) a destructor.  If a base class has a

  1684. <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> method, the derived class’s <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> method,

  1685. if any, must explicitly call it to ensure proper deletion of the base

  1686. class part of the instance.</p>

  1687. <p>It is possible (though not recommended!) for the <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> method

  1688. to postpone destruction of the instance by creating a new reference to

  1689. it.  This is called object <em>resurrection</em>.  It is implementation-dependent

  1690. whether <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> is called a second time when a resurrected object

  1691. is about to be destroyed; the current <a class="reference internal" href="../glossary.html#term-CPython"><span class="xref std std-term">CPython</span></a> implementation

  1692. only calls it once.</p>

  1693. <p>It is not guaranteed that <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> methods are called for objects

  1694. that still exist when the interpreter exits.</p>

  1695. <div class="admonition note">

  1696. <p class="admonition-title">Note</p>

  1697. <p><code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">x</span></code> doesn’t directly call <code class="docutils literal notranslate"><span class="pre">x.__del__()</span></code> — the former decrements

  1698. the reference count for <code class="docutils literal notranslate"><span class="pre">x</span></code> by one, and the latter is only called when

  1699. <code class="docutils literal notranslate"><span class="pre">x</span></code>’s reference count reaches zero.</p>

  1700. </div>

  1701. <div class="impl-detail compound">

  1702. <p><strong>CPython implementation detail:</strong> It is possible for a reference cycle to prevent the reference count

  1703. of an object from going to zero.  In this case, the cycle will be

  1704. later detected and deleted by the <a class="reference internal" href="../glossary.html#term-garbage-collection"><span class="xref std std-term">cyclic garbage collector</span></a>.  A common cause of reference cycles is when

  1705. an exception has been caught in a local variable.  The frame’s

  1706. locals then reference the exception, which references its own

  1707. traceback, which references the locals of all frames caught in the

  1708. traceback.</p>

  1709. <div class="admonition seealso">

  1710. <p class="admonition-title">See also</p>

  1711. <p>Documentation for the <a class="reference internal" href="../library/gc.html#module-gc" title="gc: Interface to the cycle-detecting garbage collector."><code class="xref py py-mod docutils literal notranslate"><span class="pre">gc</span></code></a> module.</p>

  1712. </div>

  1713. </div>

  1714. <div class="admonition warning">

  1715. <p class="admonition-title">Warning</p>

  1716. <p>Due to the precarious circumstances under which <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> methods are

  1717. invoked, exceptions that occur during their execution are ignored, and a warning

  1718. is printed to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> instead.  In particular:</p>

  1719. <ul class="simple">

  1720. <li><p><a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> can be invoked when arbitrary code is being executed,

  1721. including from any arbitrary thread.  If <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> needs to take

  1722. a lock or invoke any other blocking resource, it may deadlock as

  1723. the resource may already be taken by the code that gets interrupted

  1724. to execute <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a>.</p></li>

  1725. <li><p><a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> can be executed during interpreter shutdown.  As a

  1726. consequence, the global variables it needs to access (including other

  1727. modules) may already have been deleted or set to <code class="docutils literal notranslate"><span class="pre">None</span></code>. Python

  1728. guarantees that globals whose name begins with a single underscore

  1729. are deleted from their module before other globals are deleted; if

  1730. no other references to such globals exist, this may help in assuring

  1731. that imported modules are still available at the time when the

  1732. <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> method is called.</p></li>

  1733. </ul>

  1734. </div>

  1735. <span class="target" id="index-75"></span></dd></dl>

  1736. 

  1737. <dl class="py method">

  1738. <dt class="sig sig-object py" id="object.__repr__">

  1739. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__repr__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__repr__" title="Link to this definition">¶</a></dt>

  1740. <dd><p>Called by the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a> built-in function to compute the “official” string

  1741. representation of an object.  If at all possible, this should look like a

  1742. valid Python expression that could be used to recreate an object with the

  1743. same value (given an appropriate environment).  If this is not possible, a

  1744. string of the form <code class="docutils literal notranslate"><span class="pre">&lt;...some</span> <span class="pre">useful</span> <span class="pre">description...&gt;</span></code> should be returned.

  1745. The return value must be a string object. If a class defines <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a>

  1746. but not <a class="reference internal" href="#object.__str__" title="object.__str__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code></a>, then <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a> is also used when an

  1747. “informal” string representation of instances of that class is required.</p>

  1748. <p>This is typically used for debugging, so it is important that the representation

  1749. is information-rich and unambiguous.</p>

  1750. <span class="target" id="index-76"></span></dd></dl>

  1751. 

  1752. <dl class="py method">

  1753. <dt class="sig sig-object py" id="object.__str__">

  1754. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__str__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__str__" title="Link to this definition">¶</a></dt>

  1755. <dd><p>Called by <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str(object)</span></code></a> and the built-in functions

  1756. <a class="reference internal" href="../library/functions.html#format" title="format"><code class="xref py py-func docutils literal notranslate"><span class="pre">format()</span></code></a> and <a class="reference internal" href="../library/functions.html#print" title="print"><code class="xref py py-func docutils literal notranslate"><span class="pre">print()</span></code></a> to compute the “informal” or nicely

  1757. printable string representation of an object.  The return value must be a

  1758. <a class="reference internal" href="../library/stdtypes.html#textseq"><span class="std std-ref">string</span></a> object.</p>

  1759. <p>This method differs from <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__repr__()</span></code></a> in that there is no

  1760. expectation that <a class="reference internal" href="#object.__str__" title="object.__str__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code></a> return a valid Python expression: a more

  1761. convenient or concise representation can be used.</p>

  1762. <p>The default implementation defined by the built-in type <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>

  1763. calls <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__repr__()</span></code></a>.</p>

  1764. </dd></dl>

  1765. 

  1766. <dl class="py method">

  1767. <dt class="sig sig-object py" id="object.__bytes__">

  1768. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__bytes__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__bytes__" title="Link to this definition">¶</a></dt>

  1769. <dd><p id="index-77">Called by <a class="reference internal" href="../library/functions.html#func-bytes"><span class="std std-ref">bytes</span></a> to compute a byte-string representation

  1770. of an object. This should return a <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>

  1771. <span class="target" id="index-78"></span></dd></dl>

  1772. 

  1773. <dl class="py method">

  1774. <dt class="sig sig-object py" id="object.__format__">

  1775. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__format__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">format_spec</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__format__" title="Link to this definition">¶</a></dt>

  1776. <dd><p>Called by the <a class="reference internal" href="../library/functions.html#format" title="format"><code class="xref py py-func docutils literal notranslate"><span class="pre">format()</span></code></a> built-in function,

  1777. and by extension, evaluation of <a class="reference internal" href="lexical_analysis.html#f-strings"><span class="std std-ref">formatted string literals</span></a> and the <a class="reference internal" href="../library/stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a> method, to produce a “formatted”

  1778. string representation of an object. The <em>format_spec</em> argument is

  1779. a string that contains a description of the formatting options desired.

  1780. The interpretation of the <em>format_spec</em> argument is up to the type

  1781. implementing <a class="reference internal" href="#object.__format__" title="object.__format__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__format__()</span></code></a>, however most classes will either

  1782. delegate formatting to one of the built-in types, or use a similar

  1783. formatting option syntax.</p>

  1784. <p>See <a class="reference internal" href="../library/string.html#formatspec"><span class="std std-ref">Format Specification Mini-Language</span></a> for a description of the standard formatting syntax.</p>

  1785. <p>The return value must be a string object.</p>

  1786. <div class="versionchanged">

  1787. <p><span class="versionmodified changed">Changed in version 3.4: </span>The __format__ method of <code class="docutils literal notranslate"><span class="pre">object</span></code> itself raises a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>

  1788. if passed any non-empty string.</p>

  1789. </div>

  1790. <div class="versionchanged">

  1791. <p><span class="versionmodified changed">Changed in version 3.7: </span><code class="docutils literal notranslate"><span class="pre">object.__format__(x,</span> <span class="pre">'')</span></code> is now equivalent to <code class="docutils literal notranslate"><span class="pre">str(x)</span></code> rather

  1792. than <code class="docutils literal notranslate"><span class="pre">format(str(x),</span> <span class="pre">'')</span></code>.</p>

  1793. </div>

  1794. </dd></dl>

  1795. 

  1796. <dl class="py method" id="richcmpfuncs">

  1797. <dt class="sig sig-object py" id="object.__lt__">

  1798. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__lt__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__lt__" title="Link to this definition">¶</a></dt>

  1799. <dt class="sig sig-object py" id="object.__le__">

  1800. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__le__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__le__" title="Link to this definition">¶</a></dt>

  1801. <dt class="sig sig-object py" id="object.__eq__">

  1802. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__eq__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__eq__" title="Link to this definition">¶</a></dt>

  1803. <dt class="sig sig-object py" id="object.__ne__">

  1804. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ne__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__ne__" title="Link to this definition">¶</a></dt>

  1805. <dt class="sig sig-object py" id="object.__gt__">

  1806. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__gt__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__gt__" title="Link to this definition">¶</a></dt>

  1807. <dt class="sig sig-object py" id="object.__ge__">

  1808. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ge__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__ge__" title="Link to this definition">¶</a></dt>

  1809. <dd><p id="index-79">These are the so-called “rich comparison” methods. The correspondence between

  1810. operator symbols and method names is as follows: <code class="docutils literal notranslate"><span class="pre">x&lt;y</span></code> calls <code class="docutils literal notranslate"><span class="pre">x.__lt__(y)</span></code>,

  1811. <code class="docutils literal notranslate"><span class="pre">x&lt;=y</span></code> calls <code class="docutils literal notranslate"><span class="pre">x.__le__(y)</span></code>, <code class="docutils literal notranslate"><span class="pre">x==y</span></code> calls <code class="docutils literal notranslate"><span class="pre">x.__eq__(y)</span></code>, <code class="docutils literal notranslate"><span class="pre">x!=y</span></code> calls

  1812. <code class="docutils literal notranslate"><span class="pre">x.__ne__(y)</span></code>, <code class="docutils literal notranslate"><span class="pre">x&gt;y</span></code> calls <code class="docutils literal notranslate"><span class="pre">x.__gt__(y)</span></code>, and <code class="docutils literal notranslate"><span class="pre">x&gt;=y</span></code> calls

  1813. <code class="docutils literal notranslate"><span class="pre">x.__ge__(y)</span></code>.</p>

  1814. <p>A rich comparison method may return the singleton <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a> if it does

  1815. not implement the operation for a given pair of arguments. By convention,

  1816. <code class="docutils literal notranslate"><span class="pre">False</span></code> and <code class="docutils literal notranslate"><span class="pre">True</span></code> are returned for a successful comparison. However, these

  1817. methods can return any value, so if the comparison operator is used in a Boolean

  1818. context (e.g., in the condition of an <code class="docutils literal notranslate"><span class="pre">if</span></code> statement), Python will call

  1819. <a class="reference internal" href="../library/functions.html#bool" title="bool"><code class="xref py py-func docutils literal notranslate"><span class="pre">bool()</span></code></a> on the value to determine if the result is true or false.</p>

  1820. <p>By default, <code class="docutils literal notranslate"><span class="pre">object</span></code> implements <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> by using <code class="docutils literal notranslate"><span class="pre">is</span></code>, returning

  1821. <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a> in the case of a false comparison:

  1822. <code class="docutils literal notranslate"><span class="pre">True</span> <span class="pre">if</span> <span class="pre">x</span> <span class="pre">is</span> <span class="pre">y</span> <span class="pre">else</span> <span class="pre">NotImplemented</span></code>. For <a class="reference internal" href="#object.__ne__" title="object.__ne__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__ne__()</span></code></a>, by default it

  1823. delegates to <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> and inverts the result unless it is

  1824. <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code>.  There are no other implied relationships among the

  1825. comparison operators or default implementations; for example, the truth of

  1826. <code class="docutils literal notranslate"><span class="pre">(x&lt;y</span> <span class="pre">or</span> <span class="pre">x==y)</span></code> does not imply <code class="docutils literal notranslate"><span class="pre">x&lt;=y</span></code>. To automatically generate ordering

  1827. operations from a single root operation, see <a class="reference internal" href="../library/functools.html#functools.total_ordering" title="functools.total_ordering"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.total_ordering()</span></code></a>.</p>

  1828. <p>See the paragraph on <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> for

  1829. some important notes on creating <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a> objects which support

  1830. custom comparison operations and are usable as dictionary keys.</p>

  1831. <p>There are no swapped-argument versions of these methods (to be used when the

  1832. left argument does not support the operation but the right argument does);

  1833. rather, <a class="reference internal" href="#object.__lt__" title="object.__lt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code></a> and <a class="reference internal" href="#object.__gt__" title="object.__gt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__gt__()</span></code></a> are each other’s reflection,

  1834. <a class="reference internal" href="#object.__le__" title="object.__le__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__le__()</span></code></a> and <a class="reference internal" href="#object.__ge__" title="object.__ge__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__ge__()</span></code></a> are each other’s reflection, and

  1835. <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> and <a class="reference internal" href="#object.__ne__" title="object.__ne__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__ne__()</span></code></a> are their own reflection.

  1836. If the operands are of different types, and the right operand’s type is

  1837. a direct or indirect subclass of the left operand’s type,

  1838. the reflected method of the right operand has priority, otherwise

  1839. the left operand’s method has priority.  Virtual subclassing is

  1840. not considered.</p>

  1841. <p>When no appropriate method returns any value other than <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a>, the

  1842. <code class="docutils literal notranslate"><span class="pre">==</span></code> and <code class="docutils literal notranslate"><span class="pre">!=</span></code> operators will fall back to <code class="docutils literal notranslate"><span class="pre">is</span></code> and <code class="docutils literal notranslate"><span class="pre">is</span> <span class="pre">not</span></code>, respectively.</p>

  1843. </dd></dl>

  1844. 

  1845. <dl class="py method">

  1846. <dt class="sig sig-object py" id="object.__hash__">

  1847. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__hash__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__hash__" title="Link to this definition">¶</a></dt>

  1848. <dd><p id="index-80">Called by built-in function <a class="reference internal" href="../library/functions.html#hash" title="hash"><code class="xref py py-func docutils literal notranslate"><span class="pre">hash()</span></code></a> and for operations on members of

  1849. hashed collections including <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>, and

  1850. <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>.  The <code class="docutils literal notranslate"><span class="pre">__hash__()</span></code> method should return an integer. The only required

  1851. property is that objects which compare equal have the same hash value; it is

  1852. advised to mix together the hash values of the components of the object that

  1853. also play a part in comparison of objects by packing them into a tuple and

  1854. hashing the tuple. Example:</p>

  1855. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="fm">__hash__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1856.     <span class="k">return</span> <span class="nb">hash</span><span class="p">((</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">nick</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">color</span><span class="p">))</span>

  1857. </pre></div>

  1858. </div>

  1859. <div class="admonition note">

  1860. <p class="admonition-title">Note</p>

  1861. <p><a class="reference internal" href="../library/functions.html#hash" title="hash"><code class="xref py py-func docutils literal notranslate"><span class="pre">hash()</span></code></a> truncates the value returned from an object’s custom

  1862. <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> method to the size of a <a class="reference internal" href="../c-api/intro.html#c.Py_ssize_t" title="Py_ssize_t"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code></a>.  This is

  1863. typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds.  If an

  1864. object’s   <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> must interoperate on builds of different bit

  1865. sizes, be sure to check the width on all supported builds.  An easy way

  1866. to do this is with

  1867. <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-c</span> <span class="pre">&quot;import</span> <span class="pre">sys;</span> <span class="pre">print(sys.hash_info.width)&quot;</span></code>.</p>

  1868. </div>

  1869. <p>If a class does not define an <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> method it should not define a

  1870. <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> operation either; if it defines <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> but not

  1871. <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a>, its instances will not be usable as items in hashable

  1872. collections.  If a class defines mutable objects and implements an

  1873. <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> method, it should not implement <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a>, since the

  1874. implementation of <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a> collections requires that a key’s hash value is

  1875. immutable (if the object’s hash value changes, it will be in the wrong hash

  1876. bucket).</p>

  1877. <p>User-defined classes have <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> and <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> methods

  1878. by default; with them, all objects compare unequal (except with themselves)

  1879. and <code class="docutils literal notranslate"><span class="pre">x.__hash__()</span></code> returns an appropriate value such that <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></code>

  1880. implies both that <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">hash(x)</span> <span class="pre">==</span> <span class="pre">hash(y)</span></code>.</p>

  1881. <p>A class that overrides <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> and does not define <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a>

  1882. will have its <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> implicitly set to <code class="docutils literal notranslate"><span class="pre">None</span></code>.  When the

  1883. <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> method of a class is <code class="docutils literal notranslate"><span class="pre">None</span></code>, instances of the class will

  1884. raise an appropriate <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> when a program attempts to retrieve

  1885. their hash value, and will also be correctly identified as unhashable when

  1886. checking <code class="docutils literal notranslate"><span class="pre">isinstance(obj,</span> <span class="pre">collections.abc.Hashable)</span></code>.</p>

  1887. <p>If a class that overrides <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> needs to retain the implementation

  1888. of <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> from a parent class, the interpreter must be told this

  1889. explicitly by setting <code class="docutils literal notranslate"><span class="pre">__hash__</span> <span class="pre">=</span> <span class="pre">&lt;ParentClass&gt;.__hash__</span></code>.</p>

  1890. <p>If a class that does not override <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> wishes to suppress hash

  1891. support, it should include <code class="docutils literal notranslate"><span class="pre">__hash__</span> <span class="pre">=</span> <span class="pre">None</span></code> in the class definition.

  1892. A class which defines its own <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> that explicitly raises

  1893. a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> would be incorrectly identified as hashable by

  1894. an <code class="docutils literal notranslate"><span class="pre">isinstance(obj,</span> <span class="pre">collections.abc.Hashable)</span></code> call.</p>

  1895. <div class="admonition note">

  1896. <p class="admonition-title">Note</p>

  1897. <p>By default, the <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> values of str and bytes objects are

  1898. “salted” with an unpredictable random value.  Although they

  1899. remain constant within an individual Python process, they are not

  1900. predictable between repeated invocations of Python.</p>

  1901. <p>This is intended to provide protection against a denial-of-service caused

  1902. by carefully chosen inputs that exploit the worst case performance of a

  1903. dict insertion, <em>O</em>(<em>n</em><sup>2</sup>) complexity.  See

  1904. <a class="reference external" href="http://ocert.org/advisories/ocert-2011-003.html">http://ocert.org/advisories/ocert-2011-003.html</a> for details.</p>

  1905. <p>Changing hash values affects the iteration order of sets.

  1906. Python has never made guarantees about this ordering

  1907. (and it typically varies between 32-bit and 64-bit builds).</p>

  1908. <p>See also <span class="target" id="index-81"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHASHSEED"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHASHSEED</span></code></a>.</p>

  1909. </div>

  1910. <div class="versionchanged">

  1911. <p><span class="versionmodified changed">Changed in version 3.3: </span>Hash randomization is enabled by default.</p>

  1912. </div>

  1913. </dd></dl>

  1914. 

  1915. <dl class="py method">

  1916. <dt class="sig sig-object py" id="object.__bool__">

  1917. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__bool__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__bool__" title="Link to this definition">¶</a></dt>

  1918. <dd><p id="index-82">Called to implement truth value testing and the built-in operation

  1919. <code class="docutils literal notranslate"><span class="pre">bool()</span></code>; should return <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">True</span></code>.  When this method is not

  1920. defined, <a class="reference internal" href="#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code></a> is called, if it is defined, and the object is

  1921. considered true if its result is nonzero.  If a class defines neither

  1922. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code> nor <code class="xref py py-meth docutils literal notranslate"><span class="pre">__bool__()</span></code>, all its instances are considered

  1923. true.</p>

  1924. </dd></dl>

  1925. 

  1926. </section>

  1927. <section id="customizing-attribute-access">

  1928. <span id="attribute-access"></span><h3><span class="section-number">3.3.2. </span>Customizing attribute access<a class="headerlink" href="#customizing-attribute-access" title="Link to this heading">¶</a></h3>

  1929. <p>The following methods can be defined to customize the meaning of attribute

  1930. access (use of, assignment to, or deletion of <code class="docutils literal notranslate"><span class="pre">x.name</span></code>) for class instances.</p>

  1931. <dl class="py method">

  1932. <dt class="sig sig-object py" id="object.__getattr__">

  1933. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__getattr__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__getattr__" title="Link to this definition">¶</a></dt>

  1934. <dd><p>Called when the default attribute access fails with 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>

  1935. (either <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a> 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> because

  1936. <em>name</em> is not an instance attribute or an attribute in the class tree

  1937. for <code class="docutils literal notranslate"><span class="pre">self</span></code>; or <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code></a> of a <em>name</em> property raises

  1938. <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>).  This method should either return the (computed)

  1939. attribute value or raise 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> exception.</p>

  1940. <p>Note that if the attribute is found through the normal mechanism,

  1941. <a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code></a> is not called.  (This is an intentional asymmetry between

  1942. <a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code></a> and <a class="reference internal" href="#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setattr__()</span></code></a>.) This is done both for efficiency

  1943. reasons and because otherwise <a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code></a> would have no way to access

  1944. other attributes of the instance.  Note that at least for instance variables,

  1945. you can fake total control by not inserting any values in the instance attribute

  1946. dictionary (but instead inserting them in another object).  See the

  1947. <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a> method below for a way to actually get total control

  1948. over attribute access.</p>

  1949. </dd></dl>

  1950. 

  1951. <dl class="py method">

  1952. <dt class="sig sig-object py" id="object.__getattribute__">

  1953. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__getattribute__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__getattribute__" title="Link to this definition">¶</a></dt>

  1954. <dd><p>Called unconditionally to implement attribute accesses for instances of the

  1955. class. If the class also defines <a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code></a>, the latter will not be

  1956. called unless <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a> either calls it explicitly or raises an

  1957. <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>. This method should return the (computed) attribute value

  1958. or raise 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> exception. In order to avoid infinite

  1959. recursion in this method, its implementation should always call the base class

  1960. method with the same name to access any attributes it needs, for example,

  1961. <code class="docutils literal notranslate"><span class="pre">object.__getattribute__(self,</span> <span class="pre">name)</span></code>.</p>

  1962. <div class="admonition note">

  1963. <p class="admonition-title">Note</p>

  1964. <p>This method may still be bypassed when looking up special methods as the

  1965. result of implicit invocation via language syntax or

  1966. <a class="reference internal" href="#builtin-functions"><span class="std std-ref">built-in functions</span></a>.

  1967. See <a class="reference internal" href="#special-lookup"><span class="std std-ref">Special method lookup</span></a>.</p>

  1968. </div>

  1969. <p class="audit-hook"><p>For certain sensitive attribute accesses, raises an

  1970. <a class="reference internal" href="../library/sys.html#auditing"><span class="std std-ref">auditing event</span></a> <code class="docutils literal notranslate"><span class="pre">object.__getattr__</span></code> with arguments

  1971. <code class="docutils literal notranslate"><span class="pre">obj</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code>.</p>

  1972. </p>

  1973. </dd></dl>

  1974. 

  1975. <dl class="py method">

  1976. <dt class="sig sig-object py" id="object.__setattr__">

  1977. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__setattr__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__setattr__" title="Link to this definition">¶</a></dt>

  1978. <dd><p>Called when an attribute assignment is attempted.  This is called instead of

  1979. the normal mechanism (i.e. store the value in the instance dictionary).

  1980. <em>name</em> is the attribute name, <em>value</em> is the value to be assigned to it.</p>

  1981. <p>If <a class="reference internal" href="#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setattr__()</span></code></a> wants to assign to an instance attribute, it should

  1982. call the base class method with the same name, for example,

  1983. <code class="docutils literal notranslate"><span class="pre">object.__setattr__(self,</span> <span class="pre">name,</span> <span class="pre">value)</span></code>.</p>

  1984. <p class="audit-hook"><p>For certain sensitive attribute assignments, raises an

  1985. <a class="reference internal" href="../library/sys.html#auditing"><span class="std std-ref">auditing event</span></a> <code class="docutils literal notranslate"><span class="pre">object.__setattr__</span></code> with arguments

  1986. <code class="docutils literal notranslate"><span class="pre">obj</span></code>, <code class="docutils literal notranslate"><span class="pre">name</span></code>, <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>

  1987. </p>

  1988. </dd></dl>

  1989. 

  1990. <dl class="py method">

  1991. <dt class="sig sig-object py" id="object.__delattr__">

  1992. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__delattr__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__delattr__" title="Link to this definition">¶</a></dt>

  1993. <dd><p>Like <a class="reference internal" href="#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setattr__()</span></code></a> but for attribute deletion instead of assignment.  This

  1994. should only be implemented if <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">obj.name</span></code> is meaningful for the object.</p>

  1995. <p class="audit-hook"><p>For certain sensitive attribute deletions, raises an

  1996. <a class="reference internal" href="../library/sys.html#auditing"><span class="std std-ref">auditing event</span></a> <code class="docutils literal notranslate"><span class="pre">object.__delattr__</span></code> with arguments

  1997. <code class="docutils literal notranslate"><span class="pre">obj</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code>.</p>

  1998. </p>

  1999. </dd></dl>

  2000. 

  2001. <dl class="py method">

  2002. <dt class="sig sig-object py" id="object.__dir__">

  2003. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__dir__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__dir__" title="Link to this definition">¶</a></dt>

  2004. <dd><p>Called when <a class="reference internal" href="../library/functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> is called on the object. An iterable must be

  2005. returned. <a class="reference internal" href="../library/functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> converts the returned iterable to a list and sorts it.</p>

  2006. </dd></dl>

  2007. 

  2008. <section id="customizing-module-attribute-access">

  2009. <h4><span class="section-number">3.3.2.1. </span>Customizing module attribute access<a class="headerlink" href="#customizing-module-attribute-access" title="Link to this heading">¶</a></h4>

  2010. <p id="index-83">Special names <code class="docutils literal notranslate"><span class="pre">__getattr__</span></code> and <code class="docutils literal notranslate"><span class="pre">__dir__</span></code> can be also used to customize

  2011. access to module attributes. The <code class="docutils literal notranslate"><span class="pre">__getattr__</span></code> function at the module level

  2012. should accept one argument which is the name of an attribute and return the

  2013. computed value or raise 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>. If an attribute is

  2014. not found on a module object through the normal lookup, i.e.

  2015. <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__getattribute__()</span></code></a>, then <code class="docutils literal notranslate"><span class="pre">__getattr__</span></code> is searched in

  2016. the module <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> before 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>. If found,

  2017. it is called with the attribute name and the result is returned.</p>

  2018. <p>The <code class="docutils literal notranslate"><span class="pre">__dir__</span></code> function should accept no arguments, and return an iterable of

  2019. strings that represents the names accessible on module. If present, this

  2020. function overrides the standard <a class="reference internal" href="../library/functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> search on a module.</p>

  2021. <p>For a more fine grained customization of the module behavior (setting

  2022. attributes, properties, etc.), one can set the <code class="docutils literal notranslate"><span class="pre">__class__</span></code> attribute of

  2023. a module object to a subclass of <a class="reference internal" href="../library/types.html#types.ModuleType" title="types.ModuleType"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ModuleType</span></code></a>. For example:</p>

  2024. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>

  2025. <span class="kn">from</span> <span class="nn">types</span> <span class="kn">import</span> <span class="n">ModuleType</span>

  2026. 

  2027. <span class="k">class</span> <span class="nc">VerboseModule</span><span class="p">(</span><span class="n">ModuleType</span><span class="p">):</span>

  2028.     <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2029.         <span class="k">return</span> <span class="sa">f</span><span class="s1">&#39;Verbose </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s1">&#39;</span>

  2030. 

  2031.     <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">attr</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  2032.         <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Setting </span><span class="si">{</span><span class="n">attr</span><span class="si">}</span><span class="s1">...&#39;</span><span class="p">)</span>

  2033.         <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">attr</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  2034. 

  2035. <span class="n">sys</span><span class="o">.</span><span class="n">modules</span><span class="p">[</span><span class="vm">__name__</span><span class="p">]</span><span class="o">.</span><span class="vm">__class__</span> <span class="o">=</span> <span class="n">VerboseModule</span>

  2036. </pre></div>

  2037. </div>

  2038. <div class="admonition note">

  2039. <p class="admonition-title">Note</p>

  2040. <p>Defining module <code class="docutils literal notranslate"><span class="pre">__getattr__</span></code> and setting module <code class="docutils literal notranslate"><span class="pre">__class__</span></code> only

  2041. affect lookups made using the attribute access syntax – directly accessing

  2042. the module globals (whether by code within the module, or via a reference

  2043. to the module’s globals dictionary) is unaffected.</p>

  2044. </div>

  2045. <div class="versionchanged">

  2046. <p><span class="versionmodified changed">Changed in version 3.5: </span><code class="docutils literal notranslate"><span class="pre">__class__</span></code> module attribute is now writable.</p>

  2047. </div>

  2048. <div class="versionadded">

  2049. <p><span class="versionmodified added">New in version 3.7: </span><code class="docutils literal notranslate"><span class="pre">__getattr__</span></code> and <code class="docutils literal notranslate"><span class="pre">__dir__</span></code> module attributes.</p>

  2050. </div>

  2051. <div class="admonition seealso">

  2052. <p class="admonition-title">See also</p>

  2053. <dl class="simple">

  2054. <dt><span class="target" id="index-84"></span><a class="pep reference external" href="https://peps.python.org/pep-0562/"><strong>PEP 562</strong></a> - Module __getattr__ and __dir__</dt><dd><p>Describes the <code class="docutils literal notranslate"><span class="pre">__getattr__</span></code> and <code class="docutils literal notranslate"><span class="pre">__dir__</span></code> functions on modules.</p>

  2055. </dd>

  2056. </dl>

  2057. </div>

  2058. </section>

  2059. <section id="implementing-descriptors">

  2060. <span id="descriptors"></span><h4><span class="section-number">3.3.2.2. </span>Implementing Descriptors<a class="headerlink" href="#implementing-descriptors" title="Link to this heading">¶</a></h4>

  2061. <p>The following methods only apply when an instance of the class containing the

  2062. method (a so-called <em>descriptor</em> class) appears in an <em>owner</em> class (the

  2063. descriptor must be in either the owner’s class dictionary or in the class

  2064. dictionary for one of its parents).  In the examples below, “the attribute”

  2065. refers to the attribute whose name is the key of the property in the owner

  2066. class’ <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>.</p>

  2067. <dl class="py method">

  2068. <dt class="sig sig-object py" id="object.__get__">

  2069. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__get__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">instance</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">owner</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__get__" title="Link to this definition">¶</a></dt>

  2070. <dd><p>Called to get the attribute of the owner class (class attribute access) or

  2071. of an instance of that class (instance attribute access). The optional

  2072. <em>owner</em> argument is the owner class, while <em>instance</em> is the instance that

  2073. the attribute was accessed through, or <code class="docutils literal notranslate"><span class="pre">None</span></code> when the attribute is

  2074. accessed through the <em>owner</em>.</p>

  2075. <p>This method should return the computed attribute value or raise an

  2076. <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> exception.</p>

  2077. <p><span class="target" id="index-85"></span><a class="pep reference external" href="https://peps.python.org/pep-0252/"><strong>PEP 252</strong></a> specifies that <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code></a> is callable with one or two

  2078. arguments.  Python’s own built-in descriptors support this specification;

  2079. however, it is likely that some third-party tools have descriptors

  2080. that require both arguments.  Python’s own <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a>

  2081. implementation always passes in both arguments whether they are required

  2082. or not.</p>

  2083. </dd></dl>

  2084. 

  2085. <dl class="py method">

  2086. <dt class="sig sig-object py" id="object.__set__">

  2087. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__set__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">instance</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__set__" title="Link to this definition">¶</a></dt>

  2088. <dd><p>Called to set the attribute on an instance <em>instance</em> of the owner class to a

  2089. new value, <em>value</em>.</p>

  2090. <p>Note, adding <a class="reference internal" href="#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code></a> or <a class="reference internal" href="#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code></a> changes the kind of

  2091. descriptor to a “data descriptor”.  See <a class="reference internal" href="#descriptor-invocation"><span class="std std-ref">Invoking Descriptors</span></a> for

  2092. more details.</p>

  2093. </dd></dl>

  2094. 

  2095. <dl class="py method">

  2096. <dt class="sig sig-object py" id="object.__delete__">

  2097. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__delete__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">instance</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__delete__" title="Link to this definition">¶</a></dt>

  2098. <dd><p>Called to delete the attribute on an instance <em>instance</em> of the owner class.</p>

  2099. </dd></dl>

  2100. 

  2101. <p>Instances of descriptors may also have the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__objclass__</span></code> attribute

  2102. present:</p>

  2103. <dl class="py attribute">

  2104. <dt class="sig sig-object py" id="object.__objclass__">

  2105. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__objclass__</span></span><a class="headerlink" href="#object.__objclass__" title="Link to this definition">¶</a></dt>

  2106. <dd><p>The attribute <code class="xref py py-attr docutils literal notranslate"><span class="pre">__objclass__</span></code> is interpreted by the <a class="reference internal" href="../library/inspect.html#module-inspect" title="inspect: Extract information and source code from live objects."><code class="xref py py-mod docutils literal notranslate"><span class="pre">inspect</span></code></a> module

  2107. as specifying the class where this object was defined (setting this

  2108. appropriately can assist in runtime introspection of dynamic class attributes).

  2109. For callables, it may indicate that an instance of the given type (or a

  2110. subclass) is expected or required as the first positional argument (for example,

  2111. CPython sets this attribute for unbound methods that are implemented in C).</p>

  2112. </dd></dl>

  2113. 

  2114. </section>

  2115. <section id="invoking-descriptors">

  2116. <span id="descriptor-invocation"></span><h4><span class="section-number">3.3.2.3. </span>Invoking Descriptors<a class="headerlink" href="#invoking-descriptors" title="Link to this heading">¶</a></h4>

  2117. <p>In general, a descriptor is an object attribute with “binding behavior”, one

  2118. whose attribute access has been overridden by methods in the descriptor

  2119. protocol:  <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code></a>, <a class="reference internal" href="#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code></a>, and

  2120. <a class="reference internal" href="#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code></a>. If any of

  2121. those methods are defined for an object, it is said to be a descriptor.</p>

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

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

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

  2125. continuing through the base classes of <code class="docutils literal notranslate"><span class="pre">type(a)</span></code> excluding metaclasses.</p>

  2126. <p>However, if the looked-up value is an object defining one of the descriptor

  2127. methods, then Python may override the default behavior and invoke the descriptor

  2128. method instead.  Where this occurs in the precedence chain depends on which

  2129. descriptor methods were defined and how they were called.</p>

  2130. <p>The starting point for descriptor invocation is a binding, <code class="docutils literal notranslate"><span class="pre">a.x</span></code>. How the

  2131. arguments are assembled depends on <code class="docutils literal notranslate"><span class="pre">a</span></code>:</p>

  2132. <dl class="simple">

  2133. <dt>Direct Call</dt><dd><p>The simplest and least common call is when user code directly invokes a

  2134. descriptor method:    <code class="docutils literal notranslate"><span class="pre">x.__get__(a)</span></code>.</p>

  2135. </dd>

  2136. <dt>Instance Binding</dt><dd><p>If binding to an object instance, <code class="docutils literal notranslate"><span class="pre">a.x</span></code> is transformed into the call:

  2137. <code class="docutils literal notranslate"><span class="pre">type(a).__dict__['x'].__get__(a,</span> <span class="pre">type(a))</span></code>.</p>

  2138. </dd>

  2139. <dt>Class Binding</dt><dd><p>If binding to a class, <code class="docutils literal notranslate"><span class="pre">A.x</span></code> is transformed into the call:

  2140. <code class="docutils literal notranslate"><span class="pre">A.__dict__['x'].__get__(None,</span> <span class="pre">A)</span></code>.</p>

  2141. </dd>

  2142. <dt>Super Binding</dt><dd><p>A dotted lookup such as <code class="docutils literal notranslate"><span class="pre">super(A,</span> <span class="pre">a).x</span></code> searches

  2143. <code class="docutils literal notranslate"><span class="pre">a.__class__.__mro__</span></code> for a base class <code class="docutils literal notranslate"><span class="pre">B</span></code> following <code class="docutils literal notranslate"><span class="pre">A</span></code> and then

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

  2145. returned unchanged.</p>

  2146. </dd>

  2147. </dl>

  2148. <p>For instance bindings, the precedence of descriptor invocation depends on

  2149. which descriptor methods are defined.  A descriptor can define any combination

  2150. of <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code></a>, <a class="reference internal" href="#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code></a> and

  2151. <a class="reference internal" href="#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code></a>.  If it does not

  2152. define <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code>, then accessing the attribute will return the descriptor

  2153. object itself unless there is a value in the object’s instance dictionary.  If

  2154. the descriptor defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code> and/or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code>, it is a data

  2155. descriptor; if it defines neither, it is a non-data descriptor.  Normally, data

  2156. descriptors define both <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>, while non-data

  2157. descriptors have just the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> method.  Data descriptors with

  2158. <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> (and/or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__delete__()</span></code>) defined

  2159. always override a redefinition in an

  2160. instance dictionary.  In contrast, non-data descriptors can be overridden by

  2161. instances.</p>

  2162. <p>Python methods (including those decorated with

  2163. <a class="reference internal" href="../library/functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;staticmethod</span></code></a> and <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;classmethod</span></code></a>) are

  2164. implemented as non-data descriptors.  Accordingly, instances can redefine and

  2165. override methods.  This allows individual instances to acquire behaviors that

  2166. differ from other instances of the same class.</p>

  2167. <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> function is implemented as a data descriptor. Accordingly,

  2168. instances cannot override the behavior of a property.</p>

  2169. </section>

  2170. <section id="slots">

  2171. <span id="id11"></span><h4><span class="section-number">3.3.2.4. </span>__slots__<a class="headerlink" href="#slots" title="Link to this heading">¶</a></h4>

  2172. <p><em>__slots__</em> allow us to explicitly declare data members (like

  2173. properties) and deny the creation of <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> and <em>__weakref__</em>

  2174. (unless explicitly declared in <em>__slots__</em> or available in a parent.)</p>

  2175. <p>The space saved over using <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> can be significant.

  2176. Attribute lookup speed can be significantly improved as well.</p>

  2177. <dl class="py data">

  2178. <dt class="sig sig-object py" id="object.__slots__">

  2179. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__slots__</span></span><a class="headerlink" href="#object.__slots__" title="Link to this definition">¶</a></dt>

  2180. <dd><p>This class variable can be assigned a string, iterable, or sequence of

  2181. strings with variable names used by instances.  <em>__slots__</em> reserves space

  2182. for the declared variables and prevents the automatic creation of

  2183. <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>

  2184. and <em>__weakref__</em> for each instance.</p>

  2185. </dd></dl>

  2186. 

  2187. <p id="datamodel-note-slots">Notes on using <em>__slots__</em>:</p>

  2188. <ul class="simple">

  2189. <li><p>When inheriting from a class without <em>__slots__</em>, the

  2190. <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> and

  2191. <em>__weakref__</em> attribute of the instances will always be accessible.</p></li>

  2192. <li><p>Without a <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> variable, instances cannot be assigned new

  2193. variables not

  2194. listed in the <em>__slots__</em> definition.  Attempts to assign to an unlisted

  2195. variable name raises <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>. If dynamic assignment of new

  2196. variables is desired, then add <code class="docutils literal notranslate"><span class="pre">'__dict__'</span></code> to the sequence of strings in

  2197. the <em>__slots__</em> declaration.</p></li>

  2198. <li><p>Without a <em>__weakref__</em> variable for each instance, classes defining

  2199. <em>__slots__</em> do not support <a class="reference internal" href="../library/weakref.html#module-weakref" title="weakref: Support for weak references and weak dictionaries."><code class="xref py py-mod docutils literal notranslate"><span class="pre">weak</span> <span class="pre">references</span></code></a> to its instances.

  2200. If weak reference

  2201. support is needed, then add <code class="docutils literal notranslate"><span class="pre">'__weakref__'</span></code> to the sequence of strings in the

  2202. <em>__slots__</em> declaration.</p></li>

  2203. <li><p><em>__slots__</em> are implemented at the class level by creating <a class="reference internal" href="#descriptors"><span class="std std-ref">descriptors</span></a>

  2204. for each variable name.  As a result, class attributes

  2205. cannot be used to set default values for instance variables defined by

  2206. <em>__slots__</em>; otherwise, the class attribute would overwrite the descriptor

  2207. assignment.</p></li>

  2208. <li><p>The action of a <em>__slots__</em> declaration is not limited to the class

  2209. where it is defined.  <em>__slots__</em> declared in parents are available in

  2210. child classes. However, child subclasses will get a <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> and

  2211. <em>__weakref__</em> unless they also define <em>__slots__</em> (which should only

  2212. contain names of any <em>additional</em> slots).</p></li>

  2213. <li><p>If a class defines a slot also defined in a base class, the instance variable

  2214. defined by the base class slot is inaccessible (except by retrieving its

  2215. descriptor directly from the base class). This renders the meaning of the

  2216. program undefined.  In the future, a check may be added to prevent this.</p></li>

  2217. <li><p><a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> will be raised if nonempty <em>__slots__</em> are defined for a

  2218. class derived from a

  2219. <a class="reference internal" href="../c-api/typeobj.html#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">&quot;variable-length&quot;</span> <span class="pre">built-in</span> <span class="pre">type</span></code></a> such as

  2220. <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>, <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, and <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>.</p></li>

  2221. <li><p>Any non-string <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iterable</span></a> may be assigned to <em>__slots__</em>.</p></li>

  2222. <li><p>If a <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dictionary</span></code></a> is used to assign <em>__slots__</em>, the dictionary

  2223. keys will be used as the slot names. The values of the dictionary can be used

  2224. to provide per-attribute docstrings that will be recognised by

  2225. <a class="reference internal" href="../library/inspect.html#inspect.getdoc" title="inspect.getdoc"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect.getdoc()</span></code></a> and displayed in the output of <a class="reference internal" href="../library/functions.html#help" title="help"><code class="xref py py-func docutils literal notranslate"><span class="pre">help()</span></code></a>.</p></li>

  2226. <li><p><a class="reference internal" href="../library/stdtypes.html#instance.__class__" title="instance.__class__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__class__</span></code></a> assignment works only if both classes have the

  2227. same <em>__slots__</em>.</p></li>

  2228. <li><p><a class="reference internal" href="../tutorial/classes.html#tut-multiple"><span class="std std-ref">Multiple inheritance</span></a> with multiple slotted parent

  2229. classes can be used,

  2230. but only one parent is allowed to have attributes created by slots

  2231. (the other bases must have empty slot layouts) - violations raise

  2232. <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p></li>

  2233. <li><p>If an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> is used for <em>__slots__</em> then a <a class="reference internal" href="../glossary.html#term-descriptor"><span class="xref std std-term">descriptor</span></a> is

  2234. created for each

  2235. of the iterator’s values. However, the <em>__slots__</em> attribute will be an empty

  2236. iterator.</p></li>

  2237. </ul>

  2238. </section>

  2239. </section>

  2240. <section id="customizing-class-creation">

  2241. <span id="class-customization"></span><h3><span class="section-number">3.3.3. </span>Customizing class creation<a class="headerlink" href="#customizing-class-creation" title="Link to this heading">¶</a></h3>

  2242. <p>Whenever a class inherits from another class, <a class="reference internal" href="#object.__init_subclass__" title="object.__init_subclass__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init_subclass__()</span></code></a> is

  2243. called on the parent class. This way, it is possible to write classes which

  2244. change the behavior of subclasses. This is closely related to class

  2245. decorators, but where class decorators only affect the specific class they’re

  2246. applied to, <code class="docutils literal notranslate"><span class="pre">__init_subclass__</span></code> solely applies to future subclasses of the

  2247. class defining the method.</p>

  2248. <dl class="py method">

  2249. <dt class="sig sig-object py" id="object.__init_subclass__">

  2250. <em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__init_subclass__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cls</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__init_subclass__" title="Link to this definition">¶</a></dt>

  2251. <dd><p>This method is called whenever the containing class is subclassed.

  2252. <em>cls</em> is then the new subclass. If defined as a normal instance method,

  2253. this method is implicitly converted to a class method.</p>

  2254. <p>Keyword arguments which are given to a new class are passed to

  2255. the parent class’s <code class="docutils literal notranslate"><span class="pre">__init_subclass__</span></code>. For compatibility with

  2256. other classes using <code class="docutils literal notranslate"><span class="pre">__init_subclass__</span></code>, one should take out the

  2257. needed keyword arguments and pass the others over to the base

  2258. class, as in:</p>

  2259. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Philosopher</span><span class="p">:</span>

  2260.     <span class="k">def</span> <span class="nf">__init_subclass__</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="n">default_name</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  2261.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">__init_subclass__</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  2262.         <span class="bp">cls</span><span class="o">.</span><span class="n">default_name</span> <span class="o">=</span> <span class="n">default_name</span>

  2263. 

  2264. <span class="k">class</span> <span class="nc">AustralianPhilosopher</span><span class="p">(</span><span class="n">Philosopher</span><span class="p">,</span> <span class="n">default_name</span><span class="o">=</span><span class="s2">&quot;Bruce&quot;</span><span class="p">):</span>

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

  2266. </pre></div>

  2267. </div>

  2268. <p>The default implementation <code class="docutils literal notranslate"><span class="pre">object.__init_subclass__</span></code> does

  2269. nothing, but raises an error if it is called with any arguments.</p>

  2270. <div class="admonition note">

  2271. <p class="admonition-title">Note</p>

  2272. <p>The metaclass hint <code class="docutils literal notranslate"><span class="pre">metaclass</span></code> is consumed by the rest of the type

  2273. machinery, and is never passed to <code class="docutils literal notranslate"><span class="pre">__init_subclass__</span></code> implementations.

  2274. The actual metaclass (rather than the explicit hint) can be accessed as

  2275. <code class="docutils literal notranslate"><span class="pre">type(cls)</span></code>.</p>

  2276. </div>

  2277. <div class="versionadded">

  2278. <p><span class="versionmodified added">New in version 3.6.</span></p>

  2279. </div>

  2280. </dd></dl>

  2281. 

  2282. <p>When a class is created, <code class="xref py py-meth docutils literal notranslate"><span class="pre">type.__new__()</span></code> scans the class variables

  2283. and makes callbacks to those with a <a class="reference internal" href="#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code></a> hook.</p>

  2284. <dl class="py method">

  2285. <dt class="sig sig-object py" id="object.__set_name__">

  2286. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__set_name__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">owner</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__set_name__" title="Link to this definition">¶</a></dt>

  2287. <dd><p>Automatically called at the time the owning class <em>owner</em> is

  2288. created. The object has been assigned to <em>name</em> in that class:</p>

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

  2290.     <span class="n">x</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>  <span class="c1"># Automatically calls: x.__set_name__(A, &#39;x&#39;)</span>

  2291. </pre></div>

  2292. </div>

  2293. <p>If the class variable is assigned after the class is created,

  2294. <a class="reference internal" href="#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code></a> will not be called automatically.

  2295. If needed, <a class="reference internal" href="#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code></a> can be called directly:</p>

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

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

  2298. 

  2299. <span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>

  2300. <span class="n">A</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">c</span>                  <span class="c1"># The hook is not called</span>

  2301. <span class="n">c</span><span class="o">.</span><span class="n">__set_name__</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="s1">&#39;x&#39;</span><span class="p">)</span>   <span class="c1"># Manually invoke the hook</span>

  2302. </pre></div>

  2303. </div>

  2304. <p>See <a class="reference internal" href="#class-object-creation"><span class="std std-ref">Creating the class object</span></a> for more details.</p>

  2305. <div class="versionadded">

  2306. <p><span class="versionmodified added">New in version 3.6.</span></p>

  2307. </div>

  2308. </dd></dl>

  2309. 

  2310. <section id="metaclasses">

  2311. <span id="id12"></span><h4><span class="section-number">3.3.3.1. </span>Metaclasses<a class="headerlink" href="#metaclasses" title="Link to this heading">¶</a></h4>

  2312. <p id="index-86">By default, classes are constructed using <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal notranslate"><span class="pre">type()</span></code></a>. The class body is

  2313. executed in a new namespace and the class name is bound locally to the

  2314. result of <code class="docutils literal notranslate"><span class="pre">type(name,</span> <span class="pre">bases,</span> <span class="pre">namespace)</span></code>.</p>

  2315. <p>The class creation process can be customized by passing the <code class="docutils literal notranslate"><span class="pre">metaclass</span></code>

  2316. keyword argument in the class definition line, or by inheriting from an

  2317. existing class that included such an argument. In the following example,

  2318. both <code class="docutils literal notranslate"><span class="pre">MyClass</span></code> and <code class="docutils literal notranslate"><span class="pre">MySubclass</span></code> are instances of <code class="docutils literal notranslate"><span class="pre">Meta</span></code>:</p>

  2319. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Meta</span><span class="p">(</span><span class="nb">type</span><span class="p">):</span>

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

  2321. 

  2322. <span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="n">metaclass</span><span class="o">=</span><span class="n">Meta</span><span class="p">):</span>

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

  2324. 

  2325. <span class="k">class</span> <span class="nc">MySubclass</span><span class="p">(</span><span class="n">MyClass</span><span class="p">):</span>

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

  2327. </pre></div>

  2328. </div>

  2329. <p>Any other keyword arguments that are specified in the class definition are

  2330. passed through to all metaclass operations described below.</p>

  2331. <p>When a class definition is executed, the following steps occur:</p>

  2332. <ul class="simple">

  2333. <li><p>MRO entries are resolved;</p></li>

  2334. <li><p>the appropriate metaclass is determined;</p></li>

  2335. <li><p>the class namespace is prepared;</p></li>

  2336. <li><p>the class body is executed;</p></li>

  2337. <li><p>the class object is created.</p></li>

  2338. </ul>

  2339. </section>

  2340. <section id="resolving-mro-entries">

  2341. <h4><span class="section-number">3.3.3.2. </span>Resolving MRO entries<a class="headerlink" href="#resolving-mro-entries" title="Link to this heading">¶</a></h4>

  2342. <dl class="py method">

  2343. <dt class="sig sig-object py" id="object.__mro_entries__">

  2344. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__mro_entries__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">bases</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__mro_entries__" title="Link to this definition">¶</a></dt>

  2345. <dd><p>If a base that appears in a class definition is not an instance of

  2346. <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>, then an <code class="xref py py-meth docutils literal notranslate"><span class="pre">__mro_entries__()</span></code> method is searched on the base.

  2347. If an <code class="xref py py-meth docutils literal notranslate"><span class="pre">__mro_entries__()</span></code> method is found, the base is substituted with the

  2348. result of a call to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__mro_entries__()</span></code> when creating the class.

  2349. The method is called with the original bases tuple

  2350. passed to the <em>bases</em> parameter, and must return a tuple

  2351. of classes that will be used instead of the base. The returned tuple may be

  2352. empty: in these cases, the original base is ignored.</p>

  2353. </dd></dl>

  2354. 

  2355. <div class="admonition seealso">

  2356. <p class="admonition-title">See also</p>

  2357. <dl class="simple">

  2358. <dt><a class="reference internal" href="../library/types.html#types.resolve_bases" title="types.resolve_bases"><code class="xref py py-func docutils literal notranslate"><span class="pre">types.resolve_bases()</span></code></a></dt><dd><p>Dynamically resolve bases that are not instances of <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>.</p>

  2359. </dd>

  2360. <dt><a class="reference internal" href="../library/types.html#types.get_original_bases" title="types.get_original_bases"><code class="xref py py-func docutils literal notranslate"><span class="pre">types.get_original_bases()</span></code></a></dt><dd><p>Retrieve a class’s “original bases” prior to modifications by

  2361. <a class="reference internal" href="#object.__mro_entries__" title="object.__mro_entries__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__mro_entries__()</span></code></a>.</p>

  2362. </dd>

  2363. <dt><span class="target" id="index-87"></span><a class="pep reference external" href="https://peps.python.org/pep-0560/"><strong>PEP 560</strong></a></dt><dd><p>Core support for typing module and generic types.</p>

  2364. </dd>

  2365. </dl>

  2366. </div>

  2367. </section>

  2368. <section id="determining-the-appropriate-metaclass">

  2369. <h4><span class="section-number">3.3.3.3. </span>Determining the appropriate metaclass<a class="headerlink" href="#determining-the-appropriate-metaclass" title="Link to this heading">¶</a></h4>

  2370. <p id="index-88">The appropriate metaclass for a class definition is determined as follows:</p>

  2371. <ul class="simple">

  2372. <li><p>if no bases and no explicit metaclass are given, then <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal notranslate"><span class="pre">type()</span></code></a> is used;</p></li>

  2373. <li><p>if an explicit metaclass is given and it is <em>not</em> an instance of

  2374. <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal notranslate"><span class="pre">type()</span></code></a>, then it is used directly as the metaclass;</p></li>

  2375. <li><p>if an instance of <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal notranslate"><span class="pre">type()</span></code></a> is given as the explicit metaclass, or

  2376. bases are defined, then the most derived metaclass is used.</p></li>

  2377. </ul>

  2378. <p>The most derived metaclass is selected from the explicitly specified

  2379. metaclass (if any) and the metaclasses (i.e. <code class="docutils literal notranslate"><span class="pre">type(cls)</span></code>) of all specified

  2380. base classes. The most derived metaclass is one which is a subtype of <em>all</em>

  2381. of these candidate metaclasses. If none of the candidate metaclasses meets

  2382. that criterion, then the class definition will fail with <code class="docutils literal notranslate"><span class="pre">TypeError</span></code>.</p>

  2383. </section>

  2384. <section id="preparing-the-class-namespace">

  2385. <span id="prepare"></span><h4><span class="section-number">3.3.3.4. </span>Preparing the class namespace<a class="headerlink" href="#preparing-the-class-namespace" title="Link to this heading">¶</a></h4>

  2386. <p id="index-89">Once the appropriate metaclass has been identified, then the class namespace

  2387. is prepared. If the metaclass has a <code class="docutils literal notranslate"><span class="pre">__prepare__</span></code> attribute, it is called

  2388. as <code class="docutils literal notranslate"><span class="pre">namespace</span> <span class="pre">=</span> <span class="pre">metaclass.__prepare__(name,</span> <span class="pre">bases,</span> <span class="pre">**kwds)</span></code> (where the

  2389. additional keyword arguments, if any, come from the class definition). The

  2390. <code class="docutils literal notranslate"><span class="pre">__prepare__</span></code> method should be implemented as a

  2391. <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>. The

  2392. namespace returned by <code class="docutils literal notranslate"><span class="pre">__prepare__</span></code> is passed in to <code class="docutils literal notranslate"><span class="pre">__new__</span></code>, but when

  2393. the final class object is created the namespace is copied into a new <code class="docutils literal notranslate"><span class="pre">dict</span></code>.</p>

  2394. <p>If the metaclass has no <code class="docutils literal notranslate"><span class="pre">__prepare__</span></code> attribute, then the class namespace

  2395. is initialised as an empty ordered mapping.</p>

  2396. <div class="admonition seealso">

  2397. <p class="admonition-title">See also</p>

  2398. <dl class="simple">

  2399. <dt><span class="target" id="index-90"></span><a class="pep reference external" href="https://peps.python.org/pep-3115/"><strong>PEP 3115</strong></a> - Metaclasses in Python 3000</dt><dd><p>Introduced the <code class="docutils literal notranslate"><span class="pre">__prepare__</span></code> namespace hook</p>

  2400. </dd>

  2401. </dl>

  2402. </div>

  2403. </section>

  2404. <section id="executing-the-class-body">

  2405. <h4><span class="section-number">3.3.3.5. </span>Executing the class body<a class="headerlink" href="#executing-the-class-body" title="Link to this heading">¶</a></h4>

  2406. <p id="index-91">The class body is executed (approximately) as

  2407. <code class="docutils literal notranslate"><span class="pre">exec(body,</span> <span class="pre">globals(),</span> <span class="pre">namespace)</span></code>. The key difference from a normal

  2408. call to <a class="reference internal" href="../library/functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> is that lexical scoping allows the class body (including

  2409. any methods) to reference names from the current and outer scopes when the

  2410. class definition occurs inside a function.</p>

  2411. <p>However, even when the class definition occurs inside the function, methods

  2412. defined inside the class still cannot see names defined at the class scope.

  2413. Class variables must be accessed through the first parameter of instance or

  2414. class methods, or through the implicit lexically scoped <code class="docutils literal notranslate"><span class="pre">__class__</span></code> reference

  2415. described in the next section.</p>

  2416. </section>

  2417. <section id="creating-the-class-object">

  2418. <span id="class-object-creation"></span><h4><span class="section-number">3.3.3.6. </span>Creating the class object<a class="headerlink" href="#creating-the-class-object" title="Link to this heading">¶</a></h4>

  2419. <p id="index-92">Once the class namespace has been populated by executing the class body,

  2420. the class object is created by calling

  2421. <code class="docutils literal notranslate"><span class="pre">metaclass(name,</span> <span class="pre">bases,</span> <span class="pre">namespace,</span> <span class="pre">**kwds)</span></code> (the additional keywords

  2422. passed here are the same as those passed to <code class="docutils literal notranslate"><span class="pre">__prepare__</span></code>).</p>

  2423. <p>This class object is the one that will be referenced by the zero-argument

  2424. form of <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>. <code class="docutils literal notranslate"><span class="pre">__class__</span></code> is an implicit closure reference

  2425. created by the compiler if any methods in a class body refer to either

  2426. <code class="docutils literal notranslate"><span class="pre">__class__</span></code> or <code class="docutils literal notranslate"><span class="pre">super</span></code>. This allows the zero argument form of

  2427. <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> to correctly identify the class being defined based on

  2428. lexical scoping, while the class or instance that was used to make the

  2429. current call is identified based on the first argument passed to the method.</p>

  2430. <div class="impl-detail compound">

  2431. <p><strong>CPython implementation detail:</strong> In CPython 3.6 and later, the <code class="docutils literal notranslate"><span class="pre">__class__</span></code> cell is passed to the metaclass

  2432. as a <code class="docutils literal notranslate"><span class="pre">__classcell__</span></code> entry in the class namespace. If present, this must

  2433. be propagated up to the <code class="docutils literal notranslate"><span class="pre">type.__new__</span></code> call in order for the class to be

  2434. initialised correctly.

  2435. Failing to do so will result in a <a class="reference internal" href="../library/exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> in Python 3.8.</p>

  2436. </div>

  2437. <p>When using the default metaclass <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 any metaclass that ultimately

  2438. calls <code class="docutils literal notranslate"><span class="pre">type.__new__</span></code>, the following additional customization steps are

  2439. invoked after creating the class object:</p>

  2440. <ol class="arabic simple">

  2441. <li><p>The <code class="docutils literal notranslate"><span class="pre">type.__new__</span></code> method collects all of the attributes in the class

  2442. namespace that define a <a class="reference internal" href="#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code></a> method;</p></li>

  2443. <li><p>Those <code class="docutils literal notranslate"><span class="pre">__set_name__</span></code> methods are called with the class

  2444. being defined and the assigned name of that particular attribute;</p></li>

  2445. <li><p>The <a class="reference internal" href="#object.__init_subclass__" title="object.__init_subclass__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init_subclass__()</span></code></a> hook is called on the

  2446. immediate parent of the new class in its method resolution order.</p></li>

  2447. </ol>

  2448. <p>After the class object is created, it is passed to the class decorators

  2449. included in the class definition (if any) and the resulting object is bound

  2450. in the local namespace as the defined class.</p>

  2451. <p>When a new class is created by <code class="docutils literal notranslate"><span class="pre">type.__new__</span></code>, the object provided as the

  2452. namespace parameter is copied to a new ordered mapping and the original

  2453. object is discarded. The new copy is wrapped in a read-only proxy, which

  2454. becomes the <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> attribute of the class object.</p>

  2455. <div class="admonition seealso">

  2456. <p class="admonition-title">See also</p>

  2457. <dl class="simple">

  2458. <dt><span class="target" id="index-93"></span><a class="pep reference external" href="https://peps.python.org/pep-3135/"><strong>PEP 3135</strong></a> - New super</dt><dd><p>Describes the implicit <code class="docutils literal notranslate"><span class="pre">__class__</span></code> closure reference</p>

  2459. </dd>

  2460. </dl>

  2461. </div>

  2462. </section>

  2463. <section id="uses-for-metaclasses">

  2464. <h4><span class="section-number">3.3.3.7. </span>Uses for metaclasses<a class="headerlink" href="#uses-for-metaclasses" title="Link to this heading">¶</a></h4>

  2465. <p>The potential uses for metaclasses are boundless. Some ideas that have been

  2466. explored include enum, logging, interface checking, automatic delegation,

  2467. automatic property creation, proxies, frameworks, and automatic resource

  2468. locking/synchronization.</p>

  2469. </section>

  2470. </section>

  2471. <section id="customizing-instance-and-subclass-checks">

  2472. <h3><span class="section-number">3.3.4. </span>Customizing instance and subclass checks<a class="headerlink" href="#customizing-instance-and-subclass-checks" title="Link to this heading">¶</a></h3>

  2473. <p>The following methods are used to override the default behavior of the

  2474. <a class="reference internal" href="../library/functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> and <a class="reference internal" href="../library/functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">issubclass()</span></code></a> built-in functions.</p>

  2475. <p>In particular, the metaclass <a class="reference internal" href="../library/abc.html#abc.ABCMeta" title="abc.ABCMeta"><code class="xref py py-class docutils literal notranslate"><span class="pre">abc.ABCMeta</span></code></a> implements these methods in

  2476. order to allow the addition of Abstract Base Classes (ABCs) as “virtual base

  2477. classes” to any class or type (including built-in types), including other

  2478. ABCs.</p>

  2479. <dl class="py method">

  2480. <dt class="sig sig-object py" id="class.__instancecheck__">

  2481. <span class="sig-prename descclassname"><span class="pre">class.</span></span><span class="sig-name descname"><span class="pre">__instancecheck__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">instance</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#class.__instancecheck__" title="Link to this definition">¶</a></dt>

  2482. <dd><p>Return true if <em>instance</em> should be considered a (direct or indirect)

  2483. instance of <em>class</em>. If defined, called to implement <code class="docutils literal notranslate"><span class="pre">isinstance(instance,</span>

  2484. <span class="pre">class)</span></code>.</p>

  2485. </dd></dl>

  2486. 

  2487. <dl class="py method">

  2488. <dt class="sig sig-object py" id="class.__subclasscheck__">

  2489. <span class="sig-prename descclassname"><span class="pre">class.</span></span><span class="sig-name descname"><span class="pre">__subclasscheck__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">subclass</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#class.__subclasscheck__" title="Link to this definition">¶</a></dt>

  2490. <dd><p>Return true if <em>subclass</em> should be considered a (direct or indirect)

  2491. subclass of <em>class</em>.  If defined, called to implement <code class="docutils literal notranslate"><span class="pre">issubclass(subclass,</span>

  2492. <span class="pre">class)</span></code>.</p>

  2493. </dd></dl>

  2494. 

  2495. <p>Note that these methods are looked up on the type (metaclass) of a class.  They

  2496. cannot be defined as class methods in the actual class.  This is consistent with

  2497. the lookup of special methods that are called on instances, only in this

  2498. case the instance is itself a class.</p>

  2499. <div class="admonition seealso">

  2500. <p class="admonition-title">See also</p>

  2501. <dl class="simple">

  2502. <dt><span class="target" id="index-94"></span><a class="pep reference external" href="https://peps.python.org/pep-3119/"><strong>PEP 3119</strong></a> - Introducing Abstract Base Classes</dt><dd><p>Includes the specification for customizing <a class="reference internal" href="../library/functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> and

  2503. <a class="reference internal" href="../library/functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">issubclass()</span></code></a> behavior through <a class="reference internal" href="#class.__instancecheck__" title="class.__instancecheck__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__instancecheck__()</span></code></a> and

  2504. <a class="reference internal" href="#class.__subclasscheck__" title="class.__subclasscheck__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__subclasscheck__()</span></code></a>, with motivation for this functionality

  2505. in the context of adding Abstract Base Classes (see the <a class="reference internal" href="../library/abc.html#module-abc" title="abc: Abstract base classes according to :pep:`3119`."><code class="xref py py-mod docutils literal notranslate"><span class="pre">abc</span></code></a>

  2506. module) to the language.</p>

  2507. </dd>

  2508. </dl>

  2509. </div>

  2510. </section>

  2511. <section id="emulating-generic-types">

  2512. <h3><span class="section-number">3.3.5. </span>Emulating generic types<a class="headerlink" href="#emulating-generic-types" title="Link to this heading">¶</a></h3>

  2513. <p>When using <a class="reference internal" href="../glossary.html#term-annotation"><span class="xref std std-term">type annotations</span></a>, it is often useful to

  2514. <em>parameterize</em> a <a class="reference internal" href="../glossary.html#term-generic-type"><span class="xref std std-term">generic type</span></a> using Python’s square-brackets notation.

  2515. For example, the annotation <code class="docutils literal notranslate"><span class="pre">list[int]</span></code> might be used to signify a

  2516. <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> in which all the elements are of type <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>.</p>

  2517. <div class="admonition seealso">

  2518. <p class="admonition-title">See also</p>

  2519. <dl class="simple">

  2520. <dt><span class="target" id="index-95"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a> - Type Hints</dt><dd><p>Introducing Python’s framework for type annotations</p>

  2521. </dd>

  2522. <dt><a class="reference internal" href="../library/stdtypes.html#types-genericalias"><span class="std std-ref">Generic Alias Types</span></a></dt><dd><p>Documentation for objects representing parameterized generic classes</p>

  2523. </dd>

  2524. <dt><a class="reference internal" href="../library/typing.html#generics"><span class="std std-ref">Generics</span></a>, <a class="reference internal" href="../library/typing.html#user-defined-generics"><span class="std std-ref">user-defined generics</span></a> and <a class="reference internal" href="../library/typing.html#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal notranslate"><span class="pre">typing.Generic</span></code></a></dt><dd><p>Documentation on how to implement generic classes that can be

  2525. parameterized at runtime and understood by static type-checkers.</p>

  2526. </dd>

  2527. </dl>

  2528. </div>

  2529. <p>A class can <em>generally</em> only be parameterized if it defines the special

  2530. class method <code class="docutils literal notranslate"><span class="pre">__class_getitem__()</span></code>.</p>

  2531. <dl class="py method">

  2532. <dt class="sig sig-object py" id="object.__class_getitem__">

  2533. <em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__class_getitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cls</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__class_getitem__" title="Link to this definition">¶</a></dt>

  2534. <dd><p>Return an object representing the specialization of a generic class

  2535. by type arguments found in <em>key</em>.</p>

  2536. <p>When defined on a class, <code class="docutils literal notranslate"><span class="pre">__class_getitem__()</span></code> is automatically a class

  2537. method. As such, there is no need for it to be decorated with

  2538. <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;classmethod</span></code></a> when it is defined.</p>

  2539. </dd></dl>

  2540. 

  2541. <section id="the-purpose-of-class-getitem">

  2542. <h4><span class="section-number">3.3.5.1. </span>The purpose of <em>__class_getitem__</em><a class="headerlink" href="#the-purpose-of-class-getitem" title="Link to this heading">¶</a></h4>

  2543. <p>The purpose of <a class="reference internal" href="#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a> is to allow runtime

  2544. parameterization of standard-library generic classes in order to more easily

  2545. apply <a class="reference internal" href="../glossary.html#term-type-hint"><span class="xref std std-term">type hints</span></a> to these classes.</p>

  2546. <p>To implement custom generic classes that can be parameterized at runtime and

  2547. understood by static type-checkers, users should either inherit from a standard

  2548. library class that already implements <a class="reference internal" href="#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a>, or

  2549. inherit from <a class="reference internal" href="../library/typing.html#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal notranslate"><span class="pre">typing.Generic</span></code></a>, which has its own implementation of

  2550. <code class="docutils literal notranslate"><span class="pre">__class_getitem__()</span></code>.</p>

  2551. <p>Custom implementations of <a class="reference internal" href="#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a> on classes defined

  2552. outside of the standard library may not be understood by third-party

  2553. type-checkers such as mypy. Using <code class="docutils literal notranslate"><span class="pre">__class_getitem__()</span></code> on any class for

  2554. purposes other than type hinting is discouraged.</p>

  2555. </section>

  2556. <section id="class-getitem-versus-getitem">

  2557. <span id="classgetitem-versus-getitem"></span><h4><span class="section-number">3.3.5.2. </span><em>__class_getitem__</em> versus <em>__getitem__</em><a class="headerlink" href="#class-getitem-versus-getitem" title="Link to this heading">¶</a></h4>

  2558. <p>Usually, the <a class="reference internal" href="expressions.html#subscriptions"><span class="std std-ref">subscription</span></a> of an object using square

  2559. brackets will call the <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> instance method defined on

  2560. the object’s class. However, if the object being subscribed is itself a class,

  2561. the class method <a class="reference internal" href="#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a> may be called instead.

  2562. <code class="docutils literal notranslate"><span class="pre">__class_getitem__()</span></code> should return a <a class="reference internal" href="../library/stdtypes.html#types-genericalias"><span class="std std-ref">GenericAlias</span></a>

  2563. object if it is properly defined.</p>

  2564. <p>Presented with the <a class="reference internal" href="../glossary.html#term-expression"><span class="xref std std-term">expression</span></a> <code class="docutils literal notranslate"><span class="pre">obj[x]</span></code>, the Python interpreter

  2565. follows something like the following process to decide whether

  2566. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> or <a class="reference internal" href="#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a> should be

  2567. called:</p>

  2568. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">inspect</span> <span class="kn">import</span> <span class="n">isclass</span>

  2569. 

  2570. <span class="k">def</span> <span class="nf">subscribe</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>

  2571. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Return the result of the expression &#39;obj[x]&#39;&quot;&quot;&quot;</span>

  2572. 

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

  2574. 

  2575.     <span class="c1"># If the class of obj defines __getitem__,</span>

  2576.     <span class="c1"># call class_of_obj.__getitem__(obj, x)</span>

  2577.     <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">class_of_obj</span><span class="p">,</span> <span class="s1">&#39;__getitem__&#39;</span><span class="p">):</span>

  2578.         <span class="k">return</span> <span class="n">class_of_obj</span><span class="o">.</span><span class="fm">__getitem__</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span>

  2579. 

  2580.     <span class="c1"># Else, if obj is a class and defines __class_getitem__,</span>

  2581.     <span class="c1"># call obj.__class_getitem__(x)</span>

  2582.     <span class="k">elif</span> <span class="n">isclass</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="ow">and</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s1">&#39;__class_getitem__&#39;</span><span class="p">):</span>

  2583.         <span class="k">return</span> <span class="n">obj</span><span class="o">.</span><span class="n">__class_getitem__</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>

  2584. 

  2585.     <span class="c1"># Else, raise an exception</span>

  2586.     <span class="k">else</span><span class="p">:</span>

  2587.         <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span>

  2588.             <span class="sa">f</span><span class="s2">&quot;&#39;</span><span class="si">{</span><span class="n">class_of_obj</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s2">&#39; object is not subscriptable&quot;</span>

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

  2590. </pre></div>

  2591. </div>

  2592. <p>In Python, all classes are themselves instances of other classes. The class of

  2593. a class is known as that class’s <a class="reference internal" href="../glossary.html#term-metaclass"><span class="xref std std-term">metaclass</span></a>, and most classes have the

  2594. <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> class as their metaclass. <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> does not define

  2595. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>, meaning that expressions such as <code class="docutils literal notranslate"><span class="pre">list[int]</span></code>,

  2596. <code class="docutils literal notranslate"><span class="pre">dict[str,</span> <span class="pre">float]</span></code> and <code class="docutils literal notranslate"><span class="pre">tuple[str,</span> <span class="pre">bytes]</span></code> all result in

  2597. <a class="reference internal" href="#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a> being called:</p>

  2598. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># list has class &quot;type&quot; as its metaclass, like most classes:</span>

  2599. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>

  2600. <span class="go">&lt;class &#39;type&#39;&gt;</span>

  2601. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="nb">dict</span><span class="p">)</span> <span class="o">==</span> <span class="nb">type</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span> <span class="o">==</span> <span class="nb">type</span><span class="p">(</span><span class="nb">tuple</span><span class="p">)</span> <span class="o">==</span> <span class="nb">type</span><span class="p">(</span><span class="nb">str</span><span class="p">)</span> <span class="o">==</span> <span class="nb">type</span><span class="p">(</span><span class="nb">bytes</span><span class="p">)</span>

  2602. <span class="go">True</span>

  2603. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># &quot;list[int]&quot; calls &quot;list.__class_getitem__(int)&quot;</span>

  2604. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">[</span><span class="nb">int</span><span class="p">]</span>

  2605. <span class="go">list[int]</span>

  2606. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># list.__class_getitem__ returns a GenericAlias object:</span>

  2607. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="nb">list</span><span class="p">[</span><span class="nb">int</span><span class="p">])</span>

  2608. <span class="go">&lt;class &#39;types.GenericAlias&#39;&gt;</span>

  2609. </pre></div>

  2610. </div>

  2611. <p>However, if a class has a custom metaclass that defines

  2612. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>, subscribing the class may result in different

  2613. behaviour. An example of this can be found in the <a class="reference internal" href="../library/enum.html#module-enum" title="enum: Implementation of an enumeration class."><code class="xref py py-mod docutils literal notranslate"><span class="pre">enum</span></code></a> module:</p>

  2614. <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">enum</span> <span class="kn">import</span> <span class="n">Enum</span>

  2615. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Menu</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  2616. <span class="gp">... </span><span class="w">    </span><span class="sd">&quot;&quot;&quot;A breakfast menu&quot;&quot;&quot;</span>

  2617. <span class="gp">... </span>    <span class="n">SPAM</span> <span class="o">=</span> <span class="s1">&#39;spam&#39;</span>

  2618. <span class="gp">... </span>    <span class="n">BACON</span> <span class="o">=</span> <span class="s1">&#39;bacon&#39;</span>

  2619. <span class="gp">...</span>

  2620. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># Enum classes have a custom metaclass:</span>

  2621. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">Menu</span><span class="p">)</span>

  2622. <span class="go">&lt;class &#39;enum.EnumMeta&#39;&gt;</span>

  2623. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># EnumMeta defines __getitem__,</span>

  2624. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># so __class_getitem__ is not called,</span>

  2625. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># and the result is not a GenericAlias object:</span>

  2626. <span class="gp">&gt;&gt;&gt; </span><span class="n">Menu</span><span class="p">[</span><span class="s1">&#39;SPAM&#39;</span><span class="p">]</span>

  2627. <span class="go">&lt;Menu.SPAM: &#39;spam&#39;&gt;</span>

  2628. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">Menu</span><span class="p">[</span><span class="s1">&#39;SPAM&#39;</span><span class="p">])</span>

  2629. <span class="go">&lt;enum &#39;Menu&#39;&gt;</span>

  2630. </pre></div>

  2631. </div>

  2632. <div class="admonition seealso">

  2633. <p class="admonition-title">See also</p>

  2634. <dl class="simple">

  2635. <dt><span class="target" id="index-96"></span><a class="pep reference external" href="https://peps.python.org/pep-0560/"><strong>PEP 560</strong></a> - Core Support for typing module and generic types</dt><dd><p>Introducing <a class="reference internal" href="#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a>, and outlining when a

  2636. <a class="reference internal" href="expressions.html#subscriptions"><span class="std std-ref">subscription</span></a> results in <code class="docutils literal notranslate"><span class="pre">__class_getitem__()</span></code>

  2637. being called instead of <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a></p>

  2638. </dd>

  2639. </dl>

  2640. </div>

  2641. </section>

  2642. </section>

  2643. <section id="emulating-callable-objects">

  2644. <span id="id13"></span><h3><span class="section-number">3.3.6. </span>Emulating callable objects<a class="headerlink" href="#emulating-callable-objects" title="Link to this heading">¶</a></h3>

  2645. <dl class="py method">

  2646. <dt class="sig sig-object py" id="object.__call__">

  2647. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__call__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">args...</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#object.__call__" title="Link to this definition">¶</a></dt>

  2648. <dd><p id="index-97">Called when the instance is “called” as a function; if this method is defined,

  2649. <code class="docutils literal notranslate"><span class="pre">x(arg1,</span> <span class="pre">arg2,</span> <span class="pre">...)</span></code> roughly translates to <code class="docutils literal notranslate"><span class="pre">type(x).__call__(x,</span> <span class="pre">arg1,</span> <span class="pre">...)</span></code>.</p>

  2650. </dd></dl>

  2651. 

  2652. </section>

  2653. <section id="emulating-container-types">

  2654. <span id="sequence-types"></span><h3><span class="section-number">3.3.7. </span>Emulating container types<a class="headerlink" href="#emulating-container-types" title="Link to this heading">¶</a></h3>

  2655. <p>The following methods can be defined to implement container objects.  Containers

  2656. usually are <a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequences</span></a> (such as <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">lists</span></code></a> or

  2657. <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuples</span></code></a>) or <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mappings</span></a> (like

  2658. <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dictionaries</span></code></a>),

  2659. but can represent other containers as well.  The first set of methods is used

  2660. either to emulate a sequence or to emulate a mapping; the difference is that for

  2661. a sequence, the allowable keys should be the integers <em>k</em> for which <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">&lt;=</span> <span class="pre">k</span> <span class="pre">&lt;</span>

  2662. <span class="pre">N</span></code> where <em>N</em> is the length of the sequence, or <a class="reference internal" href="../library/functions.html#slice" title="slice"><code class="xref py py-class docutils literal notranslate"><span class="pre">slice</span></code></a> objects, which define a

  2663. range of items.  It is also recommended that mappings provide the methods

  2664. <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">values()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">items()</span></code>, <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">clear()</span></code>,

  2665. <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">pop()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">popitem()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">copy()</span></code>, and

  2666. <code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code> behaving similar to those for Python’s standard <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dictionary</span></code></a>

  2667. objects.  The <a class="reference internal" href="../library/collections.abc.html#module-collections.abc" title="collections.abc: Abstract base classes for containers"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code></a> module provides a

  2668. <a class="reference internal" href="../library/collections.abc.html#collections.abc.MutableMapping" title="collections.abc.MutableMapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableMapping</span></code></a>

  2669. <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a> to help create those methods from a base set of

  2670. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>, <a class="reference internal" href="#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a>,

  2671. <a class="reference internal" href="#object.__delitem__" title="object.__delitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delitem__()</span></code></a>, and <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code>.

  2672. Mutable sequences should provide methods <code class="xref py py-meth docutils literal notranslate"><span class="pre">append()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">count()</span></code>,

  2673. <code class="xref py py-meth docutils literal notranslate"><span class="pre">index()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">extend()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">insert()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">pop()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">remove()</span></code>,

  2674. <code class="xref py py-meth docutils literal notranslate"><span class="pre">reverse()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">sort()</span></code>, like Python standard <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>

  2675. objects. Finally,

  2676. sequence types should implement addition (meaning concatenation) and

  2677. multiplication (meaning repetition) by defining the methods

  2678. <a class="reference internal" href="#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a>, <a class="reference internal" href="#object.__radd__" title="object.__radd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__radd__()</span></code></a>, <a class="reference internal" href="#object.__iadd__" title="object.__iadd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iadd__()</span></code></a>,

  2679. <a class="reference internal" href="#object.__mul__" title="object.__mul__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__mul__()</span></code></a>, <a class="reference internal" href="#object.__rmul__" title="object.__rmul__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rmul__()</span></code></a> and <a class="reference internal" href="#object.__imul__" title="object.__imul__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__imul__()</span></code></a>

  2680. described below; they should not define other numerical

  2681. operators.  It is recommended that both mappings and sequences implement the

  2682. <a class="reference internal" href="#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a> method to allow efficient use of the <code class="docutils literal notranslate"><span class="pre">in</span></code>

  2683. operator; for

  2684. mappings, <code class="docutils literal notranslate"><span class="pre">in</span></code> should search the mapping’s keys; for sequences, it should

  2685. search through the values.  It is further recommended that both mappings and

  2686. sequences implement the <a class="reference internal" href="#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> method to allow efficient iteration

  2687. through the container; for mappings, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code> should iterate

  2688. through the object’s keys; for sequences, it should iterate through the values.</p>

  2689. <dl class="py method">

  2690. <dt class="sig sig-object py" id="object.__len__">

  2691. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__len__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__len__" title="Link to this definition">¶</a></dt>

  2692. <dd><p id="index-98">Called to implement the built-in function <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a>.  Should return the length

  2693. of the object, an integer <code class="docutils literal notranslate"><span class="pre">&gt;=</span></code> 0.  Also, an object that doesn’t define a

  2694. <a class="reference internal" href="#object.__bool__" title="object.__bool__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__bool__()</span></code></a> method and whose <code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code> method returns zero is

  2695. considered to be false in a Boolean context.</p>

  2696. <div class="impl-detail compound">

  2697. <p><strong>CPython implementation detail:</strong> In CPython, the length is required to be at most <a class="reference internal" href="../library/sys.html#sys.maxsize" title="sys.maxsize"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.maxsize</span></code></a>.

  2698. If the length is larger than <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.maxsize</span></code> some features (such as

  2699. <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal notranslate"><span class="pre">len()</span></code></a>) may raise <a class="reference internal" href="../library/exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a>.  To prevent raising

  2700. <code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code> by truth value testing, an object must define a

  2701. <a class="reference internal" href="#object.__bool__" title="object.__bool__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__bool__()</span></code></a> method.</p>

  2702. </div>

  2703. </dd></dl>

  2704. 

  2705. <dl class="py method">

  2706. <dt class="sig sig-object py" id="object.__length_hint__">

  2707. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__length_hint__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__length_hint__" title="Link to this definition">¶</a></dt>

  2708. <dd><p>Called to implement <a class="reference internal" href="../library/operator.html#operator.length_hint" title="operator.length_hint"><code class="xref py py-func docutils literal notranslate"><span class="pre">operator.length_hint()</span></code></a>. Should return an estimated

  2709. length for the object (which may be greater or less than the actual length).

  2710. The length must be an integer <code class="docutils literal notranslate"><span class="pre">&gt;=</span></code> 0. The return value may also be

  2711. <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a>, which is treated the same as if the

  2712. <code class="docutils literal notranslate"><span class="pre">__length_hint__</span></code> method didn’t exist at all. This method is purely an

  2713. optimization and is never required for correctness.</p>

  2714. <div class="versionadded">

  2715. <p><span class="versionmodified added">New in version 3.4.</span></p>

  2716. </div>

  2717. </dd></dl>

  2718. 

  2719. <div class="admonition note" id="index-99">

  2720. <p class="admonition-title">Note</p>

  2721. <p>Slicing is done exclusively with the following three methods.  A call like</p>

  2722. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">a</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="n">b</span>

  2723. </pre></div>

  2724. </div>

  2725. <p>is translated to</p>

  2726. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">a</span><span class="p">[</span><span class="nb">slice</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="kc">None</span><span class="p">)]</span> <span class="o">=</span> <span class="n">b</span>

  2727. </pre></div>

  2728. </div>

  2729. <p>and so forth.  Missing slice items are always filled in with <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>

  2730. </div>

  2731. <dl class="py method">

  2732. <dt class="sig sig-object py" id="object.__getitem__">

  2733. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__getitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__getitem__" title="Link to this definition">¶</a></dt>

  2734. <dd><p>Called to implement evaluation of <code class="docutils literal notranslate"><span class="pre">self[key]</span></code>. For <a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequence</span></a> types,

  2735. the accepted keys should be integers. Optionally, they may support

  2736. <a class="reference internal" href="../library/functions.html#slice" title="slice"><code class="xref py py-class docutils literal notranslate"><span class="pre">slice</span></code></a> objects as well.  Negative index support is also optional.

  2737. If <em>key</em> is

  2738. of an inappropriate type, <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> may be raised; if <em>key</em> is a value

  2739. outside the set of indexes for the sequence (after any special

  2740. interpretation of negative values), <a class="reference internal" href="../library/exceptions.html#IndexError" title="IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> should be raised. For

  2741. <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mapping</span></a> types, if <em>key</em> is missing (not in the container),

  2742. <a class="reference internal" href="../library/exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> should be raised.</p>

  2743. <div class="admonition note">

  2744. <p class="admonition-title">Note</p>

  2745. <p><a class="reference internal" href="compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> loops expect that an <a class="reference internal" href="../library/exceptions.html#IndexError" title="IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> will be raised for

  2746. illegal indexes to allow proper detection of the end of the sequence.</p>

  2747. </div>

  2748. <div class="admonition note">

  2749. <p class="admonition-title">Note</p>

  2750. <p>When <a class="reference internal" href="expressions.html#subscriptions"><span class="std std-ref">subscripting</span></a> a <em>class</em>, the special

  2751. class method <a class="reference internal" href="#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a> may be called instead of

  2752. <code class="docutils literal notranslate"><span class="pre">__getitem__()</span></code>. See <a class="reference internal" href="#classgetitem-versus-getitem"><span class="std std-ref">__class_getitem__ versus __getitem__</span></a> for more

  2753. details.</p>

  2754. </div>

  2755. </dd></dl>

  2756. 

  2757. <dl class="py method">

  2758. <dt class="sig sig-object py" id="object.__setitem__">

  2759. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__setitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__setitem__" title="Link to this definition">¶</a></dt>

  2760. <dd><p>Called to implement assignment to <code class="docutils literal notranslate"><span class="pre">self[key]</span></code>.  Same note as for

  2761. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>.  This should only be implemented for mappings if the

  2762. objects support changes to the values for keys, or if new keys can be added, or

  2763. for sequences if elements can be replaced.  The same exceptions should be raised

  2764. for improper <em>key</em> values as for the <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> method.</p>

  2765. </dd></dl>

  2766. 

  2767. <dl class="py method">

  2768. <dt class="sig sig-object py" id="object.__delitem__">

  2769. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__delitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__delitem__" title="Link to this definition">¶</a></dt>

  2770. <dd><p>Called to implement deletion of <code class="docutils literal notranslate"><span class="pre">self[key]</span></code>.  Same note as for

  2771. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>.  This should only be implemented for mappings if the

  2772. objects support removal of keys, or for sequences if elements can be removed

  2773. from the sequence.  The same exceptions should be raised for improper <em>key</em>

  2774. values as for the <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> method.</p>

  2775. </dd></dl>

  2776. 

  2777. <dl class="py method">

  2778. <dt class="sig sig-object py" id="object.__missing__">

  2779. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__missing__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__missing__" title="Link to this definition">¶</a></dt>

  2780. <dd><p>Called by <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>.<a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> to implement <code class="docutils literal notranslate"><span class="pre">self[key]</span></code> for dict subclasses

  2781. when key is not in the dictionary.</p>

  2782. </dd></dl>

  2783. 

  2784. <dl class="py method">

  2785. <dt class="sig sig-object py" id="object.__iter__">

  2786. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__iter__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__iter__" title="Link to this definition">¶</a></dt>

  2787. <dd><p>This method is called when an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> is required for a container.

  2788. This method should return a new iterator object that can iterate over all the

  2789. objects in the container.  For mappings, it should iterate over the keys of

  2790. the container.</p>

  2791. </dd></dl>

  2792. 

  2793. <dl class="py method">

  2794. <dt class="sig sig-object py" id="object.__reversed__">

  2795. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__reversed__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__reversed__" title="Link to this definition">¶</a></dt>

  2796. <dd><p>Called (if present) by the <a class="reference internal" href="../library/functions.html#reversed" title="reversed"><code class="xref py py-func docutils literal notranslate"><span class="pre">reversed()</span></code></a> built-in to implement

  2797. reverse iteration.  It should return a new iterator object that iterates

  2798. over all the objects in the container in reverse order.</p>

  2799. <p>If the <a class="reference internal" href="#object.__reversed__" title="object.__reversed__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__reversed__()</span></code></a> method is not provided, the <a class="reference internal" href="../library/functions.html#reversed" title="reversed"><code class="xref py py-func docutils literal notranslate"><span class="pre">reversed()</span></code></a>

  2800. built-in will fall back to using the sequence protocol (<a class="reference internal" href="#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code></a> and

  2801. <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>).  Objects that support the sequence protocol should

  2802. only provide <a class="reference internal" href="#object.__reversed__" title="object.__reversed__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__reversed__()</span></code></a> if they can provide an implementation

  2803. that is more efficient than the one provided by <a class="reference internal" href="../library/functions.html#reversed" title="reversed"><code class="xref py py-func docutils literal notranslate"><span class="pre">reversed()</span></code></a>.</p>

  2804. </dd></dl>

  2805. 

  2806. <p>The membership test operators (<a class="reference internal" href="expressions.html#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a> and <a class="reference internal" href="expressions.html#not-in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span> <span class="pre">in</span></code></a>) are normally

  2807. implemented as an iteration through a container. However, container objects can

  2808. supply the following special method with a more efficient implementation, which

  2809. also does not require the object be iterable.</p>

  2810. <dl class="py method">

  2811. <dt class="sig sig-object py" id="object.__contains__">

  2812. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__contains__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">item</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__contains__" title="Link to this definition">¶</a></dt>

  2813. <dd><p>Called to implement membership test operators.  Should return true if <em>item</em>

  2814. is in <em>self</em>, false otherwise.  For mapping objects, this should consider the

  2815. keys of the mapping rather than the values or the key-item pairs.</p>

  2816. <p>For objects that don’t define <a class="reference internal" href="#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a>, the membership test first

  2817. tries iteration via <a class="reference internal" href="#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a>, then the old sequence iteration

  2818. protocol via <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>, see <a class="reference internal" href="expressions.html#membership-test-details"><span class="std std-ref">this section in the language

  2819. reference</span></a>.</p>

  2820. </dd></dl>

  2821. 

  2822. </section>

  2823. <section id="emulating-numeric-types">

  2824. <span id="numeric-types"></span><h3><span class="section-number">3.3.8. </span>Emulating numeric types<a class="headerlink" href="#emulating-numeric-types" title="Link to this heading">¶</a></h3>

  2825. <p>The following methods can be defined to emulate numeric objects. Methods

  2826. corresponding to operations that are not supported by the particular kind of

  2827. number implemented (e.g., bitwise operations for non-integral numbers) should be

  2828. left undefined.</p>

  2829. <dl class="py method">

  2830. <dt class="sig sig-object py" id="object.__add__">

  2831. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__add__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__add__" title="Link to this definition">¶</a></dt>

  2832. <dt class="sig sig-object py" id="object.__sub__">

  2833. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__sub__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__sub__" title="Link to this definition">¶</a></dt>

  2834. <dt class="sig sig-object py" id="object.__mul__">

  2835. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__mul__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__mul__" title="Link to this definition">¶</a></dt>

  2836. <dt class="sig sig-object py" id="object.__matmul__">

  2837. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__matmul__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__matmul__" title="Link to this definition">¶</a></dt>

  2838. <dt class="sig sig-object py" id="object.__truediv__">

  2839. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__truediv__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__truediv__" title="Link to this definition">¶</a></dt>

  2840. <dt class="sig sig-object py" id="object.__floordiv__">

  2841. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__floordiv__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__floordiv__" title="Link to this definition">¶</a></dt>

  2842. <dt class="sig sig-object py" id="object.__mod__">

  2843. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__mod__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__mod__" title="Link to this definition">¶</a></dt>

  2844. <dt class="sig sig-object py" id="object.__divmod__">

  2845. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__divmod__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__divmod__" title="Link to this definition">¶</a></dt>

  2846. <dt class="sig sig-object py" id="object.__pow__">

  2847. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__pow__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">modulo</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#object.__pow__" title="Link to this definition">¶</a></dt>

  2848. <dt class="sig sig-object py" id="object.__lshift__">

  2849. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__lshift__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__lshift__" title="Link to this definition">¶</a></dt>

  2850. <dt class="sig sig-object py" id="object.__rshift__">

  2851. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rshift__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rshift__" title="Link to this definition">¶</a></dt>

  2852. <dt class="sig sig-object py" id="object.__and__">

  2853. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__and__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__and__" title="Link to this definition">¶</a></dt>

  2854. <dt class="sig sig-object py" id="object.__xor__">

  2855. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__xor__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__xor__" title="Link to this definition">¶</a></dt>

  2856. <dt class="sig sig-object py" id="object.__or__">

  2857. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__or__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__or__" title="Link to this definition">¶</a></dt>

  2858. <dd><p id="index-100">These methods are called to implement the binary arithmetic operations

  2859. (<code class="docutils literal notranslate"><span class="pre">+</span></code>, <code class="docutils literal notranslate"><span class="pre">-</span></code>, <code class="docutils literal notranslate"><span class="pre">*</span></code>, <code class="docutils literal notranslate"><span class="pre">&#64;</span></code>, <code class="docutils literal notranslate"><span class="pre">/</span></code>, <code class="docutils literal notranslate"><span class="pre">//</span></code>, <code class="docutils literal notranslate"><span class="pre">%</span></code>, <a class="reference internal" href="../library/functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">divmod()</span></code></a>,

  2860. <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal notranslate"><span class="pre">pow()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">**</span></code>, <code class="docutils literal notranslate"><span class="pre">&lt;&lt;</span></code>, <code class="docutils literal notranslate"><span class="pre">&gt;&gt;</span></code>, <code class="docutils literal notranslate"><span class="pre">&amp;</span></code>, <code class="docutils literal notranslate"><span class="pre">^</span></code>, <code class="docutils literal notranslate"><span class="pre">|</span></code>).  For instance, to

  2861. evaluate the expression <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">+</span> <span class="pre">y</span></code>, where <em>x</em> is an instance of a class that

  2862. has an <a class="reference internal" href="#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a> method, <code class="docutils literal notranslate"><span class="pre">type(x).__add__(x,</span> <span class="pre">y)</span></code> is called.  The

  2863. <a class="reference internal" href="#object.__divmod__" title="object.__divmod__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__divmod__()</span></code></a> method should be the equivalent to using

  2864. <a class="reference internal" href="#object.__floordiv__" title="object.__floordiv__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__floordiv__()</span></code></a> and <a class="reference internal" href="#object.__mod__" title="object.__mod__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__mod__()</span></code></a>; it should not be related to

  2865. <a class="reference internal" href="#object.__truediv__" title="object.__truediv__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__truediv__()</span></code></a>.  Note that <a class="reference internal" href="#object.__pow__" title="object.__pow__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__pow__()</span></code></a> should be defined to accept

  2866. an optional third argument if the ternary version of the built-in <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal notranslate"><span class="pre">pow()</span></code></a>

  2867. function is to be supported.</p>

  2868. <p>If one of those methods does not support the operation with the supplied

  2869. arguments, it should return <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a>.</p>

  2870. </dd></dl>

  2871. 

  2872. <dl class="py method">

  2873. <dt class="sig sig-object py" id="object.__radd__">

  2874. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__radd__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__radd__" title="Link to this definition">¶</a></dt>

  2875. <dt class="sig sig-object py" id="object.__rsub__">

  2876. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rsub__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rsub__" title="Link to this definition">¶</a></dt>

  2877. <dt class="sig sig-object py" id="object.__rmul__">

  2878. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rmul__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rmul__" title="Link to this definition">¶</a></dt>

  2879. <dt class="sig sig-object py" id="object.__rmatmul__">

  2880. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rmatmul__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rmatmul__" title="Link to this definition">¶</a></dt>

  2881. <dt class="sig sig-object py" id="object.__rtruediv__">

  2882. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rtruediv__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rtruediv__" title="Link to this definition">¶</a></dt>

  2883. <dt class="sig sig-object py" id="object.__rfloordiv__">

  2884. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rfloordiv__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rfloordiv__" title="Link to this definition">¶</a></dt>

  2885. <dt class="sig sig-object py" id="object.__rmod__">

  2886. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rmod__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rmod__" title="Link to this definition">¶</a></dt>

  2887. <dt class="sig sig-object py" id="object.__rdivmod__">

  2888. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rdivmod__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rdivmod__" title="Link to this definition">¶</a></dt>

  2889. <dt class="sig sig-object py" id="object.__rpow__">

  2890. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rpow__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">modulo</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#object.__rpow__" title="Link to this definition">¶</a></dt>

  2891. <dt class="sig sig-object py" id="object.__rlshift__">

  2892. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rlshift__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rlshift__" title="Link to this definition">¶</a></dt>

  2893. <dt class="sig sig-object py" id="object.__rrshift__">

  2894. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rrshift__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rrshift__" title="Link to this definition">¶</a></dt>

  2895. <dt class="sig sig-object py" id="object.__rand__">

  2896. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rand__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rand__" title="Link to this definition">¶</a></dt>

  2897. <dt class="sig sig-object py" id="object.__rxor__">

  2898. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__rxor__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__rxor__" title="Link to this definition">¶</a></dt>

  2899. <dt class="sig sig-object py" id="object.__ror__">

  2900. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ror__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__ror__" title="Link to this definition">¶</a></dt>

  2901. <dd><p id="index-101">These methods are called to implement the binary arithmetic operations

  2902. (<code class="docutils literal notranslate"><span class="pre">+</span></code>, <code class="docutils literal notranslate"><span class="pre">-</span></code>, <code class="docutils literal notranslate"><span class="pre">*</span></code>, <code class="docutils literal notranslate"><span class="pre">&#64;</span></code>, <code class="docutils literal notranslate"><span class="pre">/</span></code>, <code class="docutils literal notranslate"><span class="pre">//</span></code>, <code class="docutils literal notranslate"><span class="pre">%</span></code>, <a class="reference internal" href="../library/functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">divmod()</span></code></a>,

  2903. <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal notranslate"><span class="pre">pow()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">**</span></code>, <code class="docutils literal notranslate"><span class="pre">&lt;&lt;</span></code>, <code class="docutils literal notranslate"><span class="pre">&gt;&gt;</span></code>, <code class="docutils literal notranslate"><span class="pre">&amp;</span></code>, <code class="docutils literal notranslate"><span class="pre">^</span></code>, <code class="docutils literal notranslate"><span class="pre">|</span></code>) with reflected

  2904. (swapped) operands.  These functions are only called if the left operand does

  2905. not support the corresponding operation <a class="footnote-reference brackets" href="#id19" id="id14" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a> and the operands are of different

  2906. types. <a class="footnote-reference brackets" href="#id20" id="id15" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a> For instance, to evaluate the expression <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span></code>, where <em>y</em> is

  2907. an instance of a class that has an <a class="reference internal" href="#object.__rsub__" title="object.__rsub__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rsub__()</span></code></a> method,

  2908. <code class="docutils literal notranslate"><span class="pre">type(y).__rsub__(y,</span> <span class="pre">x)</span></code> is called if <code class="docutils literal notranslate"><span class="pre">type(x).__sub__(x,</span> <span class="pre">y)</span></code> returns

  2909. <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a>.</p>

  2910. <p id="index-102">Note that ternary <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal notranslate"><span class="pre">pow()</span></code></a> will not try calling <a class="reference internal" href="#object.__rpow__" title="object.__rpow__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__rpow__()</span></code></a> (the

  2911. coercion rules would become too complicated).</p>

  2912. <div class="admonition note">

  2913. <p class="admonition-title">Note</p>

  2914. <p>If the right operand’s type is a subclass of the left operand’s type and

  2915. that subclass provides a different implementation of the reflected method

  2916. for the operation, this method will be called before the left operand’s

  2917. non-reflected method. This behavior allows subclasses to override their

  2918. ancestors’ operations.</p>

  2919. </div>

  2920. </dd></dl>

  2921. 

  2922. <dl class="py method">

  2923. <dt class="sig sig-object py" id="object.__iadd__">

  2924. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__iadd__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__iadd__" title="Link to this definition">¶</a></dt>

  2925. <dt class="sig sig-object py" id="object.__isub__">

  2926. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__isub__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__isub__" title="Link to this definition">¶</a></dt>

  2927. <dt class="sig sig-object py" id="object.__imul__">

  2928. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__imul__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__imul__" title="Link to this definition">¶</a></dt>

  2929. <dt class="sig sig-object py" id="object.__imatmul__">

  2930. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__imatmul__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__imatmul__" title="Link to this definition">¶</a></dt>

  2931. <dt class="sig sig-object py" id="object.__itruediv__">

  2932. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__itruediv__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__itruediv__" title="Link to this definition">¶</a></dt>

  2933. <dt class="sig sig-object py" id="object.__ifloordiv__">

  2934. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ifloordiv__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__ifloordiv__" title="Link to this definition">¶</a></dt>

  2935. <dt class="sig sig-object py" id="object.__imod__">

  2936. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__imod__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__imod__" title="Link to this definition">¶</a></dt>

  2937. <dt class="sig sig-object py" id="object.__ipow__">

  2938. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ipow__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">modulo</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#object.__ipow__" title="Link to this definition">¶</a></dt>

  2939. <dt class="sig sig-object py" id="object.__ilshift__">

  2940. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ilshift__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__ilshift__" title="Link to this definition">¶</a></dt>

  2941. <dt class="sig sig-object py" id="object.__irshift__">

  2942. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__irshift__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__irshift__" title="Link to this definition">¶</a></dt>

  2943. <dt class="sig sig-object py" id="object.__iand__">

  2944. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__iand__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__iand__" title="Link to this definition">¶</a></dt>

  2945. <dt class="sig sig-object py" id="object.__ixor__">

  2946. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ixor__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__ixor__" title="Link to this definition">¶</a></dt>

  2947. <dt class="sig sig-object py" id="object.__ior__">

  2948. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ior__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">other</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__ior__" title="Link to this definition">¶</a></dt>

  2949. <dd><p>These methods are called to implement the augmented arithmetic assignments

  2950. (<code class="docutils literal notranslate"><span class="pre">+=</span></code>, <code class="docutils literal notranslate"><span class="pre">-=</span></code>, <code class="docutils literal notranslate"><span class="pre">*=</span></code>, <code class="docutils literal notranslate"><span class="pre">&#64;=</span></code>, <code class="docutils literal notranslate"><span class="pre">/=</span></code>, <code class="docutils literal notranslate"><span class="pre">//=</span></code>, <code class="docutils literal notranslate"><span class="pre">%=</span></code>, <code class="docutils literal notranslate"><span class="pre">**=</span></code>, <code class="docutils literal notranslate"><span class="pre">&lt;&lt;=</span></code>,

  2951. <code class="docutils literal notranslate"><span class="pre">&gt;&gt;=</span></code>, <code class="docutils literal notranslate"><span class="pre">&amp;=</span></code>, <code class="docutils literal notranslate"><span class="pre">^=</span></code>, <code class="docutils literal notranslate"><span class="pre">|=</span></code>).  These methods should attempt to do the

  2952. operation in-place (modifying <em>self</em>) and return the result (which could be,

  2953. but does not have to be, <em>self</em>).  If a specific method is not defined, or if

  2954. that method returns <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a>, the

  2955. augmented assignment falls back to the normal methods.  For instance, if <em>x</em>

  2956. is an instance of a class with an <a class="reference internal" href="#object.__iadd__" title="object.__iadd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iadd__()</span></code></a> method, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">+=</span> <span class="pre">y</span></code> is

  2957. equivalent to <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">x.__iadd__(y)</span></code> . If <a class="reference internal" href="#object.__iadd__" title="object.__iadd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iadd__()</span></code></a> does not exist, or if <code class="docutils literal notranslate"><span class="pre">x.__iadd__(y)</span></code>

  2958. returns <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code>, <code class="docutils literal notranslate"><span class="pre">x.__add__(y)</span></code> and

  2959. <code class="docutils literal notranslate"><span class="pre">y.__radd__(x)</span></code> are considered, as with the evaluation of <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">+</span> <span class="pre">y</span></code>. In

  2960. certain situations, augmented assignment can result in unexpected errors (see

  2961. <a class="reference internal" href="../faq/programming.html#faq-augmented-assignment-tuple-error"><span class="std std-ref">Why does a_tuple[i] += [‘item’] raise an exception when the addition works?</span></a>), but this behavior is in fact

  2962. part of the data model.</p>

  2963. </dd></dl>

  2964. 

  2965. <dl class="py method">

  2966. <dt class="sig sig-object py" id="object.__neg__">

  2967. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__neg__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__neg__" title="Link to this definition">¶</a></dt>

  2968. <dt class="sig sig-object py" id="object.__pos__">

  2969. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__pos__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__pos__" title="Link to this definition">¶</a></dt>

  2970. <dt class="sig sig-object py" id="object.__abs__">

  2971. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__abs__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__abs__" title="Link to this definition">¶</a></dt>

  2972. <dt class="sig sig-object py" id="object.__invert__">

  2973. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__invert__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__invert__" title="Link to this definition">¶</a></dt>

  2974. <dd><p id="index-103">Called to implement the unary arithmetic operations (<code class="docutils literal notranslate"><span class="pre">-</span></code>, <code class="docutils literal notranslate"><span class="pre">+</span></code>, <a class="reference internal" href="../library/functions.html#abs" title="abs"><code class="xref py py-func docutils literal notranslate"><span class="pre">abs()</span></code></a>

  2975. and <code class="docutils literal notranslate"><span class="pre">~</span></code>).</p>

  2976. </dd></dl>

  2977. 

  2978. <dl class="py method">

  2979. <dt class="sig sig-object py" id="object.__complex__">

  2980. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__complex__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__complex__" title="Link to this definition">¶</a></dt>

  2981. <dt class="sig sig-object py" id="object.__int__">

  2982. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__int__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__int__" title="Link to this definition">¶</a></dt>

  2983. <dt class="sig sig-object py" id="object.__float__">

  2984. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__float__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__float__" title="Link to this definition">¶</a></dt>

  2985. <dd><p id="index-104">Called to implement the built-in functions <a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-func docutils literal notranslate"><span class="pre">complex()</span></code></a>,

  2986. <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a> and <a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-func docutils literal notranslate"><span class="pre">float()</span></code></a>.  Should return a value

  2987. of the appropriate type.</p>

  2988. </dd></dl>

  2989. 

  2990. <dl class="py method">

  2991. <dt class="sig sig-object py" id="object.__index__">

  2992. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__index__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__index__" title="Link to this definition">¶</a></dt>

  2993. <dd><p>Called to implement <a class="reference internal" href="../library/operator.html#operator.index" title="operator.index"><code class="xref py py-func docutils literal notranslate"><span class="pre">operator.index()</span></code></a>, and whenever Python needs to

  2994. losslessly convert the numeric object to an integer object (such as in

  2995. slicing, or in the built-in <a class="reference internal" href="../library/functions.html#bin" title="bin"><code class="xref py py-func docutils literal notranslate"><span class="pre">bin()</span></code></a>, <a class="reference internal" href="../library/functions.html#hex" title="hex"><code class="xref py py-func docutils literal notranslate"><span class="pre">hex()</span></code></a> and <a class="reference internal" href="../library/functions.html#oct" title="oct"><code class="xref py py-func docutils literal notranslate"><span class="pre">oct()</span></code></a>

  2996. functions). Presence of this method indicates that the numeric object is

  2997. an integer type.  Must return an integer.</p>

  2998. <p>If <a class="reference internal" href="#object.__int__" title="object.__int__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__int__()</span></code></a>, <a class="reference internal" href="#object.__float__" title="object.__float__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__float__()</span></code></a> and <a class="reference internal" href="#object.__complex__" title="object.__complex__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__complex__()</span></code></a> are not

  2999. defined then corresponding built-in functions <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a>, <a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-func docutils literal notranslate"><span class="pre">float()</span></code></a>

  3000. and <a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-func docutils literal notranslate"><span class="pre">complex()</span></code></a> fall back to <a class="reference internal" href="#object.__index__" title="object.__index__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__index__()</span></code></a>.</p>

  3001. </dd></dl>

  3002. 

  3003. <dl class="py method">

  3004. <dt class="sig sig-object py" id="object.__round__">

  3005. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__round__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">ndigits</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#object.__round__" title="Link to this definition">¶</a></dt>

  3006. <dt class="sig sig-object py" id="object.__trunc__">

  3007. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__trunc__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__trunc__" title="Link to this definition">¶</a></dt>

  3008. <dt class="sig sig-object py" id="object.__floor__">

  3009. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__floor__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__floor__" title="Link to this definition">¶</a></dt>

  3010. <dt class="sig sig-object py" id="object.__ceil__">

  3011. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__ceil__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__ceil__" title="Link to this definition">¶</a></dt>

  3012. <dd><p id="index-105">Called to implement the built-in function <a class="reference internal" href="../library/functions.html#round" title="round"><code class="xref py py-func docutils literal notranslate"><span class="pre">round()</span></code></a> and <a class="reference internal" href="../library/math.html#module-math" title="math: Mathematical functions (sin() etc.)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">math</span></code></a>

  3013. functions <a class="reference internal" href="../library/math.html#math.trunc" title="math.trunc"><code class="xref py py-func docutils literal notranslate"><span class="pre">trunc()</span></code></a>, <a class="reference internal" href="../library/math.html#math.floor" title="math.floor"><code class="xref py py-func docutils literal notranslate"><span class="pre">floor()</span></code></a> and <a class="reference internal" href="../library/math.html#math.ceil" title="math.ceil"><code class="xref py py-func docutils literal notranslate"><span class="pre">ceil()</span></code></a>.

  3014. Unless <em>ndigits</em> is passed to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__round__()</span></code> all these methods should

  3015. return the value of the object truncated to an <a class="reference internal" href="../library/numbers.html#numbers.Integral" title="numbers.Integral"><code class="xref py py-class docutils literal notranslate"><span class="pre">Integral</span></code></a>

  3016. (typically 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>).</p>

  3017. <p>The built-in function <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a> falls back to <a class="reference internal" href="#object.__trunc__" title="object.__trunc__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__trunc__()</span></code></a> if neither

  3018. <a class="reference internal" href="#object.__int__" title="object.__int__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__int__()</span></code></a> nor <a class="reference internal" href="#object.__index__" title="object.__index__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__index__()</span></code></a> is defined.</p>

  3019. <div class="versionchanged">

  3020. <p><span class="versionmodified changed">Changed in version 3.11: </span>The delegation of <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a> to <a class="reference internal" href="#object.__trunc__" title="object.__trunc__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__trunc__()</span></code></a> is deprecated.</p>

  3021. </div>

  3022. </dd></dl>

  3023. 

  3024. </section>

  3025. <section id="with-statement-context-managers">

  3026. <span id="context-managers"></span><h3><span class="section-number">3.3.9. </span>With Statement Context Managers<a class="headerlink" href="#with-statement-context-managers" title="Link to this heading">¶</a></h3>

  3027. <p>A <em class="dfn">context manager</em> is an object that defines the runtime context to be

  3028. established when executing a <a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement. The context manager

  3029. handles the entry into, and the exit from, the desired runtime context for the

  3030. execution of the block of code.  Context managers are normally invoked using the

  3031. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code> statement (described in section <a class="reference internal" href="compound_stmts.html#with"><span class="std std-ref">The with statement</span></a>), but can also be

  3032. used by directly invoking their methods.</p>

  3033. <p id="index-106">Typical uses of context managers include saving and restoring various kinds of

  3034. global state, locking and unlocking resources, closing opened files, etc.</p>

  3035. <p>For more information on context managers, see <a class="reference internal" href="../library/stdtypes.html#typecontextmanager"><span class="std std-ref">Context Manager Types</span></a>.</p>

  3036. <dl class="py method">

  3037. <dt class="sig sig-object py" id="object.__enter__">

  3038. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__enter__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__enter__" title="Link to this definition">¶</a></dt>

  3039. <dd><p>Enter the runtime context related to this object. The <a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement

  3040. will bind this method’s return value to the target(s) specified in the

  3041. <code class="xref std std-keyword docutils literal notranslate"><span class="pre">as</span></code> clause of the statement, if any.</p>

  3042. </dd></dl>

  3043. 

  3044. <dl class="py method">

  3045. <dt class="sig sig-object py" id="object.__exit__">

  3046. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__exit__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_type</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_value</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">traceback</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__exit__" title="Link to this definition">¶</a></dt>

  3047. <dd><p>Exit the runtime context related to this object. The parameters describe the

  3048. exception that caused the context to be exited. If the context was exited

  3049. without an exception, all three arguments will be <a class="reference internal" href="../library/constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.</p>

  3050. <p>If an exception is supplied, and the method wishes to suppress the exception

  3051. (i.e., prevent it from being propagated), it should return a true value.

  3052. Otherwise, the exception will be processed normally upon exit from this method.</p>

  3053. <p>Note that <a class="reference internal" href="#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> methods should not reraise the passed-in exception;

  3054. this is the caller’s responsibility.</p>

  3055. </dd></dl>

  3056. 

  3057. <div class="admonition seealso">

  3058. <p class="admonition-title">See also</p>

  3059. <dl class="simple">

  3060. <dt><span class="target" id="index-107"></span><a class="pep reference external" href="https://peps.python.org/pep-0343/"><strong>PEP 343</strong></a> - The “with” statement</dt><dd><p>The specification, background, and examples for the Python <a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a>

  3061. statement.</p>

  3062. </dd>

  3063. </dl>

  3064. </div>

  3065. </section>

  3066. <section id="customizing-positional-arguments-in-class-pattern-matching">

  3067. <span id="class-pattern-matching"></span><h3><span class="section-number">3.3.10. </span>Customizing positional arguments in class pattern matching<a class="headerlink" href="#customizing-positional-arguments-in-class-pattern-matching" title="Link to this heading">¶</a></h3>

  3068. <p>When using a class name in a pattern, positional arguments in the pattern are not

  3069. allowed by default, i.e. <code class="docutils literal notranslate"><span class="pre">case</span> <span class="pre">MyClass(x,</span> <span class="pre">y)</span></code> is typically invalid without special

  3070. support in <code class="docutils literal notranslate"><span class="pre">MyClass</span></code>. To be able to use that kind of pattern, the class needs to

  3071. define a <em>__match_args__</em> attribute.</p>

  3072. <dl class="py data">

  3073. <dt class="sig sig-object py" id="object.__match_args__">

  3074. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__match_args__</span></span><a class="headerlink" href="#object.__match_args__" title="Link to this definition">¶</a></dt>

  3075. <dd><p>This class variable can be assigned a tuple of strings. When this class is

  3076. used in a class pattern with positional arguments, each positional argument will

  3077. be converted into a keyword argument, using the corresponding value in

  3078. <em>__match_args__</em> as the keyword. The absence of this attribute is equivalent to

  3079. setting it to <code class="docutils literal notranslate"><span class="pre">()</span></code>.</p>

  3080. </dd></dl>

  3081. 

  3082. <p>For example, if <code class="docutils literal notranslate"><span class="pre">MyClass.__match_args__</span></code> is <code class="docutils literal notranslate"><span class="pre">(&quot;left&quot;,</span> <span class="pre">&quot;center&quot;,</span> <span class="pre">&quot;right&quot;)</span></code> that means

  3083. that <code class="docutils literal notranslate"><span class="pre">case</span> <span class="pre">MyClass(x,</span> <span class="pre">y)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">case</span> <span class="pre">MyClass(left=x,</span> <span class="pre">center=y)</span></code>. Note

  3084. that the number of arguments in the pattern must be smaller than or equal to the number

  3085. of elements in <em>__match_args__</em>; if it is larger, the pattern match attempt will raise

  3086. a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>

  3087. <div class="versionadded">

  3088. <p><span class="versionmodified added">New in version 3.10.</span></p>

  3089. </div>

  3090. <div class="admonition seealso">

  3091. <p class="admonition-title">See also</p>

  3092. <dl class="simple">

  3093. <dt><span class="target" id="index-108"></span><a class="pep reference external" href="https://peps.python.org/pep-0634/"><strong>PEP 634</strong></a> - Structural Pattern Matching</dt><dd><p>The specification for the Python <code class="docutils literal notranslate"><span class="pre">match</span></code> statement.</p>

  3094. </dd>

  3095. </dl>

  3096. </div>

  3097. </section>

  3098. <section id="emulating-buffer-types">

  3099. <span id="python-buffer-protocol"></span><h3><span class="section-number">3.3.11. </span>Emulating buffer types<a class="headerlink" href="#emulating-buffer-types" title="Link to this heading">¶</a></h3>

  3100. <p>The <a class="reference internal" href="../c-api/buffer.html#bufferobjects"><span class="std std-ref">buffer protocol</span></a> provides a way for Python

  3101. objects to expose efficient access to a low-level memory array. This protocol

  3102. is implemented by builtin types such as <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> and <a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a>,

  3103. and third-party libraries may define additional buffer types.</p>

  3104. <p>While buffer types are usually implemented in C, it is also possible to

  3105. implement the protocol in Python.</p>

  3106. <dl class="py method">

  3107. <dt class="sig sig-object py" id="object.__buffer__">

  3108. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__buffer__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flags</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__buffer__" title="Link to this definition">¶</a></dt>

  3109. <dd><p>Called when a buffer is requested from <em>self</em> (for example, by the

  3110. <a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> constructor). The <em>flags</em> argument is an integer

  3111. representing the kind of buffer requested, affecting for example whether

  3112. the returned buffer is read-only or writable. <a class="reference internal" href="../library/inspect.html#inspect.BufferFlags" title="inspect.BufferFlags"><code class="xref py py-class docutils literal notranslate"><span class="pre">inspect.BufferFlags</span></code></a>

  3113. provides a convenient way to interpret the flags. The method must return

  3114. a <a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> object.</p>

  3115. </dd></dl>

  3116. 

  3117. <dl class="py method">

  3118. <dt class="sig sig-object py" id="object.__release_buffer__">

  3119. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__release_buffer__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffer</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__release_buffer__" title="Link to this definition">¶</a></dt>

  3120. <dd><p>Called when a buffer is no longer needed. The <em>buffer</em> argument is a

  3121. <a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> object that was previously returned by

  3122. <a class="reference internal" href="#object.__buffer__" title="object.__buffer__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__buffer__()</span></code></a>. The method must release any resources associated

  3123. with the buffer. This method should return <code class="docutils literal notranslate"><span class="pre">None</span></code>.

  3124. Buffer objects that do not need to perform any cleanup are not required

  3125. to implement this method.</p>

  3126. </dd></dl>

  3127. 

  3128. <div class="versionadded">

  3129. <p><span class="versionmodified added">New in version 3.12.</span></p>

  3130. </div>

  3131. <div class="admonition seealso">

  3132. <p class="admonition-title">See also</p>

  3133. <dl class="simple">

  3134. <dt><span class="target" id="index-109"></span><a class="pep reference external" href="https://peps.python.org/pep-0688/"><strong>PEP 688</strong></a> - Making the buffer protocol accessible in Python</dt><dd><p>Introduces the Python <code class="docutils literal notranslate"><span class="pre">__buffer__</span></code> and <code class="docutils literal notranslate"><span class="pre">__release_buffer__</span></code> methods.</p>

  3135. </dd>

  3136. <dt><a class="reference internal" href="../library/collections.abc.html#collections.abc.Buffer" title="collections.abc.Buffer"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.abc.Buffer</span></code></a></dt><dd><p>ABC for buffer types.</p>

  3137. </dd>

  3138. </dl>

  3139. </div>

  3140. </section>

  3141. <section id="special-method-lookup">

  3142. <span id="special-lookup"></span><h3><span class="section-number">3.3.12. </span>Special method lookup<a class="headerlink" href="#special-method-lookup" title="Link to this heading">¶</a></h3>

  3143. <p>For custom classes, implicit invocations of special methods are only guaranteed

  3144. to work correctly if defined on an object’s type, not in the object’s instance

  3145. dictionary.  That behaviour is the reason why the following code raises an

  3146. exception:</p>

  3147. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">C</span><span class="p">:</span>

  3148. <span class="gp">... </span>    <span class="k">pass</span>

  3149. <span class="gp">...</span>

  3150. <span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>

  3151. <span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="fm">__len__</span> <span class="o">=</span> <span class="k">lambda</span><span class="p">:</span> <span class="mi">5</span>

  3152. <span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">c</span><span class="p">)</span>

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

  3154.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  3155. <span class="gr">TypeError</span>: <span class="n">object of type &#39;C&#39; has no len()</span>

  3156. </pre></div>

  3157. </div>

  3158. <p>The rationale behind this behaviour lies with a number of special methods such

  3159. as <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> and <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a> that are implemented

  3160. by all objects,

  3161. including type objects. If the implicit lookup of these methods used the

  3162. conventional lookup process, they would fail when invoked on the type object

  3163. itself:</p>

  3164. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="mi">1</span> <span class="o">.</span><span class="fm">__hash__</span><span class="p">()</span> <span class="o">==</span> <span class="nb">hash</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  3165. <span class="go">True</span>

  3166. <span class="gp">&gt;&gt;&gt; </span><span class="nb">int</span><span class="o">.</span><span class="fm">__hash__</span><span class="p">()</span> <span class="o">==</span> <span class="nb">hash</span><span class="p">(</span><span class="nb">int</span><span class="p">)</span>

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

  3168.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  3169. <span class="gr">TypeError</span>: <span class="n">descriptor &#39;__hash__&#39; of &#39;int&#39; object needs an argument</span>

  3170. </pre></div>

  3171. </div>

  3172. <p>Incorrectly attempting to invoke an unbound method of a class in this way is

  3173. sometimes referred to as ‘metaclass confusion’, and is avoided by bypassing

  3174. the instance when looking up special methods:</p>

  3175. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="fm">__hash__</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">==</span> <span class="nb">hash</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  3176. <span class="go">True</span>

  3177. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="nb">int</span><span class="p">)</span><span class="o">.</span><span class="fm">__hash__</span><span class="p">(</span><span class="nb">int</span><span class="p">)</span> <span class="o">==</span> <span class="nb">hash</span><span class="p">(</span><span class="nb">int</span><span class="p">)</span>

  3178. <span class="go">True</span>

  3179. </pre></div>

  3180. </div>

  3181. <p>In addition to bypassing any instance attributes in the interest of

  3182. correctness, implicit special method lookup generally also bypasses the

  3183. <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a> method even of the object’s metaclass:</p>

  3184. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Meta</span><span class="p">(</span><span class="nb">type</span><span class="p">):</span>

  3185. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__getattribute__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>

  3186. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Metaclass getattribute invoked&quot;</span><span class="p">)</span>

  3187. <span class="gp">... </span>        <span class="k">return</span> <span class="nb">type</span><span class="o">.</span><span class="fm">__getattribute__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>

  3188. <span class="gp">...</span>

  3189. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="nb">object</span><span class="p">,</span> <span class="n">metaclass</span><span class="o">=</span><span class="n">Meta</span><span class="p">):</span>

  3190. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

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

  3192. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__getattribute__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>

  3193. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Class getattribute invoked&quot;</span><span class="p">)</span>

  3194. <span class="gp">... </span>        <span class="k">return</span> <span class="nb">object</span><span class="o">.</span><span class="fm">__getattribute__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>

  3195. <span class="gp">...</span>

  3196. <span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>

  3197. <span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="fm">__len__</span><span class="p">()</span>                 <span class="c1"># Explicit lookup via instance</span>

  3198. <span class="go">Class getattribute invoked</span>

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

  3200. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">c</span><span class="p">)</span><span class="o">.</span><span class="fm">__len__</span><span class="p">(</span><span class="n">c</span><span class="p">)</span>          <span class="c1"># Explicit lookup via type</span>

  3201. <span class="go">Metaclass getattribute invoked</span>

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

  3203. <span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">c</span><span class="p">)</span>                      <span class="c1"># Implicit lookup</span>

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

  3205. </pre></div>

  3206. </div>

  3207. <p>Bypassing the <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a> machinery in this fashion

  3208. provides significant scope for speed optimisations within the

  3209. interpreter, at the cost of some flexibility in the handling of

  3210. special methods (the special method <em>must</em> be set on the class

  3211. object itself in order to be consistently invoked by the interpreter).</p>

  3212. </section>

  3213. </section>

  3214. <section id="coroutines">

  3215. <span id="index-110"></span><h2><span class="section-number">3.4. </span>Coroutines<a class="headerlink" href="#coroutines" title="Link to this heading">¶</a></h2>

  3216. <section id="awaitable-objects">

  3217. <h3><span class="section-number">3.4.1. </span>Awaitable Objects<a class="headerlink" href="#awaitable-objects" title="Link to this heading">¶</a></h3>

  3218. <p>An <a class="reference internal" href="../glossary.html#term-awaitable"><span class="xref std std-term">awaitable</span></a> object generally implements an <a class="reference internal" href="#object.__await__" title="object.__await__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code></a> method.

  3219. <a class="reference internal" href="../glossary.html#term-coroutine"><span class="xref std std-term">Coroutine objects</span></a> returned from <a class="reference internal" href="compound_stmts.html#async-def"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code></a> functions

  3220. are awaitable.</p>

  3221. <div class="admonition note">

  3222. <p class="admonition-title">Note</p>

  3223. <p>The <a class="reference internal" href="../glossary.html#term-generator-iterator"><span class="xref std std-term">generator iterator</span></a> objects returned from generators

  3224. decorated with <a class="reference internal" href="../library/types.html#types.coroutine" title="types.coroutine"><code class="xref py py-func docutils literal notranslate"><span class="pre">types.coroutine()</span></code></a>

  3225. are also awaitable, but they do not implement <a class="reference internal" href="#object.__await__" title="object.__await__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code></a>.</p>

  3226. </div>

  3227. <dl class="py method">

  3228. <dt class="sig sig-object py" id="object.__await__">

  3229. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__await__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__await__" title="Link to this definition">¶</a></dt>

  3230. <dd><p>Must return an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a>.  Should be used to implement

  3231. <a class="reference internal" href="../glossary.html#term-awaitable"><span class="xref std std-term">awaitable</span></a> objects.  For instance, <a class="reference internal" href="../library/asyncio-future.html#asyncio.Future" title="asyncio.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.Future</span></code></a> implements

  3232. this method to be compatible with the <a class="reference internal" href="expressions.html#await"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">await</span></code></a> expression.</p>

  3233. <div class="admonition note">

  3234. <p class="admonition-title">Note</p>

  3235. <p>The language doesn’t place any restriction on the type or value of the

  3236. objects yielded by the iterator returned by <code class="docutils literal notranslate"><span class="pre">__await__</span></code>, as this is

  3237. specific to the implementation of the asynchronous execution framework

  3238. (e.g. <a class="reference internal" href="../library/asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a>) that will be managing the <a class="reference internal" href="../glossary.html#term-awaitable"><span class="xref std std-term">awaitable</span></a> object.</p>

  3239. </div>

  3240. </dd></dl>

  3241. 

  3242. <div class="versionadded">

  3243. <p><span class="versionmodified added">New in version 3.5.</span></p>

  3244. </div>

  3245. <div class="admonition seealso">

  3246. <p class="admonition-title">See also</p>

  3247. <p><span class="target" id="index-111"></span><a class="pep reference external" href="https://peps.python.org/pep-0492/"><strong>PEP 492</strong></a> for additional information about awaitable objects.</p>

  3248. </div>

  3249. </section>

  3250. <section id="coroutine-objects">

  3251. <span id="id16"></span><h3><span class="section-number">3.4.2. </span>Coroutine Objects<a class="headerlink" href="#coroutine-objects" title="Link to this heading">¶</a></h3>

  3252. <p><a class="reference internal" href="../glossary.html#term-coroutine"><span class="xref std std-term">Coroutine objects</span></a> are <a class="reference internal" href="../glossary.html#term-awaitable"><span class="xref std std-term">awaitable</span></a> objects.

  3253. A coroutine’s execution can be controlled by calling <a class="reference internal" href="#object.__await__" title="object.__await__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code></a> and

  3254. iterating over the result.  When the coroutine has finished executing and

  3255. returns, the iterator raises <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a>, and the exception’s

  3256. <a class="reference internal" href="../library/exceptions.html#StopIteration.value" title="StopIteration.value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">value</span></code></a> attribute holds the return value.  If the

  3257. coroutine raises an exception, it is propagated by the iterator.  Coroutines

  3258. should not directly raise unhandled <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> exceptions.</p>

  3259. <p>Coroutines also have the methods listed below, which are analogous to

  3260. those of generators (see <a class="reference internal" href="expressions.html#generator-methods"><span class="std std-ref">Generator-iterator methods</span></a>).  However, unlike

  3261. generators, coroutines do not directly support iteration.</p>

  3262. <div class="versionchanged">

  3263. <p><span class="versionmodified changed">Changed in version 3.5.2: </span>It is a <a class="reference internal" href="../library/exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> to await on a coroutine more than once.</p>

  3264. </div>

  3265. <dl class="py method">

  3266. <dt class="sig sig-object py" id="coroutine.send">

  3267. <span class="sig-prename descclassname"><span class="pre">coroutine.</span></span><span class="sig-name descname"><span class="pre">send</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#coroutine.send" title="Link to this definition">¶</a></dt>

  3268. <dd><p>Starts or resumes execution of the coroutine.  If <em>value</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>,

  3269. this is equivalent to advancing the iterator returned by

  3270. <a class="reference internal" href="#object.__await__" title="object.__await__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code></a>.  If <em>value</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, this method delegates

  3271. to the <a class="reference internal" href="expressions.html#generator.send" title="generator.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> method of the iterator that caused

  3272. the coroutine to suspend.  The result (return value,

  3273. <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a>, or other exception) is the same as when

  3274. iterating over the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code> return value, described above.</p>

  3275. </dd></dl>

  3276. 

  3277. <dl class="py method">

  3278. <dt class="sig sig-object py" id="coroutine.throw">

  3279. <span class="sig-prename descclassname"><span class="pre">coroutine.</span></span><span class="sig-name descname"><span class="pre">throw</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#coroutine.throw" title="Link to this definition">¶</a></dt>

  3280. <dt class="sig sig-object py">

  3281. <span class="sig-prename descclassname"><span class="pre">coroutine.</span></span><span class="sig-name descname"><span class="pre">throw</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">type</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">traceback</span></span></em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span></dt>

  3282. <dd><p>Raises the specified exception in the coroutine.  This method delegates

  3283. to the <a class="reference internal" href="expressions.html#generator.throw" title="generator.throw"><code class="xref py py-meth docutils literal notranslate"><span class="pre">throw()</span></code></a> method of the iterator that caused

  3284. the coroutine to suspend, if it has such a method.  Otherwise,

  3285. the exception is raised at the suspension point.  The result

  3286. (return value, <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a>, or other exception) is the same as

  3287. when iterating over the <a class="reference internal" href="#object.__await__" title="object.__await__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__await__()</span></code></a> return value, described

  3288. above.  If the exception is not caught in the coroutine, it propagates

  3289. back to the caller.</p>

  3290. <div class="versionchanged">

  3291. <p><span class="versionmodified changed">Changed in version 3.12: </span>The second signature (type[, value[, traceback]]) is deprecated and

  3292. may be removed in a future version of Python.</p>

  3293. </div>

  3294. </dd></dl>

  3295. 

  3296. <dl class="py method">

  3297. <dt class="sig sig-object py" id="coroutine.close">

  3298. <span class="sig-prename descclassname"><span class="pre">coroutine.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#coroutine.close" title="Link to this definition">¶</a></dt>

  3299. <dd><p>Causes the coroutine to clean itself up and exit.  If the coroutine

  3300. is suspended, this method first delegates to the <a class="reference internal" href="expressions.html#generator.close" title="generator.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a>

  3301. method of the iterator that caused the coroutine to suspend, if it

  3302. has such a method.  Then it raises <a class="reference internal" href="../library/exceptions.html#GeneratorExit" title="GeneratorExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">GeneratorExit</span></code></a> at the

  3303. suspension point, causing the coroutine to immediately clean itself up.

  3304. Finally, the coroutine is marked as having finished executing, even if

  3305. it was never started.</p>

  3306. <p>Coroutine objects are automatically closed using the above process when

  3307. they are about to be destroyed.</p>

  3308. </dd></dl>

  3309. 

  3310. </section>

  3311. <section id="asynchronous-iterators">

  3312. <span id="async-iterators"></span><h3><span class="section-number">3.4.3. </span>Asynchronous Iterators<a class="headerlink" href="#asynchronous-iterators" title="Link to this heading">¶</a></h3>

  3313. <p>An <em>asynchronous iterator</em> can call asynchronous code in

  3314. its <code class="docutils literal notranslate"><span class="pre">__anext__</span></code> method.</p>

  3315. <p>Asynchronous iterators can be used in an <a class="reference internal" href="compound_stmts.html#async-for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span></code></a> statement.</p>

  3316. <dl class="py method">

  3317. <dt class="sig sig-object py" id="object.__aiter__">

  3318. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__aiter__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__aiter__" title="Link to this definition">¶</a></dt>

  3319. <dd><p>Must return an <em>asynchronous iterator</em> object.</p>

  3320. </dd></dl>

  3321. 

  3322. <dl class="py method">

  3323. <dt class="sig sig-object py" id="object.__anext__">

  3324. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__anext__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__anext__" title="Link to this definition">¶</a></dt>

  3325. <dd><p>Must return an <em>awaitable</em> resulting in a next value of the iterator.  Should

  3326. raise a <a class="reference internal" href="../library/exceptions.html#StopAsyncIteration" title="StopAsyncIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopAsyncIteration</span></code></a> error when the iteration is over.</p>

  3327. </dd></dl>

  3328. 

  3329. <p>An example of an asynchronous iterable object:</p>

  3330. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Reader</span><span class="p">:</span>

  3331.     <span class="k">async</span> <span class="k">def</span> <span class="nf">readline</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

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

  3333. 

  3334.     <span class="k">def</span> <span class="fm">__aiter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

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

  3336. 

  3337.     <span class="k">async</span> <span class="k">def</span> <span class="fm">__anext__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3338.         <span class="n">val</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">readline</span><span class="p">()</span>

  3339.         <span class="k">if</span> <span class="n">val</span> <span class="o">==</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">:</span>

  3340.             <span class="k">raise</span> <span class="ne">StopAsyncIteration</span>

  3341.         <span class="k">return</span> <span class="n">val</span>

  3342. </pre></div>

  3343. </div>

  3344. <div class="versionadded">

  3345. <p><span class="versionmodified added">New in version 3.5.</span></p>

  3346. </div>

  3347. <div class="versionchanged">

  3348. <p><span class="versionmodified changed">Changed in version 3.7: </span>Prior to Python 3.7, <a class="reference internal" href="#object.__aiter__" title="object.__aiter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aiter__()</span></code></a> could return an <em>awaitable</em>

  3349. that would resolve to an

  3350. <a class="reference internal" href="../glossary.html#term-asynchronous-iterator"><span class="xref std std-term">asynchronous iterator</span></a>.</p>

  3351. <p>Starting with Python 3.7, <a class="reference internal" href="#object.__aiter__" title="object.__aiter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__aiter__()</span></code></a> must return an

  3352. asynchronous iterator object.  Returning anything else

  3353. will result in a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> error.</p>

  3354. </div>

  3355. </section>

  3356. <section id="asynchronous-context-managers">

  3357. <span id="async-context-managers"></span><h3><span class="section-number">3.4.4. </span>Asynchronous Context Managers<a class="headerlink" href="#asynchronous-context-managers" title="Link to this heading">¶</a></h3>

  3358. <p>An <em>asynchronous context manager</em> is a <em>context manager</em> that is able to

  3359. suspend execution in its <code class="docutils literal notranslate"><span class="pre">__aenter__</span></code> and <code class="docutils literal notranslate"><span class="pre">__aexit__</span></code> methods.</p>

  3360. <p>Asynchronous context managers can be used in an <a class="reference internal" href="compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a> statement.</p>

  3361. <dl class="py method">

  3362. <dt class="sig sig-object py" id="object.__aenter__">

  3363. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__aenter__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__aenter__" title="Link to this definition">¶</a></dt>

  3364. <dd><p>Semantically similar to <a class="reference internal" href="#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a>, the only

  3365. difference being that it must return an <em>awaitable</em>.</p>

  3366. </dd></dl>

  3367. 

  3368. <dl class="py method">

  3369. <dt class="sig sig-object py" id="object.__aexit__">

  3370. <span class="sig-prename descclassname"><span class="pre">object.</span></span><span class="sig-name descname"><span class="pre">__aexit__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_type</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_value</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">traceback</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#object.__aexit__" title="Link to this definition">¶</a></dt>

  3371. <dd><p>Semantically similar to <a class="reference internal" href="#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a>, the only

  3372. difference being that it must return an <em>awaitable</em>.</p>

  3373. </dd></dl>

  3374. 

  3375. <p>An example of an asynchronous context manager class:</p>

  3376. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">AsyncContextManager</span><span class="p">:</span>

  3377.     <span class="k">async</span> <span class="k">def</span> <span class="fm">__aenter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3378.         <span class="k">await</span> <span class="n">log</span><span class="p">(</span><span class="s1">&#39;entering context&#39;</span><span class="p">)</span>

  3379. 

  3380.     <span class="k">async</span> <span class="k">def</span> <span class="fm">__aexit__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc_type</span><span class="p">,</span> <span class="n">exc</span><span class="p">,</span> <span class="n">tb</span><span class="p">):</span>

  3381.         <span class="k">await</span> <span class="n">log</span><span class="p">(</span><span class="s1">&#39;exiting context&#39;</span><span class="p">)</span>

  3382. </pre></div>

  3383. </div>

  3384. <div class="versionadded">

  3385. <p><span class="versionmodified added">New in version 3.5.</span></p>

  3386. </div>

  3387. <p class="rubric">Footnotes</p>

  3388. <aside class="footnote-list brackets">

  3389. <aside class="footnote brackets" id="id17" role="doc-footnote">

  3390. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>

  3391. <p>It <em>is</em> possible in some cases to change an object’s type, under certain

  3392. controlled conditions. It generally isn’t a good idea though, since it can

  3393. lead to some very strange behaviour if it is handled incorrectly.</p>

  3394. </aside>

  3395. <aside class="footnote brackets" id="id18" role="doc-footnote">

  3396. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id10">2</a><span class="fn-bracket">]</span></span>

  3397. <p>The <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a>, <a class="reference internal" href="#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a>,

  3398. <a class="reference internal" href="#object.__reversed__" title="object.__reversed__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__reversed__()</span></code></a>, and <a class="reference internal" href="#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a> methods have

  3399. special handling for this; others

  3400. will still raise a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>, but may do so by relying on

  3401. the behavior that <code class="docutils literal notranslate"><span class="pre">None</span></code> is not callable.</p>

  3402. </aside>

  3403. <aside class="footnote brackets" id="id19" role="doc-footnote">

  3404. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id14">3</a><span class="fn-bracket">]</span></span>

  3405. <p>“Does not support” here means that the class has no such method, or

  3406. the method returns <a class="reference internal" href="../library/constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a>.  Do not set the method to

  3407. <code class="docutils literal notranslate"><span class="pre">None</span></code> if you want to force fallback to the right operand’s reflected

  3408. method—that will instead have the opposite effect of explicitly

  3409. <em>blocking</em> such fallback.</p>

  3410. </aside>

  3411. <aside class="footnote brackets" id="id20" role="doc-footnote">

  3412. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id15">4</a><span class="fn-bracket">]</span></span>

  3413. <p>For operands of the same type, it is assumed that if the non-reflected

  3414. method – such as <a class="reference internal" href="#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a> – fails then the overall

  3415. operation is not

  3416. supported, which is why the reflected method is not called.</p>

  3417. </aside>

  3418. </aside>

  3419. </section>

  3420. </section>

  3421. </section>

  3422. 

  3423. 

  3424.             <div class="clearer"></div>

  3425.           </div>

  3426.         </div>

  3427.       </div>

  3428.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  3429.         <div class="sphinxsidebarwrapper">

  3430.   <div>

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

  3432.     <ul>

  3433. <li><a class="reference internal" href="#">3. Data model</a><ul>

  3434. <li><a class="reference internal" href="#objects-values-and-types">3.1. Objects, values and types</a></li>

  3435. <li><a class="reference internal" href="#the-standard-type-hierarchy">3.2. The standard type hierarchy</a><ul>

  3436. <li><a class="reference internal" href="#none">3.2.1. None</a></li>

  3437. <li><a class="reference internal" href="#notimplemented">3.2.2. NotImplemented</a></li>

  3438. <li><a class="reference internal" href="#ellipsis">3.2.3. Ellipsis</a></li>

  3439. <li><a class="reference internal" href="#numbers-number">3.2.4. <code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Number</span></code></a><ul>

  3440. <li><a class="reference internal" href="#numbers-integral">3.2.4.1. <code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Integral</span></code></a></li>

  3441. <li><a class="reference internal" href="#numbers-real-float">3.2.4.2. <code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Real</span></code> (<code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code>)</a></li>

  3442. <li><a class="reference internal" href="#numbers-complex-complex">3.2.4.3. <code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Complex</span></code> (<code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code>)</a></li>

  3443. </ul>

  3444. </li>

  3445. <li><a class="reference internal" href="#sequences">3.2.5. Sequences</a><ul>

  3446. <li><a class="reference internal" href="#immutable-sequences">3.2.5.1. Immutable sequences</a></li>

  3447. <li><a class="reference internal" href="#mutable-sequences">3.2.5.2. Mutable sequences</a></li>

  3448. </ul>

  3449. </li>

  3450. <li><a class="reference internal" href="#set-types">3.2.6. Set types</a></li>

  3451. <li><a class="reference internal" href="#mappings">3.2.7. Mappings</a><ul>

  3452. <li><a class="reference internal" href="#dictionaries">3.2.7.1. Dictionaries</a></li>

  3453. </ul>

  3454. </li>

  3455. <li><a class="reference internal" href="#callable-types">3.2.8. Callable types</a><ul>

  3456. <li><a class="reference internal" href="#user-defined-functions">3.2.8.1. User-defined functions</a><ul>

  3457. <li><a class="reference internal" href="#special-read-only-attributes">3.2.8.1.1. Special read-only attributes</a></li>

  3458. <li><a class="reference internal" href="#special-writable-attributes">3.2.8.1.2. Special writable attributes</a></li>

  3459. </ul>

  3460. </li>

  3461. <li><a class="reference internal" href="#instance-methods">3.2.8.2. Instance methods</a></li>

  3462. <li><a class="reference internal" href="#generator-functions">3.2.8.3. Generator functions</a></li>

  3463. <li><a class="reference internal" href="#coroutine-functions">3.2.8.4. Coroutine functions</a></li>

  3464. <li><a class="reference internal" href="#asynchronous-generator-functions">3.2.8.5. Asynchronous generator functions</a></li>

  3465. <li><a class="reference internal" href="#built-in-functions">3.2.8.6. Built-in functions</a></li>

  3466. <li><a class="reference internal" href="#built-in-methods">3.2.8.7. Built-in methods</a></li>

  3467. <li><a class="reference internal" href="#classes">3.2.8.8. Classes</a></li>

  3468. <li><a class="reference internal" href="#class-instances">3.2.8.9. Class Instances</a></li>

  3469. </ul>

  3470. </li>

  3471. <li><a class="reference internal" href="#modules">3.2.9. Modules</a></li>

  3472. <li><a class="reference internal" href="#custom-classes">3.2.10. Custom classes</a></li>

  3473. <li><a class="reference internal" href="#id3">3.2.11. Class instances</a></li>

  3474. <li><a class="reference internal" href="#i-o-objects-also-known-as-file-objects">3.2.12. I/O objects (also known as file objects)</a></li>

  3475. <li><a class="reference internal" href="#internal-types">3.2.13. Internal types</a><ul>

  3476. <li><a class="reference internal" href="#code-objects">3.2.13.1. Code objects</a><ul>

  3477. <li><a class="reference internal" href="#index-58">3.2.13.1.1. Special read-only attributes</a></li>

  3478. <li><a class="reference internal" href="#methods-on-code-objects">3.2.13.1.2. Methods on code objects</a></li>

  3479. </ul>

  3480. </li>

  3481. <li><a class="reference internal" href="#frame-objects">3.2.13.2. Frame objects</a><ul>

  3482. <li><a class="reference internal" href="#index-64">3.2.13.2.1. Special read-only attributes</a></li>

  3483. <li><a class="reference internal" href="#index-65">3.2.13.2.2. Special writable attributes</a></li>

  3484. <li><a class="reference internal" href="#frame-object-methods">3.2.13.2.3. Frame object methods</a></li>

  3485. </ul>

  3486. </li>

  3487. <li><a class="reference internal" href="#traceback-objects">3.2.13.3. Traceback objects</a></li>

  3488. <li><a class="reference internal" href="#slice-objects">3.2.13.4. Slice objects</a></li>

  3489. <li><a class="reference internal" href="#static-method-objects">3.2.13.5. Static method objects</a></li>

  3490. <li><a class="reference internal" href="#class-method-objects">3.2.13.6. Class method objects</a></li>

  3491. </ul>

  3492. </li>

  3493. </ul>

  3494. </li>

  3495. <li><a class="reference internal" href="#special-method-names">3.3. Special method names</a><ul>

  3496. <li><a class="reference internal" href="#basic-customization">3.3.1. Basic customization</a></li>

  3497. <li><a class="reference internal" href="#customizing-attribute-access">3.3.2. Customizing attribute access</a><ul>

  3498. <li><a class="reference internal" href="#customizing-module-attribute-access">3.3.2.1. Customizing module attribute access</a></li>

  3499. <li><a class="reference internal" href="#implementing-descriptors">3.3.2.2. Implementing Descriptors</a></li>

  3500. <li><a class="reference internal" href="#invoking-descriptors">3.3.2.3. Invoking Descriptors</a></li>

  3501. <li><a class="reference internal" href="#slots">3.3.2.4. __slots__</a></li>

  3502. </ul>

  3503. </li>

  3504. <li><a class="reference internal" href="#customizing-class-creation">3.3.3. Customizing class creation</a><ul>

  3505. <li><a class="reference internal" href="#metaclasses">3.3.3.1. Metaclasses</a></li>

  3506. <li><a class="reference internal" href="#resolving-mro-entries">3.3.3.2. Resolving MRO entries</a></li>

  3507. <li><a class="reference internal" href="#determining-the-appropriate-metaclass">3.3.3.3. Determining the appropriate metaclass</a></li>

  3508. <li><a class="reference internal" href="#preparing-the-class-namespace">3.3.3.4. Preparing the class namespace</a></li>

  3509. <li><a class="reference internal" href="#executing-the-class-body">3.3.3.5. Executing the class body</a></li>

  3510. <li><a class="reference internal" href="#creating-the-class-object">3.3.3.6. Creating the class object</a></li>

  3511. <li><a class="reference internal" href="#uses-for-metaclasses">3.3.3.7. Uses for metaclasses</a></li>

  3512. </ul>

  3513. </li>

  3514. <li><a class="reference internal" href="#customizing-instance-and-subclass-checks">3.3.4. Customizing instance and subclass checks</a></li>

  3515. <li><a class="reference internal" href="#emulating-generic-types">3.3.5. Emulating generic types</a><ul>

  3516. <li><a class="reference internal" href="#the-purpose-of-class-getitem">3.3.5.1. The purpose of <em>__class_getitem__</em></a></li>

  3517. <li><a class="reference internal" href="#class-getitem-versus-getitem">3.3.5.2. <em>__class_getitem__</em> versus <em>__getitem__</em></a></li>

  3518. </ul>

  3519. </li>

  3520. <li><a class="reference internal" href="#emulating-callable-objects">3.3.6. Emulating callable objects</a></li>

  3521. <li><a class="reference internal" href="#emulating-container-types">3.3.7. Emulating container types</a></li>

  3522. <li><a class="reference internal" href="#emulating-numeric-types">3.3.8. Emulating numeric types</a></li>

  3523. <li><a class="reference internal" href="#with-statement-context-managers">3.3.9. With Statement Context Managers</a></li>

  3524. <li><a class="reference internal" href="#customizing-positional-arguments-in-class-pattern-matching">3.3.10. Customizing positional arguments in class pattern matching</a></li>

  3525. <li><a class="reference internal" href="#emulating-buffer-types">3.3.11. Emulating buffer types</a></li>

  3526. <li><a class="reference internal" href="#special-method-lookup">3.3.12. Special method lookup</a></li>

  3527. </ul>

  3528. </li>

  3529. <li><a class="reference internal" href="#coroutines">3.4. Coroutines</a><ul>

  3530. <li><a class="reference internal" href="#awaitable-objects">3.4.1. Awaitable Objects</a></li>

  3531. <li><a class="reference internal" href="#coroutine-objects">3.4.2. Coroutine Objects</a></li>

  3532. <li><a class="reference internal" href="#asynchronous-iterators">3.4.3. Asynchronous Iterators</a></li>

  3533. <li><a class="reference internal" href="#asynchronous-context-managers">3.4.4. Asynchronous Context Managers</a></li>

  3534. </ul>

  3535. </li>

  3536. </ul>

  3537. </li>

  3538. </ul>

  3539. 

  3540.   </div>

  3541.   <div>

  3542.     <h4>Previous topic</h4>

  3543.     <p class="topless"><a href="lexical_analysis.html"

  3544.                           title="previous chapter"><span class="section-number">2. </span>Lexical analysis</a></p>

  3545.   </div>

  3546.   <div>

  3547.     <h4>Next topic</h4>

  3548.     <p class="topless"><a href="executionmodel.html"

  3549.                           title="next chapter"><span class="section-number">4. </span>Execution model</a></p>

  3550.   </div>

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

  3552.     <h3>This Page</h3>

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

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

  3555.       <li>

  3556.         <a href="https://github.com/python/cpython/blob/main/Doc/reference/datamodel.rst"

  3557.             rel="nofollow">Show Source

  3558.         </a>

  3559.       </li>

  3560.     </ul>

  3561.   </div>

  3562.         </div>

  3563. <div id="sidebarbutton" title="Collapse sidebar">

  3564. <span>«</span>

  3565. </div>

  3566. 

  3567.       </div>

  3568.       <div class="clearer"></div>

  3569.     </div>  

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

  3571.       <h3>Navigation</h3>

  3572.       <ul>

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

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

  3575.              >index</a></li>

  3576.         <li class="right" >

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

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

  3579.         <li class="right" >

  3580.           <a href="executionmodel.html" title="4. Execution model"

  3581.              >next</a> |</li>

  3582.         <li class="right" >

  3583.           <a href="lexical_analysis.html" title="2. Lexical analysis"

  3584.              >previous</a> |</li>

  3585. 

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

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

  3588.           <li class="switchers">

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

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

  3591.           </li>

  3592.           <li>

  3593.               

  3594.           </li>

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

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

  3597.     </li>

  3598. 

  3599.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Language Reference</a> &#187;</li>

  3600.         <li class="nav-item nav-item-this"><a href=""><span class="section-number">3. </span>Data model</a></li>

  3601.                 <li class="right">

  3602.                     

  3603. 

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

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

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

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

  3608.         </form>

  3609.     </div>

  3610.                      |

  3611.                 </li>

  3612.             <li class="right">

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

  3614.     Theme

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

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

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

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

  3619.     </select>

  3620. </label> |</li>

  3621.             

  3622.       </ul>

  3623.     </div>  

  3624.     <div class="footer">

  3625.     &copy; 

  3626.       <a href="../copyright.html">

  3627.     

  3628.     Copyright

  3629.     

  3630.       </a>

  3631.      2001-2024, Python Software Foundation.

  3632.     <br />

  3633.     This page is licensed under the Python Software Foundation License Version 2.

  3634.     <br />

  3635.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  3636.     <br />

  3637.     

  3638.       See <a href="/license.html">History and License</a> for more information.<br />

  3639.     

  3640.     

  3641.     <br />

  3642. 

  3643.     The Python Software Foundation is a non-profit corporation.

  3644. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  3645. <br />

  3646.     <br />

  3647.       Last updated on Apr 09, 2024 (13:47 UTC).

  3648.     

  3649.       <a href="/bugs.html">Found a bug</a>?

  3650.     

  3651.     <br />

  3652. 

  3653.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  3654.     </div>

  3655. 

  3656.   </body>

  3657. </html>
上海开阖软件有限公司 沪ICP备12045867号-1