parthtamu/rag-code-assistant
0
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="Built-in Types" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/stdtypes.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="The following sections describe the standard types that are built into the interpreter. The principal built-in types are numerics, sequences, mappings, classes, instances and exceptions. Some colle..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_stdtypes_88628c8c.png" />15<meta property="og:image:alt" content="The following sections describe the standard types that are built into the interpreter. The principal built-in types are numerics, sequences, mappings, classes, instances and exceptions. Some colle..." />16<meta name="description" content="The following sections describe the standard types that are built into the interpreter. The principal built-in types are numerics, sequences, mappings, classes, instances and exceptions. Some colle..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>Built-in Types — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="Built-in Exceptions" href="exceptions.html" />43 <link rel="prev" title="Built-in Constants" href="constants.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/stdtypes.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#">Built-in Types</a><ul>108<li><a class="reference internal" href="#truth-value-testing">Truth Value Testing</a></li>109<li><a class="reference internal" href="#boolean-operations-and-or-not">Boolean Operations — <code class="xref std std-keyword docutils literal notranslate"><span class="pre">and</span></code>, <code class="xref std std-keyword docutils literal notranslate"><span class="pre">or</span></code>, <code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span></code></a></li>110<li><a class="reference internal" href="#comparisons">Comparisons</a></li>111<li><a class="reference internal" href="#numeric-types-int-float-complex">Numeric Types — <code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a><ul>112<li><a class="reference internal" href="#bitwise-operations-on-integer-types">Bitwise Operations on Integer Types</a></li>113<li><a class="reference internal" href="#additional-methods-on-integer-types">Additional Methods on Integer Types</a></li>114<li><a class="reference internal" href="#additional-methods-on-float">Additional Methods on Float</a></li>115<li><a class="reference internal" href="#additional-methods-on-complex">Additional Methods on Complex</a></li>116<li><a class="reference internal" href="#hashing-of-numeric-types">Hashing of numeric types</a></li>117</ul>118</li>119<li><a class="reference internal" href="#boolean-type-bool">Boolean Type - <code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a></li>120<li><a class="reference internal" href="#iterator-types">Iterator Types</a><ul>121<li><a class="reference internal" href="#generator-types">Generator Types</a></li>122</ul>123</li>124<li><a class="reference internal" href="#sequence-types-list-tuple-range">Sequence Types — <code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a><ul>125<li><a class="reference internal" href="#common-sequence-operations">Common Sequence Operations</a></li>126<li><a class="reference internal" href="#immutable-sequence-types">Immutable Sequence Types</a></li>127<li><a class="reference internal" href="#mutable-sequence-types">Mutable Sequence Types</a></li>128<li><a class="reference internal" href="#lists">Lists</a></li>129<li><a class="reference internal" href="#tuples">Tuples</a></li>130<li><a class="reference internal" href="#ranges">Ranges</a></li>131</ul>132</li>133<li><a class="reference internal" href="#text-and-binary-sequence-type-methods-summary">Text and Binary Sequence Type Methods Summary</a></li>134<li><a class="reference internal" href="#text-sequence-type-str">Text Sequence Type — <code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a><ul>135<li><a class="reference internal" href="#string-methods">String Methods</a></li>136<li><a class="reference internal" href="#formatted-string-literals-f-strings">Formatted String Literals (f-strings)</a><ul>137<li><a class="reference internal" href="#debug-specifier">Debug specifier</a></li>138<li><a class="reference internal" href="#conversion-specifier">Conversion specifier</a></li>139<li><a class="reference internal" href="#format-specifier">Format specifier</a></li>140</ul>141</li>142<li><a class="reference internal" href="#template-string-literals-t-strings">Template String Literals (t-strings)</a></li>143<li><a class="reference internal" href="#printf-style-string-formatting"><code class="docutils literal notranslate"><span class="pre">printf</span></code>-style String Formatting</a></li>144</ul>145</li>146<li><a class="reference internal" href="#binary-sequence-types-bytes-bytearray-memoryview">Binary Sequence Types — <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a><ul>147<li><a class="reference internal" href="#bytes-objects">Bytes Objects</a></li>148<li><a class="reference internal" href="#bytearray-objects">Bytearray Objects</a></li>149<li><a class="reference internal" href="#bytes-and-bytearray-operations">Bytes and Bytearray Operations</a></li>150<li><a class="reference internal" href="#printf-style-bytes-formatting"><code class="docutils literal notranslate"><span class="pre">printf</span></code>-style Bytes Formatting</a></li>151<li><a class="reference internal" href="#memory-views">Memory Views</a></li>152</ul>153</li>154<li><a class="reference internal" href="#set-types-set-frozenset">Set Types — <code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a></li>155<li><a class="reference internal" href="#mapping-types-dict-frozendict">Mapping types — <code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a><ul>156<li><a class="reference internal" href="#dictionary-view-objects">Dictionary view objects</a></li>157<li><a class="reference internal" href="#frozen-dictionaries">Frozen dictionaries</a></li>158</ul>159</li>160<li><a class="reference internal" href="#context-manager-types">Context Manager Types</a></li>161<li><a class="reference internal" href="#type-annotation-types-generic-alias-union">Type Annotation Types — <span class="xref std std-ref">Generic Alias</span>, <span class="xref std std-ref">Union</span></a><ul>162<li><a class="reference internal" href="#generic-alias-type">Generic Alias Type</a><ul>163<li><a class="reference internal" href="#standard-generic-classes">Standard Generic Classes</a></li>164<li><a class="reference internal" href="#special-attributes-of-genericalias-objects">Special Attributes of <code class="docutils literal notranslate"><span class="pre">GenericAlias</span></code> objects</a></li>165</ul>166</li>167<li><a class="reference internal" href="#union-type">Union Type</a></li>168</ul>169</li>170<li><a class="reference internal" href="#other-built-in-types">Other Built-in Types</a><ul>171<li><a class="reference internal" href="#modules">Modules</a></li>172<li><a class="reference internal" href="#classes-and-class-instances">Classes and Class Instances</a></li>173<li><a class="reference internal" href="#functions">Functions</a></li>174<li><a class="reference internal" href="#methods">Methods</a></li>175<li><a class="reference internal" href="#code-objects">Code Objects</a></li>176<li><a class="reference internal" href="#type-objects">Type Objects</a></li>177<li><a class="reference internal" href="#the-null-object">The Null Object</a></li>178<li><a class="reference internal" href="#the-ellipsis-object">The Ellipsis Object</a></li>179<li><a class="reference internal" href="#the-notimplemented-object">The NotImplemented Object</a></li>180<li><a class="reference internal" href="#internal-objects">Internal Objects</a></li>181</ul>182</li>183<li><a class="reference internal" href="#special-attributes">Special Attributes</a></li>184<li><a class="reference internal" href="#integer-string-conversion-length-limitation">Integer string conversion length limitation</a><ul>185<li><a class="reference internal" href="#affected-apis">Affected APIs</a></li>186<li><a class="reference internal" href="#configuring-the-limit">Configuring the limit</a></li>187<li><a class="reference internal" href="#recommended-configuration">Recommended configuration</a></li>188</ul>189</li>190</ul>191</li>192</ul>193 194 </div>195 <div>196 <h4>Previous topic</h4>197 <p class="topless"><a href="constants.html"198 title="previous chapter">Built-in Constants</a></p>199 </div>200 <div>201 <h4>Next topic</h4>202 <p class="topless"><a href="exceptions.html"203 title="next chapter">Built-in Exceptions</a></p>204 </div>205 <script>206 document.addEventListener('DOMContentLoaded', () => {207 const title = document.querySelector('meta[property="og:title"]').content;208 const elements = document.querySelectorAll('.improvepage');209 const pageurl = window.location.href.split('?')[0];210 elements.forEach(element => {211 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));212 url.searchParams.set('pagetitle', title);213 url.searchParams.set('pageurl', pageurl);214 url.searchParams.set('pagesource', "library/stdtypes.rst");215 element.href = url.toString();216 });217 });218 </script>219 <div role="note" aria-label="source link">220 <h3>This page</h3>221 <ul class="this-page-menu">222 <li><a href="../bugs.html">Report a bug</a></li>223 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>224 <li>225 <a href="https://github.com/python/cpython/blob/main/Doc/library/stdtypes.rst?plain=1"226 rel="nofollow">Show source227 </a>228 </li>229 230 </ul>231 </div>232 </nav>233 </div>234</div>235 236 237 <div class="related" role="navigation" aria-label="Related">238 <h3>Navigation</h3>239 <ul>240 <li class="right" style="margin-right: 10px">241 <a href="../genindex.html" title="General Index"242 accesskey="I">index</a></li>243 <li class="right" >244 <a href="../py-modindex.html" title="Python Module Index"245 >modules</a> |</li>246 <li class="right" >247 <a href="exceptions.html" title="Built-in Exceptions"248 accesskey="N">next</a> |</li>249 <li class="right" >250 <a href="constants.html" title="Built-in Constants"251 accesskey="P">previous</a> |</li>252 253 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>254 <li><a href="https://www.python.org/">Python</a> »</li>255 <li class="switchers">256 <div class="language_switcher_placeholder"></div>257 <div class="version_switcher_placeholder"></div>258 </li>259 <li>260 261 </li>262 <li id="cpython-language-and-version">263 <a href="../index.html">3.15.0a6 Documentation</a> »264 </li>265 266 <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Python Standard Library</a> »</li>267 <li class="nav-item nav-item-this"><a href="">Built-in Types</a></li>268 <li class="right">269 270 271 <div class="inline-search" role="search">272 <form class="inline-search" action="../search.html" method="get">273 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">274 <input type="submit" value="Go">275 </form>276 </div>277 |278 </li>279 <li class="right">280<label class="theme-selector-label">281 Theme282 <select class="theme-selector" oninput="activateTheme(this.value)">283 <option value="auto" selected>Auto</option>284 <option value="light">Light</option>285 <option value="dark">Dark</option>286 </select>287</label> |</li>288 289 </ul>290 </div> 291 292 <div class="document">293 <div class="documentwrapper">294 <div class="bodywrapper">295 <div class="body" role="main">296 297 <section id="built-in-types">298<span id="bltin-types"></span><h1>Built-in Types<a class="headerlink" href="#built-in-types" title="Link to this heading">¶</a></h1>299<p>The following sections describe the standard types that are built into the300interpreter.</p>301<p id="index-0">The principal built-in types are numerics, sequences, mappings, classes,302instances and exceptions.</p>303<p>Some collection classes are mutable. The methods that add, subtract, or304rearrange their members in place, and don’t return a specific item, never return305the collection instance itself but <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>306<p>Some operations are supported by several object types; in particular,307practically all objects can be compared for equality, tested for truth308value, and converted to a string (with the <a class="reference internal" href="functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a> function or the309slightly different <a class="reference internal" href="#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> function). The latter function is implicitly310used when an object is written by the <a class="reference internal" href="functions.html#print" title="print"><code class="xref py py-func docutils literal notranslate"><span class="pre">print()</span></code></a> function.</p>311<section id="truth-value-testing">312<span id="truth"></span><h2>Truth Value Testing<a class="headerlink" href="#truth-value-testing" title="Link to this heading">¶</a></h2>313<p id="index-1">Any object can be tested for truth value, for use in an <a class="reference internal" href="../reference/compound_stmts.html#if"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">if</span></code></a> or314<a class="reference internal" href="../reference/compound_stmts.html#while"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">while</span></code></a> condition or as operand of the Boolean operations below.</p>315<p id="index-2">By default, an object is considered true unless its class defines either a316<a class="reference internal" href="../reference/datamodel.html#object.__bool__" title="object.__bool__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__bool__()</span></code></a> method that returns <code class="docutils literal notranslate"><span class="pre">False</span></code> or a317<a class="reference internal" href="../reference/datamodel.html#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code></a> method that318returns zero, when called with the object. <a class="footnote-reference brackets" href="#id12" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> If one of the methods raises an319exception when called, the exception is propagated and the object does320not have a truth value (for example, <a class="reference internal" href="constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a>).321Here are most of the built-in objects considered false:</p>322<ul class="simple" id="index-3">323<li><p>constants defined to be false: <code class="docutils literal notranslate"><span class="pre">None</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code></p></li>324<li><p>zero of any numeric type: <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">0.0</span></code>, <code class="docutils literal notranslate"><span class="pre">0j</span></code>, <code class="docutils literal notranslate"><span class="pre">Decimal(0)</span></code>,325<code class="docutils literal notranslate"><span class="pre">Fraction(0,</span> <span class="pre">1)</span></code></p></li>326<li><p>empty sequences and collections: <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">set()</span></code>,327<code class="docutils literal notranslate"><span class="pre">range(0)</span></code></p></li>328</ul>329<p id="index-4">Operations and built-in functions that have a Boolean result always return <code class="docutils literal notranslate"><span class="pre">0</span></code>330or <code class="docutils literal notranslate"><span class="pre">False</span></code> for false and <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">True</span></code> for true, unless otherwise stated.331(Important exception: the Boolean operations <code class="docutils literal notranslate"><span class="pre">or</span></code> and <code class="docutils literal notranslate"><span class="pre">and</span></code> always return332one of their operands.)</p>333</section>334<section id="boolean-operations-and-or-not">335<span id="boolean"></span><h2>Boolean Operations — <code class="xref std std-keyword docutils literal notranslate"><span class="pre">and</span></code>, <code class="xref std std-keyword docutils literal notranslate"><span class="pre">or</span></code>, <code class="xref std std-keyword docutils literal notranslate"><span class="pre">not</span></code><a class="headerlink" href="#boolean-operations-and-or-not" title="Link to this heading">¶</a></h2>336<p id="index-5">These are the Boolean operations, ordered by ascending priority:</p>337<table class="docutils align-default">338<thead>339<tr class="row-odd"><th class="head"><p>Operation</p></th>340<th class="head"><p>Result</p></th>341<th class="head"><p>Notes</p></th>342</tr>343</thead>344<tbody>345<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">or</span> <span class="pre">y</span></code></p></td>346<td><p>if <em>x</em> is true, then <em>x</em>, else347<em>y</em></p></td>348<td><p>(1)</p></td>349</tr>350<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">and</span> <span class="pre">y</span></code></p></td>351<td><p>if <em>x</em> is false, then <em>x</em>, else352<em>y</em></p></td>353<td><p>(2)</p></td>354</tr>355<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">x</span></code></p></td>356<td><p>if <em>x</em> is false, then <code class="docutils literal notranslate"><span class="pre">True</span></code>,357else <code class="docutils literal notranslate"><span class="pre">False</span></code></p></td>358<td><p>(3)</p></td>359</tr>360</tbody>361</table>362<p id="index-6">Notes:</p>363<ol class="arabic simple">364<li><p>This is a short-circuit operator, so it only evaluates the second365argument if the first one is false.</p></li>366<li><p>This is a short-circuit operator, so it only evaluates the second367argument if the first one is true.</p></li>368<li><p><code class="docutils literal notranslate"><span class="pre">not</span></code> has a lower priority than non-Boolean operators, so <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></code> is369interpreted as <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">(a</span> <span class="pre">==</span> <span class="pre">b)</span></code>, and <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">not</span> <span class="pre">b</span></code> is a syntax error.</p></li>370</ol>371</section>372<section id="comparisons">373<span id="stdcomparisons"></span><h2>Comparisons<a class="headerlink" href="#comparisons" title="Link to this heading">¶</a></h2>374<p id="index-7">There are eight comparison operations in Python. They all have the same375priority (which is higher than that of the Boolean operations). Comparisons can376be chained arbitrarily; for example, <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span> <span class="pre">and</span>377<span class="pre">y</span> <span class="pre"><=</span> <span class="pre">z</span></code>, except that <em>y</em> is evaluated only once (but in both cases <em>z</em> is not378evaluated at all when <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><</span> <span class="pre">y</span></code> is found to be false).</p>379<p>This table summarizes the comparison operations:</p>380<table class="docutils align-default">381<thead>382<tr class="row-odd"><th class="head"><p>Operation</p></th>383<th class="head"><p>Meaning</p></th>384</tr>385</thead>386<tbody>387<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre"><</span></code></p></td>388<td><p>strictly less than</p></td>389</tr>390<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre"><=</span></code></p></td>391<td><p>less than or equal</p></td>392</tr>393<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">></span></code></p></td>394<td><p>strictly greater than</p></td>395</tr>396<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">>=</span></code></p></td>397<td><p>greater than or equal</p></td>398</tr>399<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">==</span></code></p></td>400<td><p>equal</p></td>401</tr>402<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">!=</span></code></p></td>403<td><p>not equal</p></td>404</tr>405<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">is</span></code></p></td>406<td><p>object identity</p></td>407</tr>408<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">is</span> <span class="pre">not</span></code></p></td>409<td><p>negated object identity</p></td>410</tr>411</tbody>412</table>413<p id="index-8">Unless stated otherwise, objects of different types never compare equal.414The <code class="docutils literal notranslate"><span class="pre">==</span></code> operator is always defined but for some object types (for example,415class objects) is equivalent to <a class="reference internal" href="../reference/expressions.html#is"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span></code></a>. The <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> and <code class="docutils literal notranslate"><span class="pre">>=</span></code>416operators are only defined where they make sense; for example, they raise a417<a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> exception when one of the arguments is a complex number.</p>418<p id="index-9">Non-identical instances of a class normally compare as non-equal unless the419class defines the <a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> method.</p>420<p>Instances of a class cannot be ordered with respect to other instances of the421same class, or other types of object, unless the class defines enough of the422methods <a class="reference internal" href="../reference/datamodel.html#object.__lt__" title="object.__lt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__le__" title="object.__le__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__le__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__gt__" title="object.__gt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__gt__()</span></code></a>, and423<a class="reference internal" href="../reference/datamodel.html#object.__ge__" title="object.__ge__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__ge__()</span></code></a> (in general, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code> and424<a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> are sufficient, if you want the conventional meanings of the425comparison operators).</p>426<p>The behavior of the <a class="reference internal" href="../reference/expressions.html#is"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span></code></a> and <a class="reference internal" href="../reference/expressions.html#is-not"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">is</span> <span class="pre">not</span></code></a> operators cannot be427customized; also they can be applied to any two objects and never raise an428exception.</p>429<p id="index-10">Two more operations with the same syntactic priority, <a class="reference internal" href="../reference/expressions.html#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a> and430<a class="reference internal" href="../reference/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 supported by types that are <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iterable</span></a> or431implement the <a class="reference internal" href="../reference/datamodel.html#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a> method.</p>432</section>433<section id="numeric-types-int-float-complex">434<span id="typesnumeric"></span><h2>Numeric Types — <a class="reference internal" href="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="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, <a class="reference internal" href="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="#numeric-types-int-float-complex" title="Link to this heading">¶</a></h2>435<p id="index-11">There are three distinct numeric types: <em class="dfn">integers</em>, <em class="dfn">floating-point436numbers</em>, and <em class="dfn">complex numbers</em>. In addition, Booleans are a437subtype of integers. Integers have unlimited precision. Floating-point438numbers are usually implemented using <span class="c-expr sig sig-inline c"><span class="kt">double</span></span> in C; information439about the precision and internal representation of floating-point440numbers for the machine on which your program is running is available441in <a class="reference internal" href="sys.html#sys.float_info" title="sys.float_info"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.float_info</span></code></a>. Complex numbers have a real and imaginary442part, which are each a floating-point number. To extract these parts443from a complex number <em>z</em>, use <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>. (The standard444library includes the additional numeric types <a class="reference internal" href="fractions.html#fractions.Fraction" title="fractions.Fraction"><code class="xref py py-mod docutils literal notranslate"><span class="pre">fractions.Fraction</span></code></a>, for445rationals, and <a class="reference internal" href="decimal.html#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal.Decimal</span></code></a>, for floating-point numbers with446user-definable precision.)</p>447<p id="index-12">Numbers are created by numeric literals or as the result of built-in functions448and operators. Unadorned integer literals (including hex, octal and binary449numbers) yield integers. Numeric literals containing a decimal point or an450exponent sign yield floating-point numbers. Appending <code class="docutils literal notranslate"><span class="pre">'j'</span></code> or <code class="docutils literal notranslate"><span class="pre">'J'</span></code> to a451numeric literal yields an imaginary number (a complex number with a zero real452part) which you can add to an integer or float to get a complex number with real453and imaginary parts.</p>454<p>The constructors <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a>, <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-func docutils literal notranslate"><span class="pre">float()</span></code></a>, and455<a class="reference internal" href="functions.html#complex" title="complex"><code class="xref py py-func docutils literal notranslate"><span class="pre">complex()</span></code></a> can be used to produce numbers of a specific type.</p>456<p id="stdtypes-mixed-arithmetic"><span id="index-13"></span>Python fully supports mixed arithmetic: when a binary arithmetic operator has457operands of different built-in numeric types, the operand with the “narrower”458type is widened to that of the other:</p>459<ul class="simple">460<li><p>If both arguments are complex numbers, no conversion is performed;</p></li>461<li><p>if either argument is a complex or a floating-point number, the other is462converted to a floating-point number;</p></li>463<li><p>otherwise, both must be integers and no conversion is necessary.</p></li>464</ul>465<p>Arithmetic with complex and real operands is defined by the usual mathematical466formula, for example:</p>467<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">+</span> <span class="nb">complex</span><span class="p">(</span><span class="n">u</span><span class="p">,</span> <span class="n">v</span><span class="p">)</span> <span class="o">=</span> <span class="nb">complex</span><span class="p">(</span><span class="n">x</span> <span class="o">+</span> <span class="n">u</span><span class="p">,</span> <span class="n">v</span><span class="p">)</span>468<span class="n">x</span> <span class="o">*</span> <span class="nb">complex</span><span class="p">(</span><span class="n">u</span><span class="p">,</span> <span class="n">v</span><span class="p">)</span> <span class="o">=</span> <span class="nb">complex</span><span class="p">(</span><span class="n">x</span> <span class="o">*</span> <span class="n">u</span><span class="p">,</span> <span class="n">x</span> <span class="o">*</span> <span class="n">v</span><span class="p">)</span>469</pre></div>470</div>471<p>A comparison between numbers of different types behaves as though the exact472values of those numbers were being compared. <a class="footnote-reference brackets" href="#id13" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p>473<p>All numeric types (except complex) support the following operations (for priorities of474the operations, see <a class="reference internal" href="../reference/expressions.html#operator-summary"><span class="std std-ref">Operator precedence</span></a>):</p>475<table class="docutils align-default">476<thead>477<tr class="row-odd"><th class="head"><p>Operation</p></th>478<th class="head"><p>Result</p></th>479<th class="head"><p>Notes</p></th>480<th class="head"><p>Full documentation</p></th>481</tr>482</thead>483<tbody>484<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">+</span> <span class="pre">y</span></code></p></td>485<td><p>sum of <em>x</em> and <em>y</em></p></td>486<td></td>487<td></td>488</tr>489<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span></code></p></td>490<td><p>difference of <em>x</em> and <em>y</em></p></td>491<td></td>492<td></td>493</tr>494<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">*</span> <span class="pre">y</span></code></p></td>495<td><p>product of <em>x</em> and <em>y</em></p></td>496<td></td>497<td></td>498</tr>499<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">/</span> <span class="pre">y</span></code></p></td>500<td><p>quotient of <em>x</em> and <em>y</em></p></td>501<td></td>502<td></td>503</tr>504<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">//</span> <span class="pre">y</span></code></p></td>505<td><p>floored quotient of <em>x</em> and506<em>y</em></p></td>507<td><p>(1)(2)</p></td>508<td></td>509</tr>510<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">%</span> <span class="pre">y</span></code></p></td>511<td><p>remainder of <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">/</span> <span class="pre">y</span></code></p></td>512<td><p>(2)</p></td>513<td></td>514</tr>515<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-x</span></code></p></td>516<td><p><em>x</em> negated</p></td>517<td></td>518<td></td>519</tr>520<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">+x</span></code></p></td>521<td><p><em>x</em> unchanged</p></td>522<td></td>523<td></td>524</tr>525<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">abs(x)</span></code></p></td>526<td><p>absolute value or magnitude of527<em>x</em></p></td>528<td></td>529<td><p><a class="reference internal" href="functions.html#abs" title="abs"><code class="xref py py-func docutils literal notranslate"><span class="pre">abs()</span></code></a></p></td>530</tr>531<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">int(x)</span></code></p></td>532<td><p><em>x</em> converted to integer</p></td>533<td><p>(3)(6)</p></td>534<td><p><a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a></p></td>535</tr>536<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">float(x)</span></code></p></td>537<td><p><em>x</em> converted to floating point</p></td>538<td><p>(4)(6)</p></td>539<td><p><a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-func docutils literal notranslate"><span class="pre">float()</span></code></a></p></td>540</tr>541<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">complex(re,</span> <span class="pre">im)</span></code></p></td>542<td><p>a complex number with real part543<em>re</em>, imaginary part <em>im</em>.544<em>im</em> defaults to zero.</p></td>545<td><p>(6)</p></td>546<td><p><a class="reference internal" href="functions.html#complex" title="complex"><code class="xref py py-func docutils literal notranslate"><span class="pre">complex()</span></code></a></p></td>547</tr>548<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">c.conjugate()</span></code></p></td>549<td><p>conjugate of the complex number550<em>c</em></p></td>551<td></td>552<td></td>553</tr>554<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">divmod(x,</span> <span class="pre">y)</span></code></p></td>555<td><p>the pair <code class="docutils literal notranslate"><span class="pre">(x</span> <span class="pre">//</span> <span class="pre">y,</span> <span class="pre">x</span> <span class="pre">%</span> <span class="pre">y)</span></code></p></td>556<td><p>(2)</p></td>557<td><p><a class="reference internal" href="functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">divmod()</span></code></a></p></td>558</tr>559<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">pow(x,</span> <span class="pre">y)</span></code></p></td>560<td><p><em>x</em> to the power <em>y</em></p></td>561<td><p>(5)</p></td>562<td><p><a class="reference internal" href="functions.html#pow" title="pow"><code class="xref py py-func docutils literal notranslate"><span class="pre">pow()</span></code></a></p></td>563</tr>564<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">**</span> <span class="pre">y</span></code></p></td>565<td><p><em>x</em> to the power <em>y</em></p></td>566<td><p>(5)</p></td>567<td></td>568</tr>569</tbody>570</table>571<p id="index-14">Notes:</p>572<ol class="arabic">573<li><p>Also referred to as integer division. For operands of type <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>,574the result has type <code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code>. For operands of type <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>,575the result has type <code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code>. In general, the result is a whole576integer, though the result’s type is not necessarily <code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code>. The result is577always rounded towards minus infinity: <code class="docutils literal notranslate"><span class="pre">1//2</span></code> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">(-1)//2</span></code> is578<code class="docutils literal notranslate"><span class="pre">-1</span></code>, <code class="docutils literal notranslate"><span class="pre">1//(-2)</span></code> is <code class="docutils literal notranslate"><span class="pre">-1</span></code>, and <code class="docutils literal notranslate"><span class="pre">(-1)//(-2)</span></code> is <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p></li>579<li><p>Not for complex numbers. Instead convert to floats using <a class="reference internal" href="functions.html#abs" title="abs"><code class="xref py py-func docutils literal notranslate"><span class="pre">abs()</span></code></a> if580appropriate.</p></li>581<li><p id="index-15">Conversion from <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> to <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> truncates, discarding the582fractional part. See functions <a class="reference internal" href="math.html#math.floor" title="math.floor"><code class="xref py py-func docutils literal notranslate"><span class="pre">math.floor()</span></code></a> and <a class="reference internal" href="math.html#math.ceil" title="math.ceil"><code class="xref py py-func docutils literal notranslate"><span class="pre">math.ceil()</span></code></a> for583alternative conversions.</p>584</li>585<li><p>float also accepts the strings “nan” and “inf” with an optional prefix “+”586or “-” for Not a Number (NaN) and positive or negative infinity.</p></li>587<li><p>Python defines <code class="docutils literal notranslate"><span class="pre">pow(0,</span> <span class="pre">0)</span></code> and <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">**</span> <span class="pre">0</span></code> to be <code class="docutils literal notranslate"><span class="pre">1</span></code>, as is common for588programming languages.</p></li>589<li><p>The numeric literals accepted include the digits <code class="docutils literal notranslate"><span class="pre">0</span></code> to <code class="docutils literal notranslate"><span class="pre">9</span></code> or any590Unicode equivalent (code points with the <code class="docutils literal notranslate"><span class="pre">Nd</span></code> property).</p>591<p>See <a class="reference external" href="https://unicode.org/Public/UNIDATA/extracted/DerivedNumericType.txt">the Unicode Standard</a>592for a complete list of code points with the <code class="docutils literal notranslate"><span class="pre">Nd</span></code> property.</p>593</li>594</ol>595<p>All <a class="reference internal" href="numbers.html#numbers.Real" title="numbers.Real"><code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Real</span></code></a> types (<a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> and <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) also include596the following operations:</p>597<table class="docutils align-default">598<thead>599<tr class="row-odd"><th class="head"><p>Operation</p></th>600<th class="head"><p>Result</p></th>601</tr>602</thead>603<tbody>604<tr class="row-even"><td><p><a class="reference internal" href="math.html#math.trunc" title="math.trunc"><code class="xref py py-func docutils literal notranslate"><span class="pre">math.trunc(x)</span></code></a></p></td>605<td><p><em>x</em> truncated to <a class="reference internal" href="numbers.html#numbers.Integral" title="numbers.Integral"><code class="xref py py-class docutils literal notranslate"><span class="pre">Integral</span></code></a></p></td>606</tr>607<tr class="row-odd"><td><p><a class="reference internal" href="functions.html#round" title="round"><code class="xref py py-func docutils literal notranslate"><span class="pre">round(x[,</span>608<span class="pre">n])</span></code></a></p></td>609<td><p><em>x</em> rounded to <em>n</em> digits,610rounding half to even. If <em>n</em> is611omitted, it defaults to 0.</p></td>612</tr>613<tr class="row-even"><td><p><a class="reference internal" href="math.html#math.floor" title="math.floor"><code class="xref py py-func docutils literal notranslate"><span class="pre">math.floor(x)</span></code></a></p></td>614<td><p>the greatest <a class="reference internal" href="numbers.html#numbers.Integral" title="numbers.Integral"><code class="xref py py-class docutils literal notranslate"><span class="pre">Integral</span></code></a>615<= <em>x</em></p></td>616</tr>617<tr class="row-odd"><td><p><a class="reference internal" href="math.html#math.ceil" title="math.ceil"><code class="xref py py-func docutils literal notranslate"><span class="pre">math.ceil(x)</span></code></a></p></td>618<td><p>the least <a class="reference internal" href="numbers.html#numbers.Integral" title="numbers.Integral"><code class="xref py py-class docutils literal notranslate"><span class="pre">Integral</span></code></a> >= <em>x</em></p></td>619</tr>620</tbody>621</table>622<p>For additional numeric operations see the <a class="reference internal" href="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> and <a class="reference internal" href="cmath.html#module-cmath" title="cmath: Mathematical functions for complex numbers."><code class="xref py py-mod docutils literal notranslate"><span class="pre">cmath</span></code></a>623modules.</p>624<section id="bitwise-operations-on-integer-types">625<span id="bitstring-ops"></span><h3>Bitwise Operations on Integer Types<a class="headerlink" href="#bitwise-operations-on-integer-types" title="Link to this heading">¶</a></h3>626<p id="index-16">Bitwise operations only make sense for integers. The result of bitwise627operations is calculated as though carried out in two’s complement with an628infinite number of sign bits.</p>629<p>The priorities of the binary bitwise operations are all lower than the numeric630operations and higher than the comparisons; the unary operation <code class="docutils literal notranslate"><span class="pre">~</span></code> has the631same priority as the other unary numeric operations (<code class="docutils literal notranslate"><span class="pre">+</span></code> and <code class="docutils literal notranslate"><span class="pre">-</span></code>).</p>632<p>This table lists the bitwise operations sorted in ascending priority:</p>633<table class="docutils align-default">634<thead>635<tr class="row-odd"><th class="head"><p>Operation</p></th>636<th class="head"><p>Result</p></th>637<th class="head"><p>Notes</p></th>638</tr>639</thead>640<tbody>641<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">|</span> <span class="pre">y</span></code></p></td>642<td><p>bitwise <em class="dfn">or</em> of <em>x</em> and643<em>y</em></p></td>644<td><p>(4)</p></td>645</tr>646<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">^</span> <span class="pre">y</span></code></p></td>647<td><p>bitwise <em class="dfn">exclusive or</em> of648<em>x</em> and <em>y</em></p></td>649<td><p>(4)</p></td>650</tr>651<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">&</span> <span class="pre">y</span></code></p></td>652<td><p>bitwise <em class="dfn">and</em> of <em>x</em> and653<em>y</em></p></td>654<td><p>(4)</p></td>655</tr>656<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre"><<</span> <span class="pre">n</span></code></p></td>657<td><p><em>x</em> shifted left by <em>n</em> bits</p></td>658<td><p>(1)(2)</p></td>659</tr>660<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">>></span> <span class="pre">n</span></code></p></td>661<td><p><em>x</em> shifted right by <em>n</em> bits</p></td>662<td><p>(1)(3)</p></td>663</tr>664<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">~x</span></code></p></td>665<td><p>the bits of <em>x</em> inverted</p></td>666<td></td>667</tr>668</tbody>669</table>670<p>Notes:</p>671<ol class="arabic simple">672<li><p>Negative shift counts are illegal and cause a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> to be raised.</p></li>673<li><p>A left shift by <em>n</em> bits is equivalent to multiplication by <code class="docutils literal notranslate"><span class="pre">pow(2,</span> <span class="pre">n)</span></code>.</p></li>674<li><p>A right shift by <em>n</em> bits is equivalent to floor division by <code class="docutils literal notranslate"><span class="pre">pow(2,</span> <span class="pre">n)</span></code>.</p></li>675<li><p>Performing these calculations with at least one extra sign extension bit in676a finite two’s complement representation (a working bit-width of677<code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre">+</span> <span class="pre">max(x.bit_length(),</span> <span class="pre">y.bit_length())</span></code> or more) is sufficient to get the678same result as if there were an infinite number of sign bits.</p></li>679</ol>680</section>681<section id="additional-methods-on-integer-types">682<h3>Additional Methods on Integer Types<a class="headerlink" href="#additional-methods-on-integer-types" title="Link to this heading">¶</a></h3>683<p>The int type implements the <a class="reference internal" href="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="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base684class</span></a>. In addition, it provides a few more methods:</p>685<dl class="py method">686<dt class="sig sig-object py" id="int.bit_length">687<span class="sig-prename descclassname"><span class="pre">int.</span></span><span class="sig-name descname"><span class="pre">bit_length</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#int.bit_length" title="Link to this definition">¶</a></dt>688<dd><p>Return the number of bits necessary to represent an integer in binary,689excluding the sign and leading zeros:</p>690<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">n</span> <span class="o">=</span> <span class="o">-</span><span class="mi">37</span>691<span class="gp">>>> </span><span class="nb">bin</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>692<span class="go">'-0b100101'</span>693<span class="gp">>>> </span><span class="n">n</span><span class="o">.</span><span class="n">bit_length</span><span class="p">()</span>694<span class="go">6</span>695</pre></div>696</div>697<p>More precisely, if <code class="docutils literal notranslate"><span class="pre">x</span></code> is nonzero, then <code class="docutils literal notranslate"><span class="pre">x.bit_length()</span></code> is the698unique positive integer <code class="docutils literal notranslate"><span class="pre">k</span></code> such that <code class="docutils literal notranslate"><span class="pre">2**(k-1)</span> <span class="pre"><=</span> <span class="pre">abs(x)</span> <span class="pre"><</span> <span class="pre">2**k</span></code>.699Equivalently, when <code class="docutils literal notranslate"><span class="pre">abs(x)</span></code> is small enough to have a correctly700rounded logarithm, then <code class="docutils literal notranslate"><span class="pre">k</span> <span class="pre">=</span> <span class="pre">1</span> <span class="pre">+</span> <span class="pre">int(log(abs(x),</span> <span class="pre">2))</span></code>.701If <code class="docutils literal notranslate"><span class="pre">x</span></code> is zero, then <code class="docutils literal notranslate"><span class="pre">x.bit_length()</span></code> returns <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>702<p>Equivalent to:</p>703<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">bit_length</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>704 <span class="n">s</span> <span class="o">=</span> <span class="nb">bin</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="c1"># binary representation: bin(-37) --> '-0b100101'</span>705 <span class="n">s</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">lstrip</span><span class="p">(</span><span class="s1">'-0b'</span><span class="p">)</span> <span class="c1"># remove leading zeros and minus sign</span>706 <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="c1"># len('100101') --> 6</span>707</pre></div>708</div>709<div class="versionadded">710<p><span class="versionmodified added">Added in version 3.1.</span></p>711</div>712</dd></dl>713 714<dl class="py method">715<dt class="sig sig-object py" id="int.bit_count">716<span class="sig-prename descclassname"><span class="pre">int.</span></span><span class="sig-name descname"><span class="pre">bit_count</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#int.bit_count" title="Link to this definition">¶</a></dt>717<dd><p>Return the number of ones in the binary representation of the absolute718value of the integer. This is also known as the population count.719Example:</p>720<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">n</span> <span class="o">=</span> <span class="mi">19</span>721<span class="gp">>>> </span><span class="nb">bin</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>722<span class="go">'0b10011'</span>723<span class="gp">>>> </span><span class="n">n</span><span class="o">.</span><span class="n">bit_count</span><span class="p">()</span>724<span class="go">3</span>725<span class="gp">>>> </span><span class="p">(</span><span class="o">-</span><span class="n">n</span><span class="p">)</span><span class="o">.</span><span class="n">bit_count</span><span class="p">()</span>726<span class="go">3</span>727</pre></div>728</div>729<p>Equivalent to:</p>730<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">bit_count</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>731 <span class="k">return</span> <span class="nb">bin</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="s2">"1"</span><span class="p">)</span>732</pre></div>733</div>734<div class="versionadded">735<p><span class="versionmodified added">Added in version 3.10.</span></p>736</div>737</dd></dl>738 739<dl class="py method">740<dt class="sig sig-object py" id="int.to_bytes">741<span class="sig-prename descclassname"><span class="pre">int.</span></span><span class="sig-name descname"><span class="pre">to_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">length</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">byteorder</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'big'</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">signed</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#int.to_bytes" title="Link to this definition">¶</a></dt>742<dd><p>Return an array of bytes representing an integer.</p>743<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">)</span>744<span class="go">b'\x04\x00'</span>745<span class="gp">>>> </span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">)</span>746<span class="go">b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'</span>747<span class="gp">>>> </span><span class="p">(</span><span class="o">-</span><span class="mi">1024</span><span class="p">)</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">,</span> <span class="n">signed</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>748<span class="go">b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'</span>749<span class="gp">>>> </span><span class="n">x</span> <span class="o">=</span> <span class="mi">1000</span>750<span class="gp">>>> </span><span class="n">x</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">((</span><span class="n">x</span><span class="o">.</span><span class="n">bit_length</span><span class="p">()</span> <span class="o">+</span> <span class="mi">7</span><span class="p">)</span> <span class="o">//</span> <span class="mi">8</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'little'</span><span class="p">)</span>751<span class="go">b'\xe8\x03'</span>752</pre></div>753</div>754<p>The integer is represented using <em>length</em> bytes, and defaults to 1. An755<a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is raised if the integer is not representable with756the given number of bytes.</p>757<p>The <em>byteorder</em> argument determines the byte order used to represent the758integer, and defaults to <code class="docutils literal notranslate"><span class="pre">"big"</span></code>. If <em>byteorder</em> is759<code class="docutils literal notranslate"><span class="pre">"big"</span></code>, the most significant byte is at the beginning of the byte760array. If <em>byteorder</em> is <code class="docutils literal notranslate"><span class="pre">"little"</span></code>, the most significant byte is at761the end of the byte array.</p>762<p>The <em>signed</em> argument determines whether two’s complement is used to763represent the integer. If <em>signed</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> and a negative integer is764given, an <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is raised. The default value for <em>signed</em>765is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>766<p>The default values can be used to conveniently turn an integer into a767single byte object:</p>768<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="p">(</span><span class="mi">65</span><span class="p">)</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">()</span>769<span class="go">b'A'</span>770</pre></div>771</div>772<p>However, when using the default arguments, don’t try773to convert a value greater than 255 or you’ll get an <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a>.</p>774<p>Equivalent to:</p>775<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">to_bytes</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">length</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">,</span> <span class="n">signed</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>776 <span class="k">if</span> <span class="n">byteorder</span> <span class="o">==</span> <span class="s1">'little'</span><span class="p">:</span>777 <span class="n">order</span> <span class="o">=</span> <span class="nb">range</span><span class="p">(</span><span class="n">length</span><span class="p">)</span>778 <span class="k">elif</span> <span class="n">byteorder</span> <span class="o">==</span> <span class="s1">'big'</span><span class="p">:</span>779 <span class="n">order</span> <span class="o">=</span> <span class="nb">reversed</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">length</span><span class="p">))</span>780 <span class="k">else</span><span class="p">:</span>781 <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"byteorder must be either 'little' or 'big'"</span><span class="p">)</span>782 783 <span class="k">return</span> <span class="nb">bytes</span><span class="p">((</span><span class="n">n</span> <span class="o">>></span> <span class="n">i</span><span class="o">*</span><span class="mi">8</span><span class="p">)</span> <span class="o">&</span> <span class="mh">0xff</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">order</span><span class="p">)</span>784</pre></div>785</div>786<div class="versionadded">787<p><span class="versionmodified added">Added in version 3.2.</span></p>788</div>789<div class="versionchanged">790<p><span class="versionmodified changed">Changed in version 3.11: </span>Added default argument values for <code class="docutils literal notranslate"><span class="pre">length</span></code> and <code class="docutils literal notranslate"><span class="pre">byteorder</span></code>.</p>791</div>792</dd></dl>793 794<dl class="py method">795<dt class="sig sig-object py" id="int.from_bytes">796<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">int.</span></span><span class="sig-name descname"><span class="pre">from_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">bytes</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">byteorder</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'big'</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">signed</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#int.from_bytes" title="Link to this definition">¶</a></dt>797<dd><p>Return the integer represented by the given array of bytes.</p>798<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">int</span><span class="o">.</span><span class="n">from_bytes</span><span class="p">(</span><span class="sa">b</span><span class="s1">'</span><span class="se">\x00\x10</span><span class="s1">'</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">)</span>799<span class="go">16</span>800<span class="gp">>>> </span><span class="nb">int</span><span class="o">.</span><span class="n">from_bytes</span><span class="p">(</span><span class="sa">b</span><span class="s1">'</span><span class="se">\x00\x10</span><span class="s1">'</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'little'</span><span class="p">)</span>801<span class="go">4096</span>802<span class="gp">>>> </span><span class="nb">int</span><span class="o">.</span><span class="n">from_bytes</span><span class="p">(</span><span class="sa">b</span><span class="s1">'</span><span class="se">\xfc\x00</span><span class="s1">'</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">,</span> <span class="n">signed</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>803<span class="go">-1024</span>804<span class="gp">>>> </span><span class="nb">int</span><span class="o">.</span><span class="n">from_bytes</span><span class="p">(</span><span class="sa">b</span><span class="s1">'</span><span class="se">\xfc\x00</span><span class="s1">'</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">,</span> <span class="n">signed</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>805<span class="go">64512</span>806<span class="gp">>>> </span><span class="nb">int</span><span class="o">.</span><span class="n">from_bytes</span><span class="p">([</span><span class="mi">255</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">)</span>807<span class="go">16711680</span>808</pre></div>809</div>810<p>The argument <em>bytes</em> must either be a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> or an811iterable producing bytes.</p>812<p>The <em>byteorder</em> argument determines the byte order used to represent the813integer, and defaults to <code class="docutils literal notranslate"><span class="pre">"big"</span></code>. If <em>byteorder</em> is814<code class="docutils literal notranslate"><span class="pre">"big"</span></code>, the most significant byte is at the beginning of the byte815array. If <em>byteorder</em> is <code class="docutils literal notranslate"><span class="pre">"little"</span></code>, the most significant byte is at816the end of the byte array. To request the native byte order of the host817system, use <a class="reference internal" href="sys.html#sys.byteorder" title="sys.byteorder"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.byteorder</span></code></a> as the byte order value.</p>818<p>The <em>signed</em> argument indicates whether two’s complement is used to819represent the integer.</p>820<p>Equivalent to:</p>821<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">from_bytes</span><span class="p">(</span><span class="nb">bytes</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">'big'</span><span class="p">,</span> <span class="n">signed</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>822 <span class="k">if</span> <span class="n">byteorder</span> <span class="o">==</span> <span class="s1">'little'</span><span class="p">:</span>823 <span class="n">little_ordered</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">bytes</span><span class="p">)</span>824 <span class="k">elif</span> <span class="n">byteorder</span> <span class="o">==</span> <span class="s1">'big'</span><span class="p">:</span>825 <span class="n">little_ordered</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">reversed</span><span class="p">(</span><span class="nb">bytes</span><span class="p">))</span>826 <span class="k">else</span><span class="p">:</span>827 <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"byteorder must be either 'little' or 'big'"</span><span class="p">)</span>828 829 <span class="n">n</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="n">b</span> <span class="o"><<</span> <span class="n">i</span><span class="o">*</span><span class="mi">8</span> <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">b</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">little_ordered</span><span class="p">))</span>830 <span class="k">if</span> <span class="n">signed</span> <span class="ow">and</span> <span class="n">little_ordered</span> <span class="ow">and</span> <span class="p">(</span><span class="n">little_ordered</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">&</span> <span class="mh">0x80</span><span class="p">):</span>831 <span class="n">n</span> <span class="o">-=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">8</span><span class="o">*</span><span class="nb">len</span><span class="p">(</span><span class="n">little_ordered</span><span class="p">)</span>832 833 <span class="k">return</span> <span class="n">n</span>834</pre></div>835</div>836<div class="versionadded">837<p><span class="versionmodified added">Added in version 3.2.</span></p>838</div>839<div class="versionchanged">840<p><span class="versionmodified changed">Changed in version 3.11: </span>Added default argument value for <code class="docutils literal notranslate"><span class="pre">byteorder</span></code>.</p>841</div>842</dd></dl>843 844<dl class="py method">845<dt class="sig sig-object py" id="int.as_integer_ratio">846<span class="sig-prename descclassname"><span class="pre">int.</span></span><span class="sig-name descname"><span class="pre">as_integer_ratio</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#int.as_integer_ratio" title="Link to this definition">¶</a></dt>847<dd><p>Return a pair of integers whose ratio is equal to the original848integer and has a positive denominator. The integer ratio of integers849(whole numbers) is always the integer as the numerator and <code class="docutils literal notranslate"><span class="pre">1</span></code> as the850denominator.</p>851<div class="versionadded">852<p><span class="versionmodified added">Added in version 3.8.</span></p>853</div>854</dd></dl>855 856<dl class="py method">857<dt class="sig sig-object py" id="int.is_integer">858<span class="sig-prename descclassname"><span class="pre">int.</span></span><span class="sig-name descname"><span class="pre">is_integer</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#int.is_integer" title="Link to this definition">¶</a></dt>859<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code>. Exists for duck type compatibility with <a class="reference internal" href="#float.is_integer" title="float.is_integer"><code class="xref py py-meth docutils literal notranslate"><span class="pre">float.is_integer()</span></code></a>.</p>860<div class="versionadded">861<p><span class="versionmodified added">Added in version 3.12.</span></p>862</div>863</dd></dl>864 865</section>866<section id="additional-methods-on-float">867<h3>Additional Methods on Float<a class="headerlink" href="#additional-methods-on-float" title="Link to this heading">¶</a></h3>868<p>The float type implements the <a class="reference internal" href="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="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base869class</span></a>. float also has the following additional methods.</p>870<dl class="py method">871<dt class="sig sig-object py" id="float.from_number">872<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">float.</span></span><span class="sig-name descname"><span class="pre">from_number</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#float.from_number" title="Link to this definition">¶</a></dt>873<dd><p>Class method to return a floating-point number constructed from a number <em>x</em>.</p>874<p>If the argument is an integer or a floating-point number, a875floating-point number with the same value (within Python’s floating-point876precision) is returned. If the argument is outside the range of a Python877float, an <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> will be raised.</p>878<p>For a general Python object <code class="docutils literal notranslate"><span class="pre">x</span></code>, <code class="docutils literal notranslate"><span class="pre">float.from_number(x)</span></code> delegates to879<code class="docutils literal notranslate"><span class="pre">x.__float__()</span></code>.880If <a class="reference internal" href="../reference/datamodel.html#object.__float__" title="object.__float__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__float__()</span></code></a> is not defined then it falls back881to <a class="reference internal" href="../reference/datamodel.html#object.__index__" title="object.__index__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__index__()</span></code></a>.</p>882<div class="versionadded">883<p><span class="versionmodified added">Added in version 3.14.</span></p>884</div>885</dd></dl>886 887<dl class="py method">888<dt class="sig sig-object py" id="float.as_integer_ratio">889<span class="sig-prename descclassname"><span class="pre">float.</span></span><span class="sig-name descname"><span class="pre">as_integer_ratio</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#float.as_integer_ratio" title="Link to this definition">¶</a></dt>890<dd><p>Return a pair of integers whose ratio is exactly equal to the891original float. The ratio is in lowest terms and has a positive denominator. Raises892<a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> on infinities and a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> on893NaNs.</p>894</dd></dl>895 896<dl class="py method">897<dt class="sig sig-object py" id="float.is_integer">898<span class="sig-prename descclassname"><span class="pre">float.</span></span><span class="sig-name descname"><span class="pre">is_integer</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#float.is_integer" title="Link to this definition">¶</a></dt>899<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the float instance is finite with integral900value, and <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise:</p>901<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="p">(</span><span class="o">-</span><span class="mf">2.0</span><span class="p">)</span><span class="o">.</span><span class="n">is_integer</span><span class="p">()</span>902<span class="go">True</span>903<span class="gp">>>> </span><span class="p">(</span><span class="mf">3.2</span><span class="p">)</span><span class="o">.</span><span class="n">is_integer</span><span class="p">()</span>904<span class="go">False</span>905</pre></div>906</div>907</dd></dl>908 909<p>Two methods support conversion to910and from hexadecimal strings. Since Python’s floats are stored911internally as binary numbers, converting a float to or from a912<em>decimal</em> string usually involves a small rounding error. In913contrast, hexadecimal strings allow exact representation and914specification of floating-point numbers. This can be useful when915debugging, and in numerical work.</p>916<dl class="py method">917<dt class="sig sig-object py" id="float.hex">918<span class="sig-prename descclassname"><span class="pre">float.</span></span><span class="sig-name descname"><span class="pre">hex</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#float.hex" title="Link to this definition">¶</a></dt>919<dd><p>Return a representation of a floating-point number as a hexadecimal920string. For finite floating-point numbers, this representation921will always include a leading <code class="docutils literal notranslate"><span class="pre">0x</span></code> and a trailing <code class="docutils literal notranslate"><span class="pre">p</span></code> and922exponent.</p>923</dd></dl>924 925<dl class="py method">926<dt class="sig sig-object py" id="float.fromhex">927<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">float.</span></span><span class="sig-name descname"><span class="pre">fromhex</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#float.fromhex" title="Link to this definition">¶</a></dt>928<dd><p>Class method to return the float represented by a hexadecimal929string <em>s</em>. The string <em>s</em> may have leading and trailing930whitespace.</p>931</dd></dl>932 933<p>Note that <a class="reference internal" href="#float.hex" title="float.hex"><code class="xref py py-meth docutils literal notranslate"><span class="pre">float.hex()</span></code></a> is an instance method, while934<a class="reference internal" href="#float.fromhex" title="float.fromhex"><code class="xref py py-meth docutils literal notranslate"><span class="pre">float.fromhex()</span></code></a> is a class method.</p>935<p>A hexadecimal string takes the form:</p>936<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">sign</span><span class="p">]</span> <span class="p">[</span><span class="s1">'0x'</span><span class="p">]</span> <span class="n">integer</span> <span class="p">[</span><span class="s1">'.'</span> <span class="n">fraction</span><span class="p">]</span> <span class="p">[</span><span class="s1">'p'</span> <span class="n">exponent</span><span class="p">]</span>937</pre></div>938</div>939<p>where the optional <code class="docutils literal notranslate"><span class="pre">sign</span></code> may by either <code class="docutils literal notranslate"><span class="pre">+</span></code> or <code class="docutils literal notranslate"><span class="pre">-</span></code>, <code class="docutils literal notranslate"><span class="pre">integer</span></code>940and <code class="docutils literal notranslate"><span class="pre">fraction</span></code> are strings of hexadecimal digits, and <code class="docutils literal notranslate"><span class="pre">exponent</span></code>941is a decimal integer with an optional leading sign. Case is not942significant, and there must be at least one hexadecimal digit in943either the integer or the fraction. This syntax is similar to the944syntax specified in section 6.4.4.2 of the C99 standard, and also to945the syntax used in Java 1.5 onwards. In particular, the output of946<a class="reference internal" href="#float.hex" title="float.hex"><code class="xref py py-meth docutils literal notranslate"><span class="pre">float.hex()</span></code></a> is usable as a hexadecimal floating-point literal in947C or Java code, and hexadecimal strings produced by C’s <code class="docutils literal notranslate"><span class="pre">%a</span></code> format948character or Java’s <code class="docutils literal notranslate"><span class="pre">Double.toHexString</span></code> are accepted by949<a class="reference internal" href="#float.fromhex" title="float.fromhex"><code class="xref py py-meth docutils literal notranslate"><span class="pre">float.fromhex()</span></code></a>.</p>950<p>Note that the exponent is written in decimal rather than hexadecimal,951and that it gives the power of 2 by which to multiply the coefficient.952For example, the hexadecimal string <code class="docutils literal notranslate"><span class="pre">0x3.a7p10</span></code> represents the953floating-point number <code class="docutils literal notranslate"><span class="pre">(3</span> <span class="pre">+</span> <span class="pre">10./16</span> <span class="pre">+</span> <span class="pre">7./16**2)</span> <span class="pre">*</span> <span class="pre">2.0**10</span></code>, or954<code class="docutils literal notranslate"><span class="pre">3740.0</span></code>:</p>955<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">float</span><span class="o">.</span><span class="n">fromhex</span><span class="p">(</span><span class="s1">'0x3.a7p10'</span><span class="p">)</span>956<span class="go">3740.0</span>957</pre></div>958</div>959<p>Applying the reverse conversion to <code class="docutils literal notranslate"><span class="pre">3740.0</span></code> gives a different960hexadecimal string representing the same number:</p>961<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">float</span><span class="o">.</span><span class="n">hex</span><span class="p">(</span><span class="mf">3740.0</span><span class="p">)</span>962<span class="go">'0x1.d380000000000p+11'</span>963</pre></div>964</div>965</section>966<section id="additional-methods-on-complex">967<h3>Additional Methods on Complex<a class="headerlink" href="#additional-methods-on-complex" title="Link to this heading">¶</a></h3>968<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code> type implements the <a class="reference internal" href="numbers.html#numbers.Complex" title="numbers.Complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">numbers.Complex</span></code></a>969<a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a>.970<code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code> also has the following additional methods.</p>971<dl class="py method">972<dt class="sig sig-object py" id="complex.from_number">973<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">complex.</span></span><span class="sig-name descname"><span class="pre">from_number</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#complex.from_number" title="Link to this definition">¶</a></dt>974<dd><p>Class method to convert a number to a complex number.</p>975<p>For a general Python object <code class="docutils literal notranslate"><span class="pre">x</span></code>, <code class="docutils literal notranslate"><span class="pre">complex.from_number(x)</span></code> delegates to976<code class="docutils literal notranslate"><span class="pre">x.__complex__()</span></code>. If <a class="reference internal" href="../reference/datamodel.html#object.__complex__" title="object.__complex__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__complex__()</span></code></a> is not defined then it falls back977to <a class="reference internal" href="../reference/datamodel.html#object.__float__" title="object.__float__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__float__()</span></code></a>. If <code class="xref py py-meth docutils literal notranslate"><span class="pre">__float__()</span></code> is not defined then it falls back978to <a class="reference internal" href="../reference/datamodel.html#object.__index__" title="object.__index__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__index__()</span></code></a>.</p>979<div class="versionadded">980<p><span class="versionmodified added">Added in version 3.14.</span></p>981</div>982</dd></dl>983 984</section>985<section id="hashing-of-numeric-types">986<span id="numeric-hash"></span><h3>Hashing of numeric types<a class="headerlink" href="#hashing-of-numeric-types" title="Link to this heading">¶</a></h3>987<p>For numbers <code class="docutils literal notranslate"><span class="pre">x</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span></code>, possibly of different types, it’s a requirement988that <code class="docutils literal notranslate"><span class="pre">hash(x)</span> <span class="pre">==</span> <span class="pre">hash(y)</span></code> whenever <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></code> (see the <a class="reference internal" href="../reference/datamodel.html#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a>989method documentation for more details). For ease of implementation and990efficiency across a variety of numeric types (including <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>,991<a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, <a class="reference internal" href="decimal.html#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Decimal</span></code></a> and <a class="reference internal" href="fractions.html#fractions.Fraction" title="fractions.Fraction"><code class="xref py py-class docutils literal notranslate"><span class="pre">fractions.Fraction</span></code></a>)992Python’s hash for numeric types is based on a single mathematical function993that’s defined for any rational number, and hence applies to all instances of994<code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code> and <code class="xref py py-class docutils literal notranslate"><span class="pre">fractions.Fraction</span></code>, and all finite instances of995<code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code> and <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Decimal</span></code>. Essentially, this function is996given by reduction modulo <code class="docutils literal notranslate"><span class="pre">P</span></code> for a fixed prime <code class="docutils literal notranslate"><span class="pre">P</span></code>. The value of <code class="docutils literal notranslate"><span class="pre">P</span></code> is997made available to Python as the <a class="reference internal" href="sys.html#sys.hash_info.modulus" title="sys.hash_info.modulus"><code class="xref py py-attr docutils literal notranslate"><span class="pre">modulus</span></code></a> attribute of998<a class="reference internal" href="sys.html#sys.hash_info" title="sys.hash_info"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.hash_info</span></code></a>.</p>999<div class="impl-detail compound">1000<p><strong>CPython implementation detail:</strong> Currently, the prime used is <code class="docutils literal notranslate"><span class="pre">P</span> <span class="pre">=</span> <span class="pre">2**31</span> <span class="pre">-</span> <span class="pre">1</span></code> on machines with 32-bit C1001longs and <code class="docutils literal notranslate"><span class="pre">P</span> <span class="pre">=</span> <span class="pre">2**61</span> <span class="pre">-</span> <span class="pre">1</span></code> on machines with 64-bit C longs.</p>1002</div>1003<p>Here are the rules in detail:</p>1004<ul class="simple">1005<li><p>If <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">m</span> <span class="pre">/</span> <span class="pre">n</span></code> is a nonnegative rational number and <code class="docutils literal notranslate"><span class="pre">n</span></code> is not divisible1006by <code class="docutils literal notranslate"><span class="pre">P</span></code>, define <code class="docutils literal notranslate"><span class="pre">hash(x)</span></code> as <code class="docutils literal notranslate"><span class="pre">m</span> <span class="pre">*</span> <span class="pre">invmod(n,</span> <span class="pre">P)</span> <span class="pre">%</span> <span class="pre">P</span></code>, where <code class="docutils literal notranslate"><span class="pre">invmod(n,</span>1007<span class="pre">P)</span></code> gives the inverse of <code class="docutils literal notranslate"><span class="pre">n</span></code> modulo <code class="docutils literal notranslate"><span class="pre">P</span></code>.</p></li>1008<li><p>If <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">m</span> <span class="pre">/</span> <span class="pre">n</span></code> is a nonnegative rational number and <code class="docutils literal notranslate"><span class="pre">n</span></code> is1009divisible by <code class="docutils literal notranslate"><span class="pre">P</span></code> (but <code class="docutils literal notranslate"><span class="pre">m</span></code> is not) then <code class="docutils literal notranslate"><span class="pre">n</span></code> has no inverse1010modulo <code class="docutils literal notranslate"><span class="pre">P</span></code> and the rule above doesn’t apply; in this case define1011<code class="docutils literal notranslate"><span class="pre">hash(x)</span></code> to be the constant value <code class="docutils literal notranslate"><span class="pre">sys.hash_info.inf</span></code>.</p></li>1012<li><p>If <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">m</span> <span class="pre">/</span> <span class="pre">n</span></code> is a negative rational number define <code class="docutils literal notranslate"><span class="pre">hash(x)</span></code>1013as <code class="docutils literal notranslate"><span class="pre">-hash(-x)</span></code>. If the resulting hash is <code class="docutils literal notranslate"><span class="pre">-1</span></code>, replace it with1014<code class="docutils literal notranslate"><span class="pre">-2</span></code>.</p></li>1015<li><p>The particular values <code class="docutils literal notranslate"><span class="pre">sys.hash_info.inf</span></code> and <code class="docutils literal notranslate"><span class="pre">-sys.hash_info.inf</span></code>1016are used as hash values for positive1017infinity or negative infinity (respectively).</p></li>1018<li><p>For a <a class="reference internal" href="functions.html#complex" title="complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a> number <code class="docutils literal notranslate"><span class="pre">z</span></code>, the hash values of the real1019and imaginary parts are combined by computing <code class="docutils literal notranslate"><span class="pre">hash(z.real)</span> <span class="pre">+</span>1020<span class="pre">sys.hash_info.imag</span> <span class="pre">*</span> <span class="pre">hash(z.imag)</span></code>, reduced modulo1021<code class="docutils literal notranslate"><span class="pre">2**sys.hash_info.width</span></code> so that it lies in1022<code class="docutils literal notranslate"><span class="pre">range(-2**(sys.hash_info.width</span> <span class="pre">-</span> <span class="pre">1),</span> <span class="pre">2**(sys.hash_info.width</span> <span class="pre">-</span>1023<span class="pre">1))</span></code>. Again, if the result is <code class="docutils literal notranslate"><span class="pre">-1</span></code>, it’s replaced with <code class="docutils literal notranslate"><span class="pre">-2</span></code>.</p></li>1024</ul>1025<p>To clarify the above rules, here’s some example Python code,1026equivalent to the built-in hash, for computing the hash of a rational1027number, <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, or <a class="reference internal" href="functions.html#complex" title="complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a>:</p>1028<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">sys</span><span class="o">,</span><span class="w"> </span><span class="nn">math</span>1029 1030<span class="k">def</span><span class="w"> </span><span class="nf">hash_fraction</span><span class="p">(</span><span class="n">m</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>1031<span class="w"> </span><span class="sd">"""Compute the hash of a rational number m / n.</span>1032 1033<span class="sd"> Assumes m and n are integers, with n positive.</span>1034<span class="sd"> Equivalent to hash(fractions.Fraction(m, n)).</span>1035 1036<span class="sd"> """</span>1037 <span class="n">P</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">hash_info</span><span class="o">.</span><span class="n">modulus</span>1038 <span class="c1"># Remove common factors of P. (Unnecessary if m and n already coprime.)</span>1039 <span class="k">while</span> <span class="n">m</span> <span class="o">%</span> <span class="n">P</span> <span class="o">==</span> <span class="n">n</span> <span class="o">%</span> <span class="n">P</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>1040 <span class="n">m</span><span class="p">,</span> <span class="n">n</span> <span class="o">=</span> <span class="n">m</span> <span class="o">//</span> <span class="n">P</span><span class="p">,</span> <span class="n">n</span> <span class="o">//</span> <span class="n">P</span>1041 1042 <span class="k">if</span> <span class="n">n</span> <span class="o">%</span> <span class="n">P</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>1043 <span class="n">hash_value</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">hash_info</span><span class="o">.</span><span class="n">inf</span>1044 <span class="k">else</span><span class="p">:</span>1045 <span class="c1"># Fermat's Little Theorem: pow(n, P-1, P) is 1, so</span>1046 <span class="c1"># pow(n, P-2, P) gives the inverse of n modulo P.</span>1047 <span class="n">hash_value</span> <span class="o">=</span> <span class="p">(</span><span class="nb">abs</span><span class="p">(</span><span class="n">m</span><span class="p">)</span> <span class="o">%</span> <span class="n">P</span><span class="p">)</span> <span class="o">*</span> <span class="nb">pow</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">P</span> <span class="o">-</span> <span class="mi">2</span><span class="p">,</span> <span class="n">P</span><span class="p">)</span> <span class="o">%</span> <span class="n">P</span>1048 <span class="k">if</span> <span class="n">m</span> <span class="o"><</span> <span class="mi">0</span><span class="p">:</span>1049 <span class="n">hash_value</span> <span class="o">=</span> <span class="o">-</span><span class="n">hash_value</span>1050 <span class="k">if</span> <span class="n">hash_value</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="p">:</span>1051 <span class="n">hash_value</span> <span class="o">=</span> <span class="o">-</span><span class="mi">2</span>1052 <span class="k">return</span> <span class="n">hash_value</span>1053 1054<span class="k">def</span><span class="w"> </span><span class="nf">hash_float</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>1055<span class="w"> </span><span class="sd">"""Compute the hash of a float x."""</span>1056 1057 <span class="k">if</span> <span class="n">math</span><span class="o">.</span><span class="n">isnan</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>1058 <span class="k">return</span> <span class="nb">object</span><span class="o">.</span><span class="fm">__hash__</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>1059 <span class="k">elif</span> <span class="n">math</span><span class="o">.</span><span class="n">isinf</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>1060 <span class="k">return</span> <span class="n">sys</span><span class="o">.</span><span class="n">hash_info</span><span class="o">.</span><span class="n">inf</span> <span class="k">if</span> <span class="n">x</span> <span class="o">></span> <span class="mi">0</span> <span class="k">else</span> <span class="o">-</span><span class="n">sys</span><span class="o">.</span><span class="n">hash_info</span><span class="o">.</span><span class="n">inf</span>1061 <span class="k">else</span><span class="p">:</span>1062 <span class="k">return</span> <span class="n">hash_fraction</span><span class="p">(</span><span class="o">*</span><span class="n">x</span><span class="o">.</span><span class="n">as_integer_ratio</span><span class="p">())</span>1063 1064<span class="k">def</span><span class="w"> </span><span class="nf">hash_complex</span><span class="p">(</span><span class="n">z</span><span class="p">):</span>1065<span class="w"> </span><span class="sd">"""Compute the hash of a complex number z."""</span>1066 1067 <span class="n">hash_value</span> <span class="o">=</span> <span class="n">hash_float</span><span class="p">(</span><span class="n">z</span><span class="o">.</span><span class="n">real</span><span class="p">)</span> <span class="o">+</span> <span class="n">sys</span><span class="o">.</span><span class="n">hash_info</span><span class="o">.</span><span class="n">imag</span> <span class="o">*</span> <span class="n">hash_float</span><span class="p">(</span><span class="n">z</span><span class="o">.</span><span class="n">imag</span><span class="p">)</span>1068 <span class="c1"># do a signed reduction modulo 2**sys.hash_info.width</span>1069 <span class="n">M</span> <span class="o">=</span> <span class="mi">2</span><span class="o">**</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">hash_info</span><span class="o">.</span><span class="n">width</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span>1070 <span class="n">hash_value</span> <span class="o">=</span> <span class="p">(</span><span class="n">hash_value</span> <span class="o">&</span> <span class="p">(</span><span class="n">M</span> <span class="o">-</span> <span class="mi">1</span><span class="p">))</span> <span class="o">-</span> <span class="p">(</span><span class="n">hash_value</span> <span class="o">&</span> <span class="n">M</span><span class="p">)</span>1071 <span class="k">if</span> <span class="n">hash_value</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="p">:</span>1072 <span class="n">hash_value</span> <span class="o">=</span> <span class="o">-</span><span class="mi">2</span>1073 <span class="k">return</span> <span class="n">hash_value</span>1074</pre></div>1075</div>1076</section>1077</section>1078<section id="boolean-type-bool">1079<span id="typebool"></span><span id="bltin-boolean-values"></span><h2>Boolean Type - <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a><a class="headerlink" href="#boolean-type-bool" title="Link to this heading">¶</a></h2>1080<p>Booleans represent truth values. The <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a> type has exactly two1081constant instances: <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>1082<p id="index-17">The built-in function <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-func docutils literal notranslate"><span class="pre">bool()</span></code></a> converts any value to a boolean, if the1083value can be interpreted as a truth value (see section <a class="reference internal" href="#truth"><span class="std std-ref">Truth Value Testing</span></a> above).</p>1084<p>For logical operations, use the <a class="reference internal" href="#boolean"><span class="std std-ref">boolean operators</span></a> <code class="docutils literal notranslate"><span class="pre">and</span></code>,1085<code class="docutils literal notranslate"><span class="pre">or</span></code> and <code class="docutils literal notranslate"><span class="pre">not</span></code>.1086When applying the bitwise operators <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> to two booleans, they1087return a bool equivalent to the logical operations “and”, “or”, “xor”. However,1088the logical operators <code class="docutils literal notranslate"><span class="pre">and</span></code>, <code class="docutils literal notranslate"><span class="pre">or</span></code> and <code class="docutils literal notranslate"><span class="pre">!=</span></code> should be preferred1089over <code class="docutils literal notranslate"><span class="pre">&</span></code>, <code class="docutils literal notranslate"><span class="pre">|</span></code> and <code class="docutils literal notranslate"><span class="pre">^</span></code>.</p>1090<div class="deprecated">1091<p><span class="versionmodified deprecated">Deprecated since version 3.12: </span>The use of the bitwise inversion operator <code class="docutils literal notranslate"><span class="pre">~</span></code> is deprecated and will1092raise an error in Python 3.16.</p>1093</div>1094<p><a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a> is a subclass of <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> (see <a class="reference internal" href="#typesnumeric"><span class="std std-ref">Numeric Types — int, float, complex</span></a>). In1095many numeric contexts, <code class="docutils literal notranslate"><span class="pre">False</span></code> and <code class="docutils literal notranslate"><span class="pre">True</span></code> behave like the integers 0 and 1, respectively.1096However, relying on this is discouraged; explicitly convert using <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a>1097instead.</p>1098</section>1099<section id="iterator-types">1100<span id="typeiter"></span><h2>Iterator Types<a class="headerlink" href="#iterator-types" title="Link to this heading">¶</a></h2>1101<p id="index-18">Python supports a concept of iteration over containers. This is implemented1102using two distinct methods; these are used to allow user-defined classes to1103support iteration. Sequences, described below in more detail, always support1104the iteration methods.</p>1105<p>One method needs to be defined for container objects to provide <a class="reference internal" href="../glossary.html#term-iterable"><span class="xref std std-term">iterable</span></a>1106support:</p>1107<dl class="py method">1108<dt class="sig sig-object py" id="container.__iter__">1109<span class="sig-prename descclassname"><span class="pre">container.</span></span><span class="sig-name descname"><span class="pre">__iter__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#container.__iter__" title="Link to this definition">¶</a></dt>1110<dd><p>Return an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> object. The object is required to support the1111iterator protocol described below. If a container supports different types1112of iteration, additional methods can be provided to specifically request1113iterators for those iteration types. (An example of an object supporting1114multiple forms of iteration would be a tree structure which supports both1115breadth-first and depth-first traversal.) This method corresponds to the1116<a class="reference internal" href="../c-api/typeobj.html#c.PyTypeObject.tp_iter" title="PyTypeObject.tp_iter"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_iter</span></code></a> slot of the type structure for Python1117objects in the Python/C API.</p>1118</dd></dl>1119 1120<p>The iterator objects themselves are required to support the following two1121methods, which together form the <em class="dfn">iterator protocol</em>:</p>1122<dl class="py method">1123<dt class="sig sig-object py" id="iterator.__iter__">1124<span class="sig-prename descclassname"><span class="pre">iterator.</span></span><span class="sig-name descname"><span class="pre">__iter__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#iterator.__iter__" title="Link to this definition">¶</a></dt>1125<dd><p>Return the <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> object itself. This is required to allow both1126containers and iterators to be used with the <a class="reference internal" href="../reference/compound_stmts.html#for"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">for</span></code></a> and1127<a class="reference internal" href="../reference/expressions.html#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a> statements. This method corresponds to the1128<a class="reference internal" href="../c-api/typeobj.html#c.PyTypeObject.tp_iter" title="PyTypeObject.tp_iter"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_iter</span></code></a> slot of the type structure for Python1129objects in the Python/C API.</p>1130</dd></dl>1131 1132<dl class="py method">1133<dt class="sig sig-object py" id="iterator.__next__">1134<span class="sig-prename descclassname"><span class="pre">iterator.</span></span><span class="sig-name descname"><span class="pre">__next__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#iterator.__next__" title="Link to this definition">¶</a></dt>1135<dd><p>Return the next item from the <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a>. If there are no further1136items, raise the <a class="reference internal" href="exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> exception. This method corresponds to1137the <a class="reference internal" href="../c-api/typeobj.html#c.PyTypeObject.tp_iternext" title="PyTypeObject.tp_iternext"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_iternext</span></code></a> slot of the type structure for1138Python objects in the Python/C API.</p>1139</dd></dl>1140 1141<p>Python defines several iterator objects to support iteration over general and1142specific sequence types, dictionaries, and other more specialized forms. The1143specific types are not important beyond their implementation of the iterator1144protocol.</p>1145<p>Once an iterator’s <a class="reference internal" href="#iterator.__next__" title="iterator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> method raises1146<a class="reference internal" href="exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a>, it must continue to do so on subsequent calls.1147Implementations that do not obey this property are deemed broken.</p>1148<section id="generator-types">1149<span id="id3"></span><h3>Generator Types<a class="headerlink" href="#generator-types" title="Link to this heading">¶</a></h3>1150<p>Python’s <a class="reference internal" href="../glossary.html#term-generator"><span class="xref std std-term">generator</span></a>s provide a convenient way to implement the iterator1151protocol. If a container object’s <a class="reference internal" href="../reference/datamodel.html#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> method is implemented as a1152generator, it will automatically return an iterator object (technically, a1153generator object) supplying the <a class="reference internal" href="#iterator.__iter__" title="iterator.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> and <a class="reference internal" href="../reference/expressions.html#generator.__next__" title="generator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a>1154methods.1155More information about generators can be found in <a class="reference internal" href="../reference/expressions.html#yieldexpr"><span class="std std-ref">the documentation for1156the yield expression</span></a>.</p>1157</section>1158</section>1159<section id="sequence-types-list-tuple-range">1160<span id="typesseq"></span><h2>Sequence Types — <a class="reference internal" href="#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, <a class="reference internal" href="#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>, <a class="reference internal" href="#range" title="range"><code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a><a class="headerlink" href="#sequence-types-list-tuple-range" title="Link to this heading">¶</a></h2>1161<p>There are three basic sequence types: lists, tuples, and range objects.1162Additional sequence types tailored for processing of1163<a class="reference internal" href="#binaryseq"><span class="std std-ref">binary data</span></a> and <a class="reference internal" href="#textseq"><span class="std std-ref">text strings</span></a> are1164described in dedicated sections.</p>1165<section id="common-sequence-operations">1166<span id="typesseq-common"></span><h3>Common Sequence Operations<a class="headerlink" href="#common-sequence-operations" title="Link to this heading">¶</a></h3>1167<p id="index-19">The operations in the following table are supported by most sequence types,1168both mutable and immutable. The <a class="reference internal" href="collections.abc.html#collections.abc.Sequence" title="collections.abc.Sequence"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.abc.Sequence</span></code></a> ABC is1169provided to make it easier to correctly implement these operations on1170custom sequence types.</p>1171<p>This table lists the sequence operations sorted in ascending priority. In the1172table, <em>s</em> and <em>t</em> are sequences of the same type, <em>n</em>, <em>i</em>, <em>j</em> and <em>k</em> are1173integers and <em>x</em> is an arbitrary object that meets any type and value1174restrictions imposed by <em>s</em>.</p>1175<p>The <code class="docutils literal notranslate"><span class="pre">in</span></code> and <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">in</span></code> operations have the same priorities as the1176comparison operations. The <code class="docutils literal notranslate"><span class="pre">+</span></code> (concatenation) and <code class="docutils literal notranslate"><span class="pre">*</span></code> (repetition)1177operations have the same priority as the corresponding numeric operations. <a class="footnote-reference brackets" href="#id14" id="id4" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a></p>1178<table class="docutils align-default" id="index-20">1179<thead>1180<tr class="row-odd"><th class="head"><p>Operation</p></th>1181<th class="head"><p>Result</p></th>1182<th class="head"><p>Notes</p></th>1183</tr>1184</thead>1185<tbody>1186<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">in</span> <span class="pre">s</span></code></p></td>1187<td><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if an item of <em>s</em> is1188equal to <em>x</em>, else <code class="docutils literal notranslate"><span class="pre">False</span></code></p></td>1189<td><p>(1)</p></td>1190</tr>1191<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">s</span></code></p></td>1192<td><p><code class="docutils literal notranslate"><span class="pre">False</span></code> if an item of <em>s</em> is1193equal to <em>x</em>, else <code class="docutils literal notranslate"><span class="pre">True</span></code></p></td>1194<td><p>(1)</p></td>1195</tr>1196<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">s</span> <span class="pre">+</span> <span class="pre">t</span></code></p></td>1197<td><p>the concatenation of <em>s</em> and1198<em>t</em></p></td>1199<td><p>(6)(7)</p></td>1200</tr>