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="numbers — Numeric abstract base classes" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/numbers.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/numbers.py The numbers module ( PEP 3141) defines a hierarchy of numeric abstract base classes which progressively define more operations. None of the types defined in this module ..." />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_numbers_38324719.png" />15<meta property="og:image:alt" content="Source code: Lib/numbers.py The numbers module ( PEP 3141) defines a hierarchy of numeric abstract base classes which progressively define more operations. None of the types defined in this module ..." />16<meta name="description" content="Source code: Lib/numbers.py The numbers module ( PEP 3141) defines a hierarchy of numeric abstract base classes which progressively define more operations. None of the types defined in this module ..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>numbers — Numeric abstract base classes — 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="math — Mathematical functions" href="math.html" />43 <link rel="prev" title="Numeric and Mathematical Modules" href="numeric.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/numbers.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numbers</span></code> — Numeric abstract base classes</a><ul>108<li><a class="reference internal" href="#the-numeric-tower">The numeric tower</a></li>109<li><a class="reference internal" href="#notes-for-type-implementers">Notes for type implementers</a><ul>110<li><a class="reference internal" href="#adding-more-numeric-abcs">Adding More Numeric ABCs</a></li>111<li><a class="reference internal" href="#implementing-the-arithmetic-operations">Implementing the arithmetic operations</a></li>112</ul>113</li>114</ul>115</li>116</ul>117 118 </div>119 <div>120 <h4>Previous topic</h4>121 <p class="topless"><a href="numeric.html"122 title="previous chapter">Numeric and Mathematical Modules</a></p>123 </div>124 <div>125 <h4>Next topic</h4>126 <p class="topless"><a href="math.html"127 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">math</span></code> — Mathematical functions</a></p>128 </div>129 <script>130 document.addEventListener('DOMContentLoaded', () => {131 const title = document.querySelector('meta[property="og:title"]').content;132 const elements = document.querySelectorAll('.improvepage');133 const pageurl = window.location.href.split('?')[0];134 elements.forEach(element => {135 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));136 url.searchParams.set('pagetitle', title);137 url.searchParams.set('pageurl', pageurl);138 url.searchParams.set('pagesource', "library/numbers.rst");139 element.href = url.toString();140 });141 });142 </script>143 <div role="note" aria-label="source link">144 <h3>This page</h3>145 <ul class="this-page-menu">146 <li><a href="../bugs.html">Report a bug</a></li>147 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>148 <li>149 <a href="https://github.com/python/cpython/blob/main/Doc/library/numbers.rst?plain=1"150 rel="nofollow">Show source151 </a>152 </li>153 154 </ul>155 </div>156 </nav>157 </div>158</div>159 160 161 <div class="related" role="navigation" aria-label="Related">162 <h3>Navigation</h3>163 <ul>164 <li class="right" style="margin-right: 10px">165 <a href="../genindex.html" title="General Index"166 accesskey="I">index</a></li>167 <li class="right" >168 <a href="../py-modindex.html" title="Python Module Index"169 >modules</a> |</li>170 <li class="right" >171 <a href="math.html" title="math — Mathematical functions"172 accesskey="N">next</a> |</li>173 <li class="right" >174 <a href="numeric.html" title="Numeric and Mathematical Modules"175 accesskey="P">previous</a> |</li>176 177 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>178 <li><a href="https://www.python.org/">Python</a> »</li>179 <li class="switchers">180 <div class="language_switcher_placeholder"></div>181 <div class="version_switcher_placeholder"></div>182 </li>183 <li>184 185 </li>186 <li id="cpython-language-and-version">187 <a href="../index.html">3.15.0a6 Documentation</a> »188 </li>189 190 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>191 <li class="nav-item nav-item-2"><a href="numeric.html" accesskey="U">Numeric and Mathematical Modules</a> »</li>192 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">numbers</span></code> — Numeric abstract base classes</a></li>193 <li class="right">194 195 196 <div class="inline-search" role="search">197 <form class="inline-search" action="../search.html" method="get">198 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">199 <input type="submit" value="Go">200 </form>201 </div>202 |203 </li>204 <li class="right">205<label class="theme-selector-label">206 Theme207 <select class="theme-selector" oninput="activateTheme(this.value)">208 <option value="auto" selected>Auto</option>209 <option value="light">Light</option>210 <option value="dark">Dark</option>211 </select>212</label> |</li>213 214 </ul>215 </div> 216 217 <div class="document">218 <div class="documentwrapper">219 <div class="bodywrapper">220 <div class="body" role="main">221 222 <section id="module-numbers">223<span id="numbers-numeric-abstract-base-classes"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">numbers</span></code> — Numeric abstract base classes<a class="headerlink" href="#module-numbers" title="Link to this heading">¶</a></h1>224<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/numbers.py">Lib/numbers.py</a></p>225<hr class="docutils" />226<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">numbers</span></code> module (<span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-3141/"><strong>PEP 3141</strong></a>) defines a hierarchy of numeric227<a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base classes</span></a> which progressively define228more operations. None of the types defined in this module are intended to be instantiated.</p>229<dl class="py class">230<dt class="sig sig-object py" id="numbers.Number">231<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">numbers.</span></span><span class="sig-name descname"><span class="pre">Number</span></span><a class="headerlink" href="#numbers.Number" title="Link to this definition">¶</a></dt>232<dd><p>The root of the numeric hierarchy. If you just want to check if an argument233<em>x</em> is a number, without caring what kind, use <code class="docutils literal notranslate"><span class="pre">isinstance(x,</span> <span class="pre">Number)</span></code>.</p>234</dd></dl>235 236<section id="the-numeric-tower">237<h2>The numeric tower<a class="headerlink" href="#the-numeric-tower" title="Link to this heading">¶</a></h2>238<dl class="py class">239<dt class="sig sig-object py" id="numbers.Complex">240<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">numbers.</span></span><span class="sig-name descname"><span class="pre">Complex</span></span><a class="headerlink" href="#numbers.Complex" title="Link to this definition">¶</a></dt>241<dd><p>Subclasses of this type describe complex numbers and include the operations242that work on the built-in <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> type. These are: conversions to243<code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code> and <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="reference internal" href="#numbers.Complex.real" title="numbers.Complex.real"><code class="xref py py-attr docutils literal notranslate"><span class="pre">real</span></code></a>, <a class="reference internal" href="#numbers.Complex.imag" title="numbers.Complex.imag"><code class="xref py py-attr docutils literal notranslate"><span class="pre">imag</span></code></a>, <code class="docutils literal notranslate"><span class="pre">+</span></code>,244<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>, <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>, <a class="reference internal" href="#numbers.Complex.conjugate" title="numbers.Complex.conjugate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">conjugate()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">==</span></code>, and245<code class="docutils literal notranslate"><span class="pre">!=</span></code>. All except <code class="docutils literal notranslate"><span class="pre">-</span></code> and <code class="docutils literal notranslate"><span class="pre">!=</span></code> are abstract.</p>246<dl class="py attribute">247<dt class="sig sig-object py" id="numbers.Complex.real">248<span class="sig-name descname"><span class="pre">real</span></span><a class="headerlink" href="#numbers.Complex.real" title="Link to this definition">¶</a></dt>249<dd><p>Abstract. Retrieves the real component of this number.</p>250</dd></dl>251 252<dl class="py attribute">253<dt class="sig sig-object py" id="numbers.Complex.imag">254<span class="sig-name descname"><span class="pre">imag</span></span><a class="headerlink" href="#numbers.Complex.imag" title="Link to this definition">¶</a></dt>255<dd><p>Abstract. Retrieves the imaginary component of this number.</p>256</dd></dl>257 258<dl class="py method">259<dt class="sig sig-object py" id="numbers.Complex.conjugate">260<em class="property"><span class="k"><span class="pre">abstractmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">conjugate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#numbers.Complex.conjugate" title="Link to this definition">¶</a></dt>261<dd><p>Abstract. Returns the complex conjugate. For example, <code class="docutils literal notranslate"><span class="pre">(1+3j).conjugate()</span>262<span class="pre">==</span> <span class="pre">(1-3j)</span></code>.</p>263</dd></dl>264 265</dd></dl>266 267<dl class="py class">268<dt class="sig sig-object py" id="numbers.Real">269<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">numbers.</span></span><span class="sig-name descname"><span class="pre">Real</span></span><a class="headerlink" href="#numbers.Real" title="Link to this definition">¶</a></dt>270<dd><p>To <a class="reference internal" href="#numbers.Complex" title="numbers.Complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">Complex</span></code></a>, <code class="xref py py-class docutils literal notranslate"><span class="pre">Real</span></code> adds the operations that work on real271numbers.</p>272<p>In short, those are: a conversion to <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="math.html#math.trunc" title="math.trunc"><code class="xref py py-func docutils literal notranslate"><span class="pre">math.trunc()</span></code></a>,273<a class="reference internal" href="functions.html#round" title="round"><code class="xref py py-func docutils literal notranslate"><span class="pre">round()</span></code></a>, <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>, <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>, <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>, <code class="docutils literal notranslate"><span class="pre">//</span></code>,274<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>, and <code class="docutils literal notranslate"><span class="pre">>=</span></code>.</p>275<p>Real also provides defaults for <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>, <a class="reference internal" href="#numbers.Complex.real" title="numbers.Complex.real"><code class="xref py py-attr docutils literal notranslate"><span class="pre">real</span></code></a>,276<a class="reference internal" href="#numbers.Complex.imag" title="numbers.Complex.imag"><code class="xref py py-attr docutils literal notranslate"><span class="pre">imag</span></code></a>, and <a class="reference internal" href="#numbers.Complex.conjugate" title="numbers.Complex.conjugate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">conjugate()</span></code></a>.</p>277</dd></dl>278 279<dl class="py class">280<dt class="sig sig-object py" id="numbers.Rational">281<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">numbers.</span></span><span class="sig-name descname"><span class="pre">Rational</span></span><a class="headerlink" href="#numbers.Rational" title="Link to this definition">¶</a></dt>282<dd><p>Subtypes <a class="reference internal" href="#numbers.Real" title="numbers.Real"><code class="xref py py-class docutils literal notranslate"><span class="pre">Real</span></code></a> and adds <a class="reference internal" href="#numbers.Rational.numerator" title="numbers.Rational.numerator"><code class="xref py py-attr docutils literal notranslate"><span class="pre">numerator</span></code></a> and283<a class="reference internal" href="#numbers.Rational.denominator" title="numbers.Rational.denominator"><code class="xref py py-attr docutils literal notranslate"><span class="pre">denominator</span></code></a> properties. It also provides a default for284<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>285<p>The <a class="reference internal" href="#numbers.Rational.numerator" title="numbers.Rational.numerator"><code class="xref py py-attr docutils literal notranslate"><span class="pre">numerator</span></code></a> and <a class="reference internal" href="#numbers.Rational.denominator" title="numbers.Rational.denominator"><code class="xref py py-attr docutils literal notranslate"><span class="pre">denominator</span></code></a> values286should be instances of <a class="reference internal" href="#numbers.Integral" title="numbers.Integral"><code class="xref py py-class docutils literal notranslate"><span class="pre">Integral</span></code></a> and should be in lowest terms with287<code class="xref py py-attr docutils literal notranslate"><span class="pre">denominator</span></code> positive.</p>288<dl class="py attribute">289<dt class="sig sig-object py" id="numbers.Rational.numerator">290<span class="sig-name descname"><span class="pre">numerator</span></span><a class="headerlink" href="#numbers.Rational.numerator" title="Link to this definition">¶</a></dt>291<dd><p>Abstract. The numerator of this rational number.</p>292</dd></dl>293 294<dl class="py attribute">295<dt class="sig sig-object py" id="numbers.Rational.denominator">296<span class="sig-name descname"><span class="pre">denominator</span></span><a class="headerlink" href="#numbers.Rational.denominator" title="Link to this definition">¶</a></dt>297<dd><p>Abstract. The denominator of this rational number.</p>298</dd></dl>299 300</dd></dl>301 302<dl class="py class">303<dt class="sig sig-object py" id="numbers.Integral">304<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">numbers.</span></span><span class="sig-name descname"><span class="pre">Integral</span></span><a class="headerlink" href="#numbers.Integral" title="Link to this definition">¶</a></dt>305<dd><p>Subtypes <a class="reference internal" href="#numbers.Rational" title="numbers.Rational"><code class="xref py py-class docutils literal notranslate"><span class="pre">Rational</span></code></a> and adds a conversion 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>. Provides306defaults for <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>, <a class="reference internal" href="#numbers.Rational.numerator" title="numbers.Rational.numerator"><code class="xref py py-attr docutils literal notranslate"><span class="pre">numerator</span></code></a>, and307<a class="reference internal" href="#numbers.Rational.denominator" title="numbers.Rational.denominator"><code class="xref py py-attr docutils literal notranslate"><span class="pre">denominator</span></code></a>. Adds abstract methods for <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> with308modulus and bit-string operations: <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">|</span></code>,309<code class="docutils literal notranslate"><span class="pre">~</span></code>.</p>310</dd></dl>311 312</section>313<section id="notes-for-type-implementers">314<h2>Notes for type implementers<a class="headerlink" href="#notes-for-type-implementers" title="Link to this heading">¶</a></h2>315<p>Implementers should be careful to make equal numbers equal and hash316them to the same values. This may be subtle if there are two different317extensions of the real numbers. For example, <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>318implements <a class="reference internal" href="functions.html#hash" title="hash"><code class="xref py py-func docutils literal notranslate"><span class="pre">hash()</span></code></a> as follows:</p>319<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="fm">__hash__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>320 <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">denominator</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>321 <span class="c1"># Get integers right.</span>322 <span class="k">return</span> <span class="nb">hash</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">numerator</span><span class="p">)</span>323 <span class="c1"># Expensive check, but definitely correct.</span>324 <span class="k">if</span> <span class="bp">self</span> <span class="o">==</span> <span class="nb">float</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>325 <span class="k">return</span> <span class="nb">hash</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="bp">self</span><span class="p">))</span>326 <span class="k">else</span><span class="p">:</span>327 <span class="c1"># Use tuple's hash to avoid a high collision rate on</span>328 <span class="c1"># simple fractions.</span>329 <span class="k">return</span> <span class="nb">hash</span><span class="p">((</span><span class="bp">self</span><span class="o">.</span><span class="n">numerator</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">denominator</span><span class="p">))</span>330</pre></div>331</div>332<section id="adding-more-numeric-abcs">333<h3>Adding More Numeric ABCs<a class="headerlink" href="#adding-more-numeric-abcs" title="Link to this heading">¶</a></h3>334<p>There are, of course, more possible ABCs for numbers, and this would335be a poor hierarchy if it precluded the possibility of adding336those. You can add <code class="docutils literal notranslate"><span class="pre">MyFoo</span></code> between <a class="reference internal" href="#numbers.Complex" title="numbers.Complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">Complex</span></code></a> and337<a class="reference internal" href="#numbers.Real" title="numbers.Real"><code class="xref py py-class docutils literal notranslate"><span class="pre">Real</span></code></a> with:</p>338<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">MyFoo</span><span class="p">(</span><span class="n">Complex</span><span class="p">):</span> <span class="o">...</span>339<span class="n">MyFoo</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="n">Real</span><span class="p">)</span>340</pre></div>341</div>342</section>343<section id="implementing-the-arithmetic-operations">344<span id="id1"></span><h3>Implementing the arithmetic operations<a class="headerlink" href="#implementing-the-arithmetic-operations" title="Link to this heading">¶</a></h3>345<p>We want to implement the arithmetic operations so that mixed-mode346operations either call an implementation whose author knew about the347types of both arguments, or convert both to the nearest built in type348and do the operation there. For subtypes of <a class="reference internal" href="#numbers.Integral" title="numbers.Integral"><code class="xref py py-class docutils literal notranslate"><span class="pre">Integral</span></code></a>, this349means that <a class="reference internal" href="../reference/datamodel.html#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a> and <a class="reference internal" href="../reference/datamodel.html#object.__radd__" title="object.__radd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__radd__()</span></code></a> should be350defined as:</p>351<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">MyIntegral</span><span class="p">(</span><span class="n">Integral</span><span class="p">):</span>352 353 <span class="k">def</span><span class="w"> </span><span class="fm">__add__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>354 <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">MyIntegral</span><span class="p">):</span>355 <span class="k">return</span> <span class="n">do_my_adding_stuff</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>356 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">OtherTypeIKnowAbout</span><span class="p">):</span>357 <span class="k">return</span> <span class="n">do_my_other_adding_stuff</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>358 <span class="k">else</span><span class="p">:</span>359 <span class="k">return</span> <span class="bp">NotImplemented</span>360 361 <span class="k">def</span><span class="w"> </span><span class="fm">__radd__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>362 <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">MyIntegral</span><span class="p">):</span>363 <span class="k">return</span> <span class="n">do_my_adding_stuff</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>364 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">OtherTypeIKnowAbout</span><span class="p">):</span>365 <span class="k">return</span> <span class="n">do_my_other_adding_stuff</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>366 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">Integral</span><span class="p">):</span>367 <span class="k">return</span> <span class="nb">int</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="o">+</span> <span class="nb">int</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>368 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">Real</span><span class="p">):</span>369 <span class="k">return</span> <span class="nb">float</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="o">+</span> <span class="nb">float</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>370 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">Complex</span><span class="p">):</span>371 <span class="k">return</span> <span class="nb">complex</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="o">+</span> <span class="nb">complex</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>372 <span class="k">else</span><span class="p">:</span>373 <span class="k">return</span> <span class="bp">NotImplemented</span>374</pre></div>375</div>376<p>There are 5 different cases for a mixed-type operation on subclasses377of <a class="reference internal" href="#numbers.Complex" title="numbers.Complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">Complex</span></code></a>. I’ll refer to all of the above code that doesn’t378refer to <code class="docutils literal notranslate"><span class="pre">MyIntegral</span></code> and <code class="docutils literal notranslate"><span class="pre">OtherTypeIKnowAbout</span></code> as379“boilerplate”. <code class="docutils literal notranslate"><span class="pre">a</span></code> will be an instance of <code class="docutils literal notranslate"><span class="pre">A</span></code>, which is a subtype380of <code class="xref py py-class docutils literal notranslate"><span class="pre">Complex</span></code> (<code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">:</span> <span class="pre">A</span> <span class="pre"><:</span> <span class="pre">Complex</span></code>), and <code class="docutils literal notranslate"><span class="pre">b</span> <span class="pre">:</span> <span class="pre">B</span> <span class="pre"><:</span>381<span class="pre">Complex</span></code>. I’ll consider <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">b</span></code>:</p>382<ol class="arabic simple">383<li><p>If <code class="docutils literal notranslate"><span class="pre">A</span></code> defines an <a class="reference internal" href="../reference/datamodel.html#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a> which accepts <code class="docutils literal notranslate"><span class="pre">b</span></code>, all is384well.</p></li>385<li><p>If <code class="docutils literal notranslate"><span class="pre">A</span></code> falls back to the boilerplate code, and it were to386return a value from <a class="reference internal" href="../reference/datamodel.html#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a>, we’d miss the possibility387that <code class="docutils literal notranslate"><span class="pre">B</span></code> defines a more intelligent <a class="reference internal" href="../reference/datamodel.html#object.__radd__" title="object.__radd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__radd__()</span></code></a>, so the388boilerplate should return <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> from389<code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code>. (Or <code class="docutils literal notranslate"><span class="pre">A</span></code> may not implement <code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code> at390all.)</p></li>391<li><p>Then <code class="docutils literal notranslate"><span class="pre">B</span></code>’s <a class="reference internal" href="../reference/datamodel.html#object.__radd__" title="object.__radd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__radd__()</span></code></a> gets a chance. If it accepts392<code class="docutils literal notranslate"><span class="pre">a</span></code>, all is well.</p></li>393<li><p>If it falls back to the boilerplate, there are no more possible394methods to try, so this is where the default implementation395should live.</p></li>396<li><p>If <code class="docutils literal notranslate"><span class="pre">B</span> <span class="pre"><:</span> <span class="pre">A</span></code>, Python tries <code class="docutils literal notranslate"><span class="pre">B.__radd__</span></code> before397<code class="docutils literal notranslate"><span class="pre">A.__add__</span></code>. This is ok, because it was implemented with398knowledge of <code class="docutils literal notranslate"><span class="pre">A</span></code>, so it can handle those instances before399delegating to <a class="reference internal" href="#numbers.Complex" title="numbers.Complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">Complex</span></code></a>.</p></li>400</ol>401<p>If <code class="docutils literal notranslate"><span class="pre">A</span> <span class="pre"><:</span> <span class="pre">Complex</span></code> and <code class="docutils literal notranslate"><span class="pre">B</span> <span class="pre"><:</span> <span class="pre">Real</span></code> without sharing any other knowledge,402then the appropriate shared operation is the one involving the built403in <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>, and both <a class="reference internal" href="../reference/datamodel.html#object.__radd__" title="object.__radd__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__radd__()</span></code></a> s land there, so <code class="docutils literal notranslate"><span class="pre">a+b</span>404<span class="pre">==</span> <span class="pre">b+a</span></code>.</p>405<p>Because most of the operations on any given type will be very similar,406it can be useful to define a helper function which generates the407forward and reverse instances of any given operator. For example,408<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> uses:</p>409<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">_operator_fallbacks</span><span class="p">(</span><span class="n">monomorphic_operator</span><span class="p">,</span> <span class="n">fallback_operator</span><span class="p">):</span>410 <span class="k">def</span><span class="w"> </span><span class="nf">forward</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>411 <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">Fraction</span><span class="p">)):</span>412 <span class="k">return</span> <span class="n">monomorphic_operator</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>413 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="nb">float</span><span class="p">):</span>414 <span class="k">return</span> <span class="n">fallback_operator</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="n">b</span><span class="p">)</span>415 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="nb">complex</span><span class="p">):</span>416 <span class="k">return</span> <span class="n">fallback_operator</span><span class="p">(</span><span class="nb">complex</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="n">b</span><span class="p">)</span>417 <span class="k">else</span><span class="p">:</span>418 <span class="k">return</span> <span class="bp">NotImplemented</span>419 <span class="n">forward</span><span class="o">.</span><span class="vm">__name__</span> <span class="o">=</span> <span class="s1">'__'</span> <span class="o">+</span> <span class="n">fallback_operator</span><span class="o">.</span><span class="vm">__name__</span> <span class="o">+</span> <span class="s1">'__'</span>420 <span class="n">forward</span><span class="o">.</span><span class="vm">__doc__</span> <span class="o">=</span> <span class="n">monomorphic_operator</span><span class="o">.</span><span class="vm">__doc__</span>421 422 <span class="k">def</span><span class="w"> </span><span class="nf">reverse</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="p">):</span>423 <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">Rational</span><span class="p">):</span>424 <span class="c1"># Includes ints.</span>425 <span class="k">return</span> <span class="n">monomorphic_operator</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>426 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">Real</span><span class="p">):</span>427 <span class="k">return</span> <span class="n">fallback_operator</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="nb">float</span><span class="p">(</span><span class="n">b</span><span class="p">))</span>428 <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">Complex</span><span class="p">):</span>429 <span class="k">return</span> <span class="n">fallback_operator</span><span class="p">(</span><span class="nb">complex</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="nb">complex</span><span class="p">(</span><span class="n">b</span><span class="p">))</span>430 <span class="k">else</span><span class="p">:</span>431 <span class="k">return</span> <span class="bp">NotImplemented</span>432 <span class="n">reverse</span><span class="o">.</span><span class="vm">__name__</span> <span class="o">=</span> <span class="s1">'__r'</span> <span class="o">+</span> <span class="n">fallback_operator</span><span class="o">.</span><span class="vm">__name__</span> <span class="o">+</span> <span class="s1">'__'</span>433 <span class="n">reverse</span><span class="o">.</span><span class="vm">__doc__</span> <span class="o">=</span> <span class="n">monomorphic_operator</span><span class="o">.</span><span class="vm">__doc__</span>434 435 <span class="k">return</span> <span class="n">forward</span><span class="p">,</span> <span class="n">reverse</span>436 437<span class="k">def</span><span class="w"> </span><span class="nf">_add</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>438<span class="w"> </span><span class="sd">"""a + b"""</span>439 <span class="k">return</span> <span class="n">Fraction</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">numerator</span> <span class="o">*</span> <span class="n">b</span><span class="o">.</span><span class="n">denominator</span> <span class="o">+</span>440 <span class="n">b</span><span class="o">.</span><span class="n">numerator</span> <span class="o">*</span> <span class="n">a</span><span class="o">.</span><span class="n">denominator</span><span class="p">,</span>441 <span class="n">a</span><span class="o">.</span><span class="n">denominator</span> <span class="o">*</span> <span class="n">b</span><span class="o">.</span><span class="n">denominator</span><span class="p">)</span>442 443<span class="fm">__add__</span><span class="p">,</span> <span class="fm">__radd__</span> <span class="o">=</span> <span class="n">_operator_fallbacks</span><span class="p">(</span><span class="n">_add</span><span class="p">,</span> <span class="n">operator</span><span class="o">.</span><span class="n">add</span><span class="p">)</span>444 445<span class="c1"># ...</span>446</pre></div>447</div>448</section>449</section>450</section>451 452 453 <div class="clearer"></div>454 </div>455 </div>456 </div>457 <div class="sphinxsidebar" role="navigation" aria-label="Main">458 <div class="sphinxsidebarwrapper">459 <div>460 <h3><a href="../contents.html">Table of Contents</a></h3>461 <ul>462<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numbers</span></code> — Numeric abstract base classes</a><ul>463<li><a class="reference internal" href="#the-numeric-tower">The numeric tower</a></li>464<li><a class="reference internal" href="#notes-for-type-implementers">Notes for type implementers</a><ul>465<li><a class="reference internal" href="#adding-more-numeric-abcs">Adding More Numeric ABCs</a></li>466<li><a class="reference internal" href="#implementing-the-arithmetic-operations">Implementing the arithmetic operations</a></li>467</ul>468</li>469</ul>470</li>471</ul>472 473 </div>474 <div>475 <h4>Previous topic</h4>476 <p class="topless"><a href="numeric.html"477 title="previous chapter">Numeric and Mathematical Modules</a></p>478 </div>479 <div>480 <h4>Next topic</h4>481 <p class="topless"><a href="math.html"482 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">math</span></code> — Mathematical functions</a></p>483 </div>484 <script>485 document.addEventListener('DOMContentLoaded', () => {486 const title = document.querySelector('meta[property="og:title"]').content;487 const elements = document.querySelectorAll('.improvepage');488 const pageurl = window.location.href.split('?')[0];489 elements.forEach(element => {490 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));491 url.searchParams.set('pagetitle', title);492 url.searchParams.set('pageurl', pageurl);493 url.searchParams.set('pagesource', "library/numbers.rst");494 element.href = url.toString();495 });496 });497 </script>498 <div role="note" aria-label="source link">499 <h3>This page</h3>500 <ul class="this-page-menu">501 <li><a href="../bugs.html">Report a bug</a></li>502 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>503 <li>504 <a href="https://github.com/python/cpython/blob/main/Doc/library/numbers.rst?plain=1"505 rel="nofollow">Show source506 </a>507 </li>508 509 </ul>510 </div>511 </div>512<div id="sidebarbutton" title="Collapse sidebar">513<span>«</span>514</div>515 516 </div>517 <div class="clearer"></div>518 </div> 519 <div class="related" role="navigation" aria-label="Related">520 <h3>Navigation</h3>521 <ul>522 <li class="right" style="margin-right: 10px">523 <a href="../genindex.html" title="General Index"524 >index</a></li>525 <li class="right" >526 <a href="../py-modindex.html" title="Python Module Index"527 >modules</a> |</li>528 <li class="right" >529 <a href="math.html" title="math — Mathematical functions"530 >next</a> |</li>531 <li class="right" >532 <a href="numeric.html" title="Numeric and Mathematical Modules"533 >previous</a> |</li>534 535 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>536 <li><a href="https://www.python.org/">Python</a> »</li>537 <li class="switchers">538 <div class="language_switcher_placeholder"></div>539 <div class="version_switcher_placeholder"></div>540 </li>541 <li>542 543 </li>544 <li id="cpython-language-and-version">545 <a href="../index.html">3.15.0a6 Documentation</a> »546 </li>547 548 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>549 <li class="nav-item nav-item-2"><a href="numeric.html" >Numeric and Mathematical Modules</a> »</li>550 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">numbers</span></code> — Numeric abstract base classes</a></li>551 <li class="right">552 553 554 <div class="inline-search" role="search">555 <form class="inline-search" action="../search.html" method="get">556 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">557 <input type="submit" value="Go">558 </form>559 </div>560 |561 </li>562 <li class="right">563<label class="theme-selector-label">564 Theme565 <select class="theme-selector" oninput="activateTheme(this.value)">566 <option value="auto" selected>Auto</option>567 <option value="light">Light</option>568 <option value="dark">Dark</option>569 </select>570</label> |</li>571 572 </ul>573 </div> 574 <div class="footer">575 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.576 <br>577 This page is licensed under the Python Software Foundation License Version 2.578 <br>579 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.580 <br>581 582 See <a href="/license.html">History and License</a> for more information.<br>583 584 585 <br>586 587 The Python Software Foundation is a non-profit corporation.588<a href="https://www.python.org/psf/donations/">Please donate.</a>589<br>590 <br>591 Last updated on Mar 10, 2026 (08:58 UTC).592 593 <a href="/bugs.html">Found a bug</a>?594 595 <br>596 597 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.598 </div>599 600 </body>601</html>