Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
decimal.html2866 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="decimal — Decimal fixed-point and floating-point arithmetic" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/decimal.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/decimal.py The decimal module provides support for fast correctly rounded decimal floating-point arithmetic. It offers several advantages over the float datatype: Decimal “is based..." />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_decimal_09c25e75.png" />15<meta property="og:image:alt" content="Source code: Lib/decimal.py The decimal module provides support for fast correctly rounded decimal floating-point arithmetic. It offers several advantages over the float datatype: Decimal “is based..." />16<meta name="description" content="Source code: Lib/decimal.py The decimal module provides support for fast correctly rounded decimal floating-point arithmetic. It offers several advantages over the float datatype: Decimal “is based..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>decimal — Decimal fixed-point and floating-point arithmetic &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="fractions — Rational numbers" href="fractions.html" />43    <link rel="prev" title="cmath — Mathematical functions for complex numbers" href="cmath.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/decimal.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">decimal</span></code> — Decimal fixed-point and floating-point arithmetic</a><ul>108<li><a class="reference internal" href="#quick-start-tutorial">Quick-start tutorial</a></li>109<li><a class="reference internal" href="#decimal-objects">Decimal objects</a><ul>110<li><a class="reference internal" href="#logical-operands">Logical operands</a></li>111</ul>112</li>113<li><a class="reference internal" href="#context-objects">Context objects</a></li>114<li><a class="reference internal" href="#constants">Constants</a></li>115<li><a class="reference internal" href="#rounding-modes">Rounding modes</a></li>116<li><a class="reference internal" href="#signals">Signals</a></li>117<li><a class="reference internal" href="#floating-point-notes">Floating-point notes</a><ul>118<li><a class="reference internal" href="#mitigating-round-off-error-with-increased-precision">Mitigating round-off error with increased precision</a></li>119<li><a class="reference internal" href="#special-values">Special values</a></li>120</ul>121</li>122<li><a class="reference internal" href="#working-with-threads">Working with threads</a></li>123<li><a class="reference internal" href="#recipes">Recipes</a></li>124<li><a class="reference internal" href="#decimal-faq">Decimal FAQ</a></li>125</ul>126</li>127</ul>128 129  </div>130  <div>131    <h4>Previous topic</h4>132    <p class="topless"><a href="cmath.html"133                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cmath</span></code> — Mathematical functions for complex numbers</a></p>134  </div>135  <div>136    <h4>Next topic</h4>137    <p class="topless"><a href="fractions.html"138                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">fractions</span></code> — Rational numbers</a></p>139  </div>140  <script>141    document.addEventListener('DOMContentLoaded', () => {142        const title = document.querySelector('meta[property="og:title"]').content;143        const elements = document.querySelectorAll('.improvepage');144        const pageurl = window.location.href.split('?')[0];145        elements.forEach(element => {146            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));147            url.searchParams.set('pagetitle', title);148            url.searchParams.set('pageurl', pageurl);149            url.searchParams.set('pagesource', "library/decimal.rst");150            element.href = url.toString();151        });152    });153  </script>154  <div role="note" aria-label="source link">155    <h3>This page</h3>156    <ul class="this-page-menu">157      <li><a href="../bugs.html">Report a bug</a></li>158      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>159      <li>160        <a href="https://github.com/python/cpython/blob/main/Doc/library/decimal.rst?plain=1"161            rel="nofollow">Show source162        </a>163      </li>164      165    </ul>166  </div>167        </nav>168    </div>169</div>170 171  172    <div class="related" role="navigation" aria-label="Related">173      <h3>Navigation</h3>174      <ul>175        <li class="right" style="margin-right: 10px">176          <a href="../genindex.html" title="General Index"177             accesskey="I">index</a></li>178        <li class="right" >179          <a href="../py-modindex.html" title="Python Module Index"180             >modules</a> |</li>181        <li class="right" >182          <a href="fractions.html" title="fractions — Rational numbers"183             accesskey="N">next</a> |</li>184        <li class="right" >185          <a href="cmath.html" title="cmath — Mathematical functions for complex numbers"186             accesskey="P">previous</a> |</li>187 188          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>189          <li><a href="https://www.python.org/">Python</a> &#187;</li>190          <li class="switchers">191            <div class="language_switcher_placeholder"></div>192            <div class="version_switcher_placeholder"></div>193          </li>194          <li>195              196          </li>197    <li id="cpython-language-and-version">198      <a href="../index.html">3.15.0a6 Documentation</a> &#187;199    </li>200 201          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>202          <li class="nav-item nav-item-2"><a href="numeric.html" accesskey="U">Numeric and Mathematical Modules</a> &#187;</li>203        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code> — Decimal fixed-point and floating-point arithmetic</a></li>204                <li class="right">205                    206 207    <div class="inline-search" role="search">208        <form class="inline-search" action="../search.html" method="get">209          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">210          <input type="submit" value="Go">211        </form>212    </div>213                     |214                </li>215            <li class="right">216<label class="theme-selector-label">217    Theme218    <select class="theme-selector" oninput="activateTheme(this.value)">219        <option value="auto" selected>Auto</option>220        <option value="light">Light</option>221        <option value="dark">Dark</option>222    </select>223</label> |</li>224            225      </ul>226    </div>    227 228    <div class="document">229      <div class="documentwrapper">230        <div class="bodywrapper">231          <div class="body" role="main">232            233  <section id="module-decimal">234<span id="decimal-decimal-fixed-point-and-floating-point-arithmetic"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code> — Decimal fixed-point and floating-point arithmetic<a class="headerlink" href="#module-decimal" title="Link to this heading">¶</a></h1>235<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/decimal.py">Lib/decimal.py</a></p>236<hr class="docutils" />237<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code> module provides support for fast correctly rounded238decimal floating-point arithmetic. It offers several advantages over the239<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> datatype:</p>240<ul>241<li><p>Decimal “is based on a <a class="reference external" href="https://speleotrove.com/decimal/damodel.html#refnumber">floating-point model</a> which was designed242with people in mind, and necessarily has a paramount guiding principle –243computers must provide an arithmetic that works in the same way as the244arithmetic that people learn at school.” – excerpt from the decimal245arithmetic specification.</p></li>246<li><p>Decimal numbers can be represented exactly.  In contrast, numbers like247<code class="docutils literal notranslate"><span class="pre">1.1</span></code> and <code class="docutils literal notranslate"><span class="pre">2.2</span></code> do not have exact representations in binary248floating point. End users typically would not expect <code class="docutils literal notranslate"><span class="pre">1.1</span> <span class="pre">+</span> <span class="pre">2.2</span></code> to display249as <code class="docutils literal notranslate"><span class="pre">3.3000000000000003</span></code> as it does with binary floating point.</p></li>250<li><p>The exactness carries over into arithmetic.  In decimal floating point, <code class="docutils literal notranslate"><span class="pre">0.1</span>251<span class="pre">+</span> <span class="pre">0.1</span> <span class="pre">+</span> <span class="pre">0.1</span> <span class="pre">-</span> <span class="pre">0.3</span></code> is exactly equal to zero.  In binary floating point, the result252is <code class="docutils literal notranslate"><span class="pre">5.5511151231257827e-017</span></code>.  While near to zero, the differences253prevent reliable equality testing and differences can accumulate. For this254reason, decimal is preferred in accounting applications which have strict255equality invariants.</p></li>256<li><p>The decimal module incorporates a notion of significant places so that <code class="docutils literal notranslate"><span class="pre">1.30</span>257<span class="pre">+</span> <span class="pre">1.20</span></code> is <code class="docutils literal notranslate"><span class="pre">2.50</span></code>.  The trailing zero is kept to indicate significance.258This is the customary presentation for monetary applications. For259multiplication, the “schoolbook” approach uses all the figures in the260multiplicands.  For instance, <code class="docutils literal notranslate"><span class="pre">1.3</span> <span class="pre">*</span> <span class="pre">1.2</span></code> gives <code class="docutils literal notranslate"><span class="pre">1.56</span></code> while <code class="docutils literal notranslate"><span class="pre">1.30</span> <span class="pre">*</span>261<span class="pre">1.20</span></code> gives <code class="docutils literal notranslate"><span class="pre">1.5600</span></code>.</p></li>262<li><p>Unlike hardware based binary floating point, the decimal module has a user263alterable precision (defaulting to 28 places) which can be as large as needed for264a given problem:</p>265<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">decimal</span><span class="w"> </span><span class="kn">import</span> <span class="o">*</span>266<span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">6</span>267<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>268<span class="go">Decimal(&#39;0.142857&#39;)</span>269<span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">28</span>270<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>271<span class="go">Decimal(&#39;0.1428571428571428571428571429&#39;)</span>272</pre></div>273</div>274</li>275<li><p>Both binary and decimal floating point are implemented in terms of published276standards.  While the built-in float type exposes only a modest portion of its277capabilities, the decimal module exposes all required parts of the standard.278When needed, the programmer has full control over rounding and signal handling.279This includes an option to enforce exact arithmetic by using exceptions280to block any inexact operations.</p></li>281<li><p>The decimal module was designed to support “without prejudice, both exact282unrounded decimal arithmetic (sometimes called fixed-point arithmetic)283and rounded floating-point arithmetic.”  – excerpt from the decimal284arithmetic specification.</p></li>285</ul>286<p>The module design is centered around three concepts:  the decimal number, the287context for arithmetic, and signals.</p>288<p>A decimal number is immutable.  It has a sign, coefficient digits, and an289exponent.  To preserve significance, the coefficient digits do not truncate290trailing zeros.  Decimals also include special values such as291<code class="docutils literal notranslate"><span class="pre">Infinity</span></code>, <code class="docutils literal notranslate"><span class="pre">-Infinity</span></code>, and <code class="docutils literal notranslate"><span class="pre">NaN</span></code>.  The standard also292differentiates <code class="docutils literal notranslate"><span class="pre">-0</span></code> from <code class="docutils literal notranslate"><span class="pre">+0</span></code>.</p>293<p>The context for arithmetic is an environment specifying precision, rounding294rules, limits on exponents, flags indicating the results of operations, and trap295enablers which determine whether signals are treated as exceptions.  Rounding296options include <a class="reference internal" href="#decimal.ROUND_CEILING" title="decimal.ROUND_CEILING"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_CEILING</span></code></a>, <a class="reference internal" href="#decimal.ROUND_DOWN" title="decimal.ROUND_DOWN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_DOWN</span></code></a>,297<a class="reference internal" href="#decimal.ROUND_FLOOR" title="decimal.ROUND_FLOOR"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_FLOOR</span></code></a>, <a class="reference internal" href="#decimal.ROUND_HALF_DOWN" title="decimal.ROUND_HALF_DOWN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_DOWN</span></code></a>, <a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a>,298<a class="reference internal" href="#decimal.ROUND_HALF_UP" title="decimal.ROUND_HALF_UP"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_UP</span></code></a>, <a class="reference internal" href="#decimal.ROUND_UP" title="decimal.ROUND_UP"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_UP</span></code></a>, and <a class="reference internal" href="#decimal.ROUND_05UP" title="decimal.ROUND_05UP"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_05UP</span></code></a>.</p>299<p>Signals are groups of exceptional conditions arising during the course of300computation.  Depending on the needs of the application, signals may be ignored,301considered as informational, or treated as exceptions. The signals in the302decimal module are: <a class="reference internal" href="#decimal.Clamped" title="decimal.Clamped"><code class="xref py py-const docutils literal notranslate"><span class="pre">Clamped</span></code></a>, <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a>,303<a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-const docutils literal notranslate"><span class="pre">DivisionByZero</span></code></a>, <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a>, <a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal notranslate"><span class="pre">Rounded</span></code></a>, <a class="reference internal" href="#decimal.Subnormal" title="decimal.Subnormal"><code class="xref py py-const docutils literal notranslate"><span class="pre">Subnormal</span></code></a>,304<a class="reference internal" href="#decimal.Overflow" title="decimal.Overflow"><code class="xref py py-const docutils literal notranslate"><span class="pre">Overflow</span></code></a>, <a class="reference internal" href="#decimal.Underflow" title="decimal.Underflow"><code class="xref py py-const docutils literal notranslate"><span class="pre">Underflow</span></code></a> and <a class="reference internal" href="#decimal.FloatOperation" title="decimal.FloatOperation"><code class="xref py py-const docutils literal notranslate"><span class="pre">FloatOperation</span></code></a>.</p>305<p>For each signal there is a flag and a trap enabler.  When a signal is306encountered, its flag is set to one, then, if the trap enabler is307set to one, an exception is raised.  Flags are sticky, so the user needs to308reset them before monitoring a calculation.</p>309<div class="admonition seealso">310<p class="admonition-title">See also</p>311<ul class="simple">312<li><p>IBM’s General Decimal Arithmetic Specification, <a class="reference external" href="https://speleotrove.com/decimal/decarith.html">The General Decimal Arithmetic313Specification</a>.</p></li>314</ul>315</div>316<section id="quick-start-tutorial">317<span id="decimal-tutorial"></span><h2>Quick-start tutorial<a class="headerlink" href="#quick-start-tutorial" title="Link to this heading">¶</a></h2>318<p>The usual start to using decimals is importing the module, viewing the current319context with <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a> and, if necessary, setting new values for320precision, rounding, or enabled traps:</p>321<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">decimal</span><span class="w"> </span><span class="kn">import</span> <span class="o">*</span>322<span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span>323<span class="go">Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,</span>324<span class="go">        capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,</span>325<span class="go">        InvalidOperation])</span>326 327<span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">7</span>       <span class="c1"># Set a new precision</span>328</pre></div>329</div>330<p>Decimal instances can be constructed from integers, strings, floats, or tuples.331Construction from an integer or a float performs an exact conversion of the332value of that integer or float.  Decimal numbers include special values such as333<code class="docutils literal notranslate"><span class="pre">NaN</span></code> which stands for “Not a number”, positive and negative334<code class="docutils literal notranslate"><span class="pre">Infinity</span></code>, and <code class="docutils literal notranslate"><span class="pre">-0</span></code>:</p>335<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">28</span>336<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>337<span class="go">Decimal(&#39;10&#39;)</span>338<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;3.14&#39;</span><span class="p">)</span>339<span class="go">Decimal(&#39;3.14&#39;)</span>340<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mf">3.14</span><span class="p">)</span>341<span class="go">Decimal(&#39;3.140000000000000124344978758017532527446746826171875&#39;)</span>342<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">),</span> <span class="o">-</span><span class="mi">2</span><span class="p">))</span>343<span class="go">Decimal(&#39;3.14&#39;)</span>344<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="mf">2.0</span> <span class="o">**</span> <span class="mf">0.5</span><span class="p">))</span>345<span class="go">Decimal(&#39;1.4142135623730951&#39;)</span>346<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="o">**</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;0.5&#39;</span><span class="p">)</span>347<span class="go">Decimal(&#39;1.414213562373095048801688724&#39;)</span>348<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;NaN&#39;</span><span class="p">)</span>349<span class="go">Decimal(&#39;NaN&#39;)</span>350<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;-Infinity&#39;</span><span class="p">)</span>351<span class="go">Decimal(&#39;-Infinity&#39;)</span>352</pre></div>353</div>354<p>If the <a class="reference internal" href="#decimal.FloatOperation" title="decimal.FloatOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FloatOperation</span></code></a> signal is trapped, accidental mixing of355decimals and floats in constructors or ordering comparisons raises356an exception:</p>357<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">getcontext</span><span class="p">()</span>358<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">traps</span><span class="p">[</span><span class="n">FloatOperation</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>359<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mf">3.14</span><span class="p">)</span>360<span class="gt">Traceback (most recent call last):</span>361  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>362<span class="gr">decimal.FloatOperation</span>: <span class="n">[&lt;class &#39;decimal.FloatOperation&#39;&gt;]</span>363<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;3.5&#39;</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mf">3.7</span>364<span class="gt">Traceback (most recent call last):</span>365  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>366<span class="gr">decimal.FloatOperation</span>: <span class="n">[&lt;class &#39;decimal.FloatOperation&#39;&gt;]</span>367<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;3.5&#39;</span><span class="p">)</span> <span class="o">==</span> <span class="mf">3.5</span>368<span class="go">True</span>369</pre></div>370</div>371<div class="versionadded">372<p><span class="versionmodified added">Added in version 3.3.</span></p>373</div>374<p>The significance of a new Decimal is determined solely by the number of digits375input.  Context precision and rounding only come into play during arithmetic376operations.</p>377<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">6</span>378<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;3.0&#39;</span><span class="p">)</span>379<span class="go">Decimal(&#39;3.0&#39;)</span>380<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;3.1415926535&#39;</span><span class="p">)</span>381<span class="go">Decimal(&#39;3.1415926535&#39;)</span>382<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;3.1415926535&#39;</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;2.7182818285&#39;</span><span class="p">)</span>383<span class="go">Decimal(&#39;5.85987&#39;)</span>384<span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">rounding</span> <span class="o">=</span> <span class="n">ROUND_UP</span>385<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;3.1415926535&#39;</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;2.7182818285&#39;</span><span class="p">)</span>386<span class="go">Decimal(&#39;5.85988&#39;)</span>387</pre></div>388</div>389<p>If the internal limits of the C version are exceeded, constructing390a decimal raises <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-class docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a>:</p>391<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s2">&quot;1e9999999999999999999&quot;</span><span class="p">)</span>392<span class="gt">Traceback (most recent call last):</span>393  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>394<span class="gr">decimal.InvalidOperation</span>: <span class="n">[&lt;class &#39;decimal.InvalidOperation&#39;&gt;]</span>395</pre></div>396</div>397<div class="versionchanged">398<p><span class="versionmodified changed">Changed in version 3.3.</span></p>399</div>400<p>Decimals interact well with much of the rest of Python.  Here is a small decimal401floating-point flying circus:</p>402<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">Decimal</span><span class="p">,</span> <span class="s1">&#39;1.34 1.87 3.45 2.35 1.00 0.03 9.25&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">()))</span>403<span class="gp">&gt;&gt;&gt; </span><span class="nb">max</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>404<span class="go">Decimal(&#39;9.25&#39;)</span>405<span class="gp">&gt;&gt;&gt; </span><span class="nb">min</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>406<span class="go">Decimal(&#39;0.03&#39;)</span>407<span class="gp">&gt;&gt;&gt; </span><span class="nb">sorted</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>408<span class="go">[Decimal(&#39;0.03&#39;), Decimal(&#39;1.00&#39;), Decimal(&#39;1.34&#39;), Decimal(&#39;1.87&#39;),</span>409<span class="go"> Decimal(&#39;2.35&#39;), Decimal(&#39;3.45&#39;), Decimal(&#39;9.25&#39;)]</span>410<span class="gp">&gt;&gt;&gt; </span><span class="nb">sum</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>411<span class="go">Decimal(&#39;19.29&#39;)</span>412<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="p">,</span><span class="n">b</span><span class="p">,</span><span class="n">c</span> <span class="o">=</span> <span class="n">data</span><span class="p">[:</span><span class="mi">3</span><span class="p">]</span>413<span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>414<span class="go">&#39;1.34&#39;</span>415<span class="gp">&gt;&gt;&gt; </span><span class="nb">float</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>416<span class="go">1.34</span>417<span class="gp">&gt;&gt;&gt; </span><span class="nb">round</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>418<span class="go">Decimal(&#39;1.3&#39;)</span>419<span class="gp">&gt;&gt;&gt; </span><span class="nb">int</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>420<span class="go">1</span>421<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">*</span> <span class="mi">5</span>422<span class="go">Decimal(&#39;6.70&#39;)</span>423<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">*</span> <span class="n">b</span>424<span class="go">Decimal(&#39;2.5058&#39;)</span>425<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">%</span> <span class="n">a</span>426<span class="go">Decimal(&#39;0.77&#39;)</span>427</pre></div>428</div>429<p>Decimals can be formatted (with <a class="reference internal" href="functions.html#format" title="format"><code class="xref py py-func docutils literal notranslate"><span class="pre">format()</span></code></a> built-in or <a class="reference internal" href="../reference/lexical_analysis.html#f-strings"><span class="std std-ref">f-strings</span></a>) in430fixed-point or scientific notation, using the same formatting syntax (see431<a class="reference internal" href="string.html#formatspec"><span class="std std-ref">Format Specification Mini-Language</span></a>) as builtin <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> type:</p>432<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">format</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;2.675&#39;</span><span class="p">),</span> <span class="s2">&quot;f&quot;</span><span class="p">)</span>433<span class="go">&#39;2.675&#39;</span>434<span class="gp">&gt;&gt;&gt; </span><span class="nb">format</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;2.675&#39;</span><span class="p">),</span> <span class="s2">&quot;.2f&quot;</span><span class="p">)</span>435<span class="go">&#39;2.68&#39;</span>436<span class="gp">&gt;&gt;&gt; </span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;2.675&#39;</span><span class="p">)</span><span class="si">:</span><span class="s2">.2f</span><span class="si">}</span><span class="s2">&quot;</span>437<span class="go">&#39;2.68&#39;</span>438<span class="gp">&gt;&gt;&gt; </span><span class="nb">format</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;2.675&#39;</span><span class="p">),</span> <span class="s2">&quot;.2e&quot;</span><span class="p">)</span>439<span class="go">&#39;2.68e+0&#39;</span>440<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">localcontext</span><span class="p">()</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>441<span class="gp">... </span>    <span class="n">ctx</span><span class="o">.</span><span class="n">rounding</span> <span class="o">=</span> <span class="n">ROUND_DOWN</span>442<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="nb">format</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;2.675&#39;</span><span class="p">),</span> <span class="s2">&quot;.2f&quot;</span><span class="p">))</span>443<span class="gp">...</span>444<span class="go">2.67</span>445</pre></div>446</div>447<p>And some mathematical functions are also available to Decimal:</p>448<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">28</span>449<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="o">.</span><span class="n">sqrt</span><span class="p">()</span>450<span class="go">Decimal(&#39;1.414213562373095048801688724&#39;)</span>451<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">exp</span><span class="p">()</span>452<span class="go">Decimal(&#39;2.718281828459045235360287471&#39;)</span>453<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;10&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">ln</span><span class="p">()</span>454<span class="go">Decimal(&#39;2.302585092994045684017991455&#39;)</span>455<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;10&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">log10</span><span class="p">()</span>456<span class="go">Decimal(&#39;1&#39;)</span>457</pre></div>458</div>459<p>The <a class="reference internal" href="#decimal.Decimal.quantize" title="decimal.Decimal.quantize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">quantize()</span></code></a> method rounds a number to a fixed exponent.  This method is460useful for monetary applications that often round results to a fixed number of461places:</p>462<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;7.325&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;.01&#39;</span><span class="p">),</span> <span class="n">rounding</span><span class="o">=</span><span class="n">ROUND_DOWN</span><span class="p">)</span>463<span class="go">Decimal(&#39;7.32&#39;)</span>464<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;7.325&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;1.&#39;</span><span class="p">),</span> <span class="n">rounding</span><span class="o">=</span><span class="n">ROUND_UP</span><span class="p">)</span>465<span class="go">Decimal(&#39;8&#39;)</span>466</pre></div>467</div>468<p>As shown above, the <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a> function accesses the current context and469allows the settings to be changed.  This approach meets the needs of most470applications.</p>471<p>For more advanced work, it may be useful to create alternate contexts using the472<a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Context()</span></code></a> constructor.  To make an alternate active, use the <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">setcontext()</span></code></a>473function.</p>474<p>In accordance with the standard, the <code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code> module provides two ready to475use standard contexts, <a class="reference internal" href="#decimal.BasicContext" title="decimal.BasicContext"><code class="xref py py-const docutils literal notranslate"><span class="pre">BasicContext</span></code></a> and <a class="reference internal" href="#decimal.ExtendedContext" title="decimal.ExtendedContext"><code class="xref py py-const docutils literal notranslate"><span class="pre">ExtendedContext</span></code></a>. The476former is especially useful for debugging because many of the traps are477enabled:</p>478<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">myothercontext</span> <span class="o">=</span> <span class="n">Context</span><span class="p">(</span><span class="n">prec</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="n">rounding</span><span class="o">=</span><span class="n">ROUND_HALF_DOWN</span><span class="p">)</span>479<span class="gp">&gt;&gt;&gt; </span><span class="n">setcontext</span><span class="p">(</span><span class="n">myothercontext</span><span class="p">)</span>480<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>481<span class="go">Decimal(&#39;0.142857142857142857142857142857142857142857142857142857142857&#39;)</span>482 483<span class="gp">&gt;&gt;&gt; </span><span class="n">ExtendedContext</span>484<span class="go">Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,</span>485<span class="go">        capitals=1, clamp=0, flags=[], traps=[])</span>486<span class="gp">&gt;&gt;&gt; </span><span class="n">setcontext</span><span class="p">(</span><span class="n">ExtendedContext</span><span class="p">)</span>487<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>488<span class="go">Decimal(&#39;0.142857143&#39;)</span>489<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>490<span class="go">Decimal(&#39;Infinity&#39;)</span>491 492<span class="gp">&gt;&gt;&gt; </span><span class="n">setcontext</span><span class="p">(</span><span class="n">BasicContext</span><span class="p">)</span>493<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>494<span class="gt">Traceback (most recent call last):</span>495  File <span class="nb">&quot;&lt;pyshell#143&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">-toplevel-</span>496<span class="w">    </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>497<span class="gr">DivisionByZero</span>: <span class="n">x / 0</span>498</pre></div>499</div>500<p>Contexts also have signal flags for monitoring exceptional conditions501encountered during computations.  The flags remain set until explicitly cleared,502so it is best to clear the flags before each set of monitored computations by503using the <a class="reference internal" href="#decimal.Context.clear_flags" title="decimal.Context.clear_flags"><code class="xref py py-meth docutils literal notranslate"><span class="pre">clear_flags()</span></code></a> method.</p>504<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">setcontext</span><span class="p">(</span><span class="n">ExtendedContext</span><span class="p">)</span>505<span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">clear_flags</span><span class="p">()</span>506<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">355</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">113</span><span class="p">)</span>507<span class="go">Decimal(&#39;3.14159292&#39;)</span>508<span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span>509<span class="go">Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,</span>510<span class="go">        capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])</span>511</pre></div>512</div>513<p>The <em>flags</em> entry shows that the rational approximation to pi was514rounded (digits beyond the context precision were thrown away) and that the515result is inexact (some of the discarded digits were non-zero).</p>516<p>Individual traps are set using the dictionary in the <a class="reference internal" href="#decimal.Context.traps" title="decimal.Context.traps"><code class="xref py py-attr docutils literal notranslate"><span class="pre">traps</span></code></a>517attribute of a context:</p>518<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">setcontext</span><span class="p">(</span><span class="n">ExtendedContext</span><span class="p">)</span>519<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>520<span class="go">Decimal(&#39;Infinity&#39;)</span>521<span class="gp">&gt;&gt;&gt; </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">traps</span><span class="p">[</span><span class="n">DivisionByZero</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>522<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>523<span class="gt">Traceback (most recent call last):</span>524  File <span class="nb">&quot;&lt;pyshell#112&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">-toplevel-</span>525<span class="w">    </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>526<span class="gr">DivisionByZero</span>: <span class="n">x / 0</span>527</pre></div>528</div>529<p>Most programs adjust the current context only once, at the beginning of the530program.  And, in many applications, data is converted to <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> with531a single cast inside a loop.  With context set and decimals created, the bulk of532the program manipulates the data no differently than with other Python numeric533types.</p>534</section>535<section id="decimal-objects">536<span id="decimal-decimal"></span><h2>Decimal objects<a class="headerlink" href="#decimal-objects" title="Link to this heading">¶</a></h2>537<dl class="py class">538<dt class="sig sig-object py" id="decimal.Decimal">539<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">decimal.</span></span><span class="sig-name descname"><span class="pre">Decimal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'0'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal" title="Link to this definition">¶</a></dt>540<dd><p>Construct a new <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> object based from <em>value</em>.</p>541<p><em>value</em> can be an integer, string, tuple, <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 another <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code>542object. If no <em>value</em> is given, returns <code class="docutils literal notranslate"><span class="pre">Decimal('0')</span></code>.  If <em>value</em> is a543string, it should conform to the decimal numeric string syntax after leading544and trailing whitespace characters, as well as underscores throughout, are removed:</p>545<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sign</span>           <span class="p">:</span><span class="o">:=</span>  <span class="s1">&#39;+&#39;</span> <span class="o">|</span> <span class="s1">&#39;-&#39;</span>546<span class="n">digit</span>          <span class="p">:</span><span class="o">:=</span>  <span class="s1">&#39;0&#39;</span> <span class="o">|</span> <span class="s1">&#39;1&#39;</span> <span class="o">|</span> <span class="s1">&#39;2&#39;</span> <span class="o">|</span> <span class="s1">&#39;3&#39;</span> <span class="o">|</span> <span class="s1">&#39;4&#39;</span> <span class="o">|</span> <span class="s1">&#39;5&#39;</span> <span class="o">|</span> <span class="s1">&#39;6&#39;</span> <span class="o">|</span> <span class="s1">&#39;7&#39;</span> <span class="o">|</span> <span class="s1">&#39;8&#39;</span> <span class="o">|</span> <span class="s1">&#39;9&#39;</span>547<span class="n">indicator</span>      <span class="p">:</span><span class="o">:=</span>  <span class="s1">&#39;e&#39;</span> <span class="o">|</span> <span class="s1">&#39;E&#39;</span>548<span class="n">digits</span>         <span class="p">:</span><span class="o">:=</span>  <span class="n">digit</span> <span class="p">[</span><span class="n">digit</span><span class="p">]</span><span class="o">...</span>549<span class="n">decimal</span><span class="o">-</span><span class="n">part</span>   <span class="p">:</span><span class="o">:=</span>  <span class="n">digits</span> <span class="s1">&#39;.&#39;</span> <span class="p">[</span><span class="n">digits</span><span class="p">]</span> <span class="o">|</span> <span class="p">[</span><span class="s1">&#39;.&#39;</span><span class="p">]</span> <span class="n">digits</span>550<span class="n">exponent</span><span class="o">-</span><span class="n">part</span>  <span class="p">:</span><span class="o">:=</span>  <span class="n">indicator</span> <span class="p">[</span><span class="n">sign</span><span class="p">]</span> <span class="n">digits</span>551<span class="n">infinity</span>       <span class="p">:</span><span class="o">:=</span>  <span class="s1">&#39;Infinity&#39;</span> <span class="o">|</span> <span class="s1">&#39;Inf&#39;</span>552<span class="n">nan</span>            <span class="p">:</span><span class="o">:=</span>  <span class="s1">&#39;NaN&#39;</span> <span class="p">[</span><span class="n">digits</span><span class="p">]</span> <span class="o">|</span> <span class="s1">&#39;sNaN&#39;</span> <span class="p">[</span><span class="n">digits</span><span class="p">]</span>553<span class="n">numeric</span><span class="o">-</span><span class="n">value</span>  <span class="p">:</span><span class="o">:=</span>  <span class="n">decimal</span><span class="o">-</span><span class="n">part</span> <span class="p">[</span><span class="n">exponent</span><span class="o">-</span><span class="n">part</span><span class="p">]</span> <span class="o">|</span> <span class="n">infinity</span>554<span class="n">numeric</span><span class="o">-</span><span class="n">string</span> <span class="p">:</span><span class="o">:=</span>  <span class="p">[</span><span class="n">sign</span><span class="p">]</span> <span class="n">numeric</span><span class="o">-</span><span class="n">value</span> <span class="o">|</span> <span class="p">[</span><span class="n">sign</span><span class="p">]</span> <span class="n">nan</span>555</pre></div>556</div>557<p>Other Unicode decimal digits are also permitted where <code class="docutils literal notranslate"><span class="pre">digit</span></code>558appears above.  These include decimal digits from various other559alphabets (for example, Arabic-Indic and Devanāgarī digits) along560with the fullwidth digits <code class="docutils literal notranslate"><span class="pre">'\uff10'</span></code> through <code class="docutils literal notranslate"><span class="pre">'\uff19'</span></code>.561Case is not significant, so, for example, <code class="docutils literal notranslate"><span class="pre">inf</span></code>, <code class="docutils literal notranslate"><span class="pre">Inf</span></code>, <code class="docutils literal notranslate"><span class="pre">INFINITY</span></code>,562and <code class="docutils literal notranslate"><span class="pre">iNfINity</span></code> are all acceptable spellings for positive infinity.</p>563<p>If <em>value</em> is a <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>, it should have three components, a sign564(<code class="docutils literal notranslate"><span class="pre">0</span></code> for positive or <code class="docutils literal notranslate"><span class="pre">1</span></code> for negative), a <code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code> of565digits, and an integer exponent. For example, <code class="docutils literal notranslate"><span class="pre">Decimal((0,</span> <span class="pre">(1,</span> <span class="pre">4,</span> <span class="pre">1,</span> <span class="pre">4),</span> <span class="pre">-3))</span></code>566returns <code class="docutils literal notranslate"><span class="pre">Decimal('1.414')</span></code>.</p>567<p>If <em>value</em> is 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>, the binary floating-point value is losslessly568converted to its exact decimal equivalent.  This conversion can often require56953 or more digits of precision.  For example, <code class="docutils literal notranslate"><span class="pre">Decimal(float('1.1'))</span></code>570converts to571<code class="docutils literal notranslate"><span class="pre">Decimal('1.100000000000000088817841970012523233890533447265625')</span></code>.</p>572<p>The <em>context</em> precision does not affect how many digits are stored. That is573determined exclusively by the number of digits in <em>value</em>. For example,574<code class="docutils literal notranslate"><span class="pre">Decimal('3.00000')</span></code> records all five zeros even if the context precision is575only three.</p>576<p>The purpose of the <em>context</em> argument is determining what to do if <em>value</em> is a577malformed string.  If the context traps <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a>, an exception578is raised; otherwise, the constructor returns a new Decimal with the value of579<code class="docutils literal notranslate"><span class="pre">NaN</span></code>.</p>580<p>Once constructed, <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> objects are immutable.</p>581<div class="versionchanged">582<p><span class="versionmodified changed">Changed in version 3.2: </span>The argument to the constructor is now permitted to be 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>583instance.</p>584</div>585<div class="versionchanged">586<p><span class="versionmodified changed">Changed in version 3.3: </span><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> arguments raise an exception if the <a class="reference internal" href="#decimal.FloatOperation" title="decimal.FloatOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FloatOperation</span></code></a>587trap is set. By default the trap is off.</p>588</div>589<div class="versionchanged">590<p><span class="versionmodified changed">Changed in version 3.6: </span>Underscores are allowed for grouping, as with integral and floating-point591literals in code.</p>592</div>593<p>Decimal floating-point objects share many properties with the other built-in594numeric types such as <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> and <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>.  All of the usual math595operations and special methods apply.  Likewise, decimal objects can be596copied, pickled, printed, used as dictionary keys, used as set elements,597compared, sorted, and coerced to another type (such as <code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code> or598<code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code>).</p>599<p>There are some small differences between arithmetic on Decimal objects and600arithmetic on integers and floats.  When the remainder operator <code class="docutils literal notranslate"><span class="pre">%</span></code> is601applied to Decimal objects, the sign of the result is the sign of the602<em>dividend</em> rather than the sign of the divisor:</p>603<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">4</span>604<span class="go">1</span>605<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="o">-</span><span class="mi">7</span><span class="p">)</span> <span class="o">%</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>606<span class="go">Decimal(&#39;-3&#39;)</span>607</pre></div>608</div>609<p>The integer division operator <code class="docutils literal notranslate"><span class="pre">//</span></code> behaves analogously, returning the610integer part of the true quotient (truncating towards zero) rather than its611floor, so as to preserve the usual identity <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">(x</span> <span class="pre">//</span> <span class="pre">y)</span> <span class="pre">*</span> <span class="pre">y</span> <span class="pre">+</span> <span class="pre">x</span> <span class="pre">%</span> <span class="pre">y</span></code>:</p>612<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="o">-</span><span class="mi">7</span> <span class="o">//</span> <span class="mi">4</span>613<span class="go">-2</span>614<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="o">-</span><span class="mi">7</span><span class="p">)</span> <span class="o">//</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>615<span class="go">Decimal(&#39;-1&#39;)</span>616</pre></div>617</div>618<p>The <code class="docutils literal notranslate"><span class="pre">%</span></code> and <code class="docutils literal notranslate"><span class="pre">//</span></code> operators implement the <code class="docutils literal notranslate"><span class="pre">remainder</span></code> and619<code class="docutils literal notranslate"><span class="pre">divide-integer</span></code> operations (respectively) as described in the620specification.</p>621<p>Decimal objects cannot generally be combined with floats or622instances of <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> in arithmetic operations:623an attempt to add a <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> to 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>, for624example, will raise a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.  However, it is possible to625use Python’s comparison operators to compare a <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code>626instance <code class="docutils literal notranslate"><span class="pre">x</span></code> with another number <code class="docutils literal notranslate"><span class="pre">y</span></code>.  This avoids confusing results627when doing equality comparisons between numbers of different types.</p>628<div class="versionchanged">629<p><span class="versionmodified changed">Changed in version 3.2: </span>Mixed-type comparisons between <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> instances and other630numeric types are now fully supported.</p>631</div>632<p>In addition to the standard numeric properties, decimal floating-point633objects also have a number of specialized methods:</p>634<dl class="py method">635<dt class="sig sig-object py" id="decimal.Decimal.adjusted">636<span class="sig-name descname"><span class="pre">adjusted</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.adjusted" title="Link to this definition">¶</a></dt>637<dd><p>Return the adjusted exponent after shifting out the coefficient’s638rightmost digits until only the lead digit remains:639<code class="docutils literal notranslate"><span class="pre">Decimal('321e+5').adjusted()</span></code> returns seven.  Used for determining the640position of the most significant digit with respect to the decimal point.</p>641</dd></dl>642 643<dl class="py method">644<dt class="sig sig-object py" id="decimal.Decimal.as_integer_ratio">645<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="#decimal.Decimal.as_integer_ratio" title="Link to this definition">¶</a></dt>646<dd><p>Return a pair <code class="docutils literal notranslate"><span class="pre">(n,</span> <span class="pre">d)</span></code> of integers that represent the given647<code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> instance as a fraction, in lowest terms and648with a positive denominator:</p>649<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;-3.14&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">as_integer_ratio</span><span class="p">()</span>650<span class="go">(-157, 50)</span>651</pre></div>652</div>653<p>The conversion is exact.  Raise OverflowError on infinities and ValueError654on NaNs.</p>655</dd></dl>656 657<div class="versionadded">658<p><span class="versionmodified added">Added in version 3.6.</span></p>659</div>660<dl class="py method">661<dt class="sig sig-object py" id="decimal.Decimal.as_tuple">662<span class="sig-name descname"><span class="pre">as_tuple</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.as_tuple" title="Link to this definition">¶</a></dt>663<dd><p>Return a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a> representation of the number:664<code class="docutils literal notranslate"><span class="pre">DecimalTuple(sign,</span> <span class="pre">digits,</span> <span class="pre">exponent)</span></code>.</p>665</dd></dl>666 667<dl class="py method">668<dt class="sig sig-object py" id="decimal.Decimal.canonical">669<span class="sig-name descname"><span class="pre">canonical</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.canonical" title="Link to this definition">¶</a></dt>670<dd><p>Return the canonical encoding of the argument.  Currently, the encoding of671a <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> instance is always canonical, so this operation returns672its argument unchanged.</p>673</dd></dl>674 675<dl class="py method">676<dt class="sig sig-object py" id="decimal.Decimal.compare">677<span class="sig-name descname"><span class="pre">compare</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.compare" title="Link to this definition">¶</a></dt>678<dd><p>Compare the values of two Decimal instances.  <code class="xref py py-meth docutils literal notranslate"><span class="pre">compare()</span></code> returns a679Decimal instance, and if either operand is a NaN then the result is a680NaN:</p>681<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">a</span> <span class="ow">or</span> <span class="n">b</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">NaN</span>  <span class="o">==&gt;</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;NaN&#39;</span><span class="p">)</span>682<span class="n">a</span> <span class="o">&lt;</span> <span class="n">b</span>            <span class="o">==&gt;</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;-1&#39;</span><span class="p">)</span>683<span class="n">a</span> <span class="o">==</span> <span class="n">b</span>           <span class="o">==&gt;</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;0&#39;</span><span class="p">)</span>684<span class="n">a</span> <span class="o">&gt;</span> <span class="n">b</span>            <span class="o">==&gt;</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;1&#39;</span><span class="p">)</span>685</pre></div>686</div>687</dd></dl>688 689<dl class="py method">690<dt class="sig sig-object py" id="decimal.Decimal.compare_signal">691<span class="sig-name descname"><span class="pre">compare_signal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.compare_signal" title="Link to this definition">¶</a></dt>692<dd><p>This operation is identical to the <a class="reference internal" href="#decimal.Decimal.compare" title="decimal.Decimal.compare"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compare()</span></code></a> method, except that all693NaNs signal.  That is, if neither operand is a signaling NaN then any694quiet NaN operand is treated as though it were a signaling NaN.</p>695</dd></dl>696 697<dl class="py method">698<dt class="sig sig-object py" id="decimal.Decimal.compare_total">699<span class="sig-name descname"><span class="pre">compare_total</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.compare_total" title="Link to this definition">¶</a></dt>700<dd><p>Compare two operands using their abstract representation rather than their701numerical value.  Similar to the <a class="reference internal" href="#decimal.Decimal.compare" title="decimal.Decimal.compare"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compare()</span></code></a> method, but the result702gives a total ordering on <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> instances.  Two703<code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> instances with the same numeric value but different704representations compare unequal in this ordering:</p>705<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;12.0&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">compare_total</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;12&#39;</span><span class="p">))</span>706<span class="go">Decimal(&#39;-1&#39;)</span>707</pre></div>708</div>709<p>Quiet and signaling NaNs are also included in the total ordering.  The710result of this function is <code class="docutils literal notranslate"><span class="pre">Decimal('0')</span></code> if both operands have the same711representation, <code class="docutils literal notranslate"><span class="pre">Decimal('-1')</span></code> if the first operand is lower in the712total order than the second, and <code class="docutils literal notranslate"><span class="pre">Decimal('1')</span></code> if the first operand is713higher in the total order than the second operand.  See the specification714for details of the total order.</p>715<p>This operation is unaffected by context and is quiet: no flags are changed716and no rounding is performed.  As an exception, the C version may raise717InvalidOperation if the second operand cannot be converted exactly.</p>718</dd></dl>719 720<dl class="py method">721<dt class="sig sig-object py" id="decimal.Decimal.compare_total_mag">722<span class="sig-name descname"><span class="pre">compare_total_mag</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.compare_total_mag" title="Link to this definition">¶</a></dt>723<dd><p>Compare two operands using their abstract representation rather than their724value as in <a class="reference internal" href="#decimal.Decimal.compare_total" title="decimal.Decimal.compare_total"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compare_total()</span></code></a>, but ignoring the sign of each operand.725<code class="docutils literal notranslate"><span class="pre">x.compare_total_mag(y)</span></code> is equivalent to726<code class="docutils literal notranslate"><span class="pre">x.copy_abs().compare_total(y.copy_abs())</span></code>.</p>727<p>This operation is unaffected by context and is quiet: no flags are changed728and no rounding is performed.  As an exception, the C version may raise729InvalidOperation if the second operand cannot be converted exactly.</p>730</dd></dl>731 732<dl class="py method">733<dt class="sig sig-object py" id="decimal.Decimal.conjugate">734<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="#decimal.Decimal.conjugate" title="Link to this definition">¶</a></dt>735<dd><p>Just returns self, this method is only to comply with the Decimal736Specification.</p>737</dd></dl>738 739<dl class="py method">740<dt class="sig sig-object py" id="decimal.Decimal.copy_abs">741<span class="sig-name descname"><span class="pre">copy_abs</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.copy_abs" title="Link to this definition">¶</a></dt>742<dd><p>Return the absolute value of the argument.  This operation is unaffected743by the context and is quiet: no flags are changed and no rounding is744performed.</p>745</dd></dl>746 747<dl class="py method">748<dt class="sig sig-object py" id="decimal.Decimal.copy_negate">749<span class="sig-name descname"><span class="pre">copy_negate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.copy_negate" title="Link to this definition">¶</a></dt>750<dd><p>Return the negation of the argument.  This operation is unaffected by the751context and is quiet: no flags are changed and no rounding is performed.</p>752</dd></dl>753 754<dl class="py method">755<dt class="sig sig-object py" id="decimal.Decimal.copy_sign">756<span class="sig-name descname"><span class="pre">copy_sign</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.copy_sign" title="Link to this definition">¶</a></dt>757<dd><p>Return a copy of the first operand with the sign set to be the same as the758sign of the second operand.  For example:</p>759<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;2.3&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">copy_sign</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;-1.5&#39;</span><span class="p">))</span>760<span class="go">Decimal(&#39;-2.3&#39;)</span>761</pre></div>762</div>763<p>This operation is unaffected by context and is quiet: no flags are changed764and no rounding is performed.  As an exception, the C version may raise765InvalidOperation if the second operand cannot be converted exactly.</p>766</dd></dl>767 768<dl class="py method">769<dt class="sig sig-object py" id="decimal.Decimal.exp">770<span class="sig-name descname"><span class="pre">exp</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.exp" title="Link to this definition">¶</a></dt>771<dd><p>Return the value of the (natural) exponential function <code class="docutils literal notranslate"><span class="pre">e**x</span></code> at the772given number.  The result is correctly rounded using the773<a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a> rounding mode.</p>774<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">exp</span><span class="p">()</span>775<span class="go">Decimal(&#39;2.718281828459045235360287471&#39;)</span>776<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">321</span><span class="p">)</span><span class="o">.</span><span class="n">exp</span><span class="p">()</span>777<span class="go">Decimal(&#39;2.561702493119680037517373933E+139&#39;)</span>778</pre></div>779</div>780</dd></dl>781 782<dl class="py method">783<dt class="sig sig-object py" id="decimal.Decimal.from_float">784<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_float</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.from_float" title="Link to this definition">¶</a></dt>785<dd><p>Alternative constructor that only accepts instances of <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> or786<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>.</p>787<p>Note <code class="docutils literal notranslate"><span class="pre">Decimal.from_float(0.1)</span></code> is not the same as <code class="docutils literal notranslate"><span class="pre">Decimal('0.1')</span></code>.788Since 0.1 is not exactly representable in binary floating point, the789value is stored as the nearest representable value which is790<code class="docutils literal notranslate"><span class="pre">0x1.999999999999ap-4</span></code>.  That equivalent value in decimal is791<code class="docutils literal notranslate"><span class="pre">0.1000000000000000055511151231257827021181583404541015625</span></code>.</p>792<div class="admonition note">793<p class="admonition-title">Note</p>794<p>From Python 3.2 onwards, a <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> instance795can also be constructed directly from 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>.</p>796</div>797<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_float</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>798<span class="go">Decimal(&#39;0.1000000000000000055511151231257827021181583404541015625&#39;)</span>799<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_float</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="s1">&#39;nan&#39;</span><span class="p">))</span>800<span class="go">Decimal(&#39;NaN&#39;)</span>801<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_float</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="s1">&#39;inf&#39;</span><span class="p">))</span>802<span class="go">Decimal(&#39;Infinity&#39;)</span>803<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_float</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="s1">&#39;-inf&#39;</span><span class="p">))</span>804<span class="go">Decimal(&#39;-Infinity&#39;)</span>805</pre></div>806</div>807<div class="versionadded">808<p><span class="versionmodified added">Added in version 3.1.</span></p>809</div>810</dd></dl>811 812<dl class="py method">813<dt class="sig sig-object py" id="decimal.Decimal.from_number">814<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><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">number</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.from_number" title="Link to this definition">¶</a></dt>815<dd><p>Alternative constructor that only accepts instances of816<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#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> or <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code>, but not strings817or tuples.</p>818<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_number</span><span class="p">(</span><span class="mi">314</span><span class="p">)</span>819<span class="go">Decimal(&#39;314&#39;)</span>820<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_number</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>821<span class="go">Decimal(&#39;0.1000000000000000055511151231257827021181583404541015625&#39;)</span>822<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_number</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;3.14&#39;</span><span class="p">))</span>823<span class="go">Decimal(&#39;3.14&#39;)</span>824</pre></div>825</div>826<div class="versionadded">827<p><span class="versionmodified added">Added in version 3.14.</span></p>828</div>829</dd></dl>830 831<dl class="py method">832<dt class="sig sig-object py" id="decimal.Decimal.fma">833<span class="sig-name descname"><span class="pre">fma</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">third</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.fma" title="Link to this definition">¶</a></dt>834<dd><p>Fused multiply-add.  Return self*other+third with no rounding of the835intermediate product self*other.</p>836<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="o">.</span><span class="n">fma</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>837<span class="go">Decimal(&#39;11&#39;)</span>838</pre></div>839</div>840</dd></dl>841 842<dl class="py method">843<dt class="sig sig-object py" id="decimal.Decimal.is_canonical">844<span class="sig-name descname"><span class="pre">is_canonical</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_canonical" title="Link to this definition">¶</a></dt>845<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is canonical and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>846otherwise.  Currently, a <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> instance is always canonical, so847this operation always returns <code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code>.</p>848</dd></dl>849 850<dl class="py method">851<dt class="sig sig-object py" id="decimal.Decimal.is_finite">852<span class="sig-name descname"><span class="pre">is_finite</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_finite" title="Link to this definition">¶</a></dt>853<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a finite number, and854<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> if the argument is an infinity or a NaN.</p>855</dd></dl>856 857<dl class="py method">858<dt class="sig sig-object py" id="decimal.Decimal.is_infinite">859<span class="sig-name descname"><span class="pre">is_infinite</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_infinite" title="Link to this definition">¶</a></dt>860<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is either positive or negative861infinity and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.</p>862</dd></dl>863 864<dl class="py method">865<dt class="sig sig-object py" id="decimal.Decimal.is_nan">866<span class="sig-name descname"><span class="pre">is_nan</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_nan" title="Link to this definition">¶</a></dt>867<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a (quiet or signaling) NaN and868<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.</p>869</dd></dl>870 871<dl class="py method">872<dt class="sig sig-object py" id="decimal.Decimal.is_normal">873<span class="sig-name descname"><span class="pre">is_normal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_normal" title="Link to this definition">¶</a></dt>874<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a <em>normal</em> finite number.  Return875<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> if the argument is zero, subnormal, infinite or a NaN.</p>876</dd></dl>877 878<dl class="py method">879<dt class="sig sig-object py" id="decimal.Decimal.is_qnan">880<span class="sig-name descname"><span class="pre">is_qnan</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_qnan" title="Link to this definition">¶</a></dt>881<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a quiet NaN, and882<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.</p>883</dd></dl>884 885<dl class="py method">886<dt class="sig sig-object py" id="decimal.Decimal.is_signed">887<span class="sig-name descname"><span class="pre">is_signed</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_signed" title="Link to this definition">¶</a></dt>888<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument has a negative sign and889<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.  Note that zeros and NaNs can both carry signs.</p>890</dd></dl>891 892<dl class="py method">893<dt class="sig sig-object py" id="decimal.Decimal.is_snan">894<span class="sig-name descname"><span class="pre">is_snan</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_snan" title="Link to this definition">¶</a></dt>895<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a signaling NaN and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>896otherwise.</p>897</dd></dl>898 899<dl class="py method">900<dt class="sig sig-object py" id="decimal.Decimal.is_subnormal">901<span class="sig-name descname"><span class="pre">is_subnormal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_subnormal" title="Link to this definition">¶</a></dt>902<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is subnormal, and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>903otherwise.</p>904</dd></dl>905 906<dl class="py method">907<dt class="sig sig-object py" id="decimal.Decimal.is_zero">908<span class="sig-name descname"><span class="pre">is_zero</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_zero" title="Link to this definition">¶</a></dt>909<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a (positive or negative) zero and910<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.</p>911</dd></dl>912 913<dl class="py method">914<dt class="sig sig-object py" id="decimal.Decimal.ln">915<span class="sig-name descname"><span class="pre">ln</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.ln" title="Link to this definition">¶</a></dt>916<dd><p>Return the natural (base e) logarithm of the operand.  The result is917correctly rounded using the <a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a> rounding mode.</p>918</dd></dl>919 920<dl class="py method">921<dt class="sig sig-object py" id="decimal.Decimal.log10">922<span class="sig-name descname"><span class="pre">log10</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.log10" title="Link to this definition">¶</a></dt>923<dd><p>Return the base ten logarithm of the operand.  The result is correctly924rounded using the <a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a> rounding mode.</p>925</dd></dl>926 927<dl class="py method">928<dt class="sig sig-object py" id="decimal.Decimal.logb">929<span class="sig-name descname"><span class="pre">logb</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logb" title="Link to this definition">¶</a></dt>930<dd><p>For a nonzero number, return the adjusted exponent of its operand as a931<code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code> instance.  If the operand is a zero then932<code class="docutils literal notranslate"><span class="pre">Decimal('-Infinity')</span></code> is returned and the <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-const docutils literal notranslate"><span class="pre">DivisionByZero</span></code></a> flag933is raised.  If the operand is an infinity then <code class="docutils literal notranslate"><span class="pre">Decimal('Infinity')</span></code> is934returned.</p>935</dd></dl>936 937<dl class="py method">938<dt class="sig sig-object py" id="decimal.Decimal.logical_and">939<span class="sig-name descname"><span class="pre">logical_and</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logical_and" title="Link to this definition">¶</a></dt>940<dd><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_and()</span></code> is a logical operation which takes two <em>logical941operands</em> (see <a class="reference internal" href="#logical-operands-label"><span class="std std-ref">Logical operands</span></a>).  The result is the942digit-wise <code class="docutils literal notranslate"><span class="pre">and</span></code> of the two operands.</p>943</dd></dl>944 945<dl class="py method">946<dt class="sig sig-object py" id="decimal.Decimal.logical_invert">947<span class="sig-name descname"><span class="pre">logical_invert</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logical_invert" title="Link to this definition">¶</a></dt>948<dd><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_invert()</span></code> is a logical operation.  The949result is the digit-wise inversion of the operand.</p>950</dd></dl>951 952<dl class="py method">953<dt class="sig sig-object py" id="decimal.Decimal.logical_or">954<span class="sig-name descname"><span class="pre">logical_or</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logical_or" title="Link to this definition">¶</a></dt>955<dd><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_or()</span></code> is a logical operation which takes two <em>logical956operands</em> (see <a class="reference internal" href="#logical-operands-label"><span class="std std-ref">Logical operands</span></a>).  The result is the957digit-wise <code class="docutils literal notranslate"><span class="pre">or</span></code> of the two operands.</p>958</dd></dl>959 960<dl class="py method">961<dt class="sig sig-object py" id="decimal.Decimal.logical_xor">962<span class="sig-name descname"><span class="pre">logical_xor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logical_xor" title="Link to this definition">¶</a></dt>963<dd><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_xor()</span></code> is a logical operation which takes two <em>logical964operands</em> (see <a class="reference internal" href="#logical-operands-label"><span class="std std-ref">Logical operands</span></a>).  The result is the965digit-wise exclusive or of the two operands.</p>966</dd></dl>967 968<dl class="py method">969<dt class="sig sig-object py" id="decimal.Decimal.max">970<span class="sig-name descname"><span class="pre">max</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.max" title="Link to this definition">¶</a></dt>971<dd><p>Like <code class="docutils literal notranslate"><span class="pre">max(self,</span> <span class="pre">other)</span></code> except that the context rounding rule is applied972before returning and that <code class="docutils literal notranslate"><span class="pre">NaN</span></code> values are either signaled or973ignored (depending on the context and whether they are signaling or974quiet).</p>975</dd></dl>976 977<dl class="py method">978<dt class="sig sig-object py" id="decimal.Decimal.max_mag">979<span class="sig-name descname"><span class="pre">max_mag</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.max_mag" title="Link to this definition">¶</a></dt>980<dd><p>Similar to the <a class="reference internal" href="#decimal.Decimal.max" title="decimal.Decimal.max"><code class="xref py py-meth docutils literal notranslate"><span class="pre">max()</span></code></a> method, but the comparison is done using the981absolute values of the operands.</p>982</dd></dl>983 984<dl class="py method">985<dt class="sig sig-object py" id="decimal.Decimal.min">986<span class="sig-name descname"><span class="pre">min</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.min" title="Link to this definition">¶</a></dt>987<dd><p>Like <code class="docutils literal notranslate"><span class="pre">min(self,</span> <span class="pre">other)</span></code> except that the context rounding rule is applied988before returning and that <code class="docutils literal notranslate"><span class="pre">NaN</span></code> values are either signaled or989ignored (depending on the context and whether they are signaling or990quiet).</p>991</dd></dl>992 993<dl class="py method">994<dt class="sig sig-object py" id="decimal.Decimal.min_mag">995<span class="sig-name descname"><span class="pre">min_mag</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.min_mag" title="Link to this definition">¶</a></dt>996<dd><p>Similar to the <a class="reference internal" href="#decimal.Decimal.min" title="decimal.Decimal.min"><code class="xref py py-meth docutils literal notranslate"><span class="pre">min()</span></code></a> method, but the comparison is done using the997absolute values of the operands.</p>998</dd></dl>999 1000<dl class="py method">1001<dt class="sig sig-object py" id="decimal.Decimal.next_minus">1002<span class="sig-name descname"><span class="pre">next_minus</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.next_minus" title="Link to this definition">¶</a></dt>1003<dd><p>Return the largest number representable in the given context (or in the1004current thread’s context if no context is given) that is smaller than the1005given operand.</p>1006</dd></dl>1007 1008<dl class="py method">1009<dt class="sig sig-object py" id="decimal.Decimal.next_plus">1010<span class="sig-name descname"><span class="pre">next_plus</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.next_plus" title="Link to this definition">¶</a></dt>1011<dd><p>Return the smallest number representable in the given context (or in the1012current thread’s context if no context is given) that is larger than the1013given operand.</p>1014</dd></dl>1015 1016<dl class="py method">1017<dt class="sig sig-object py" id="decimal.Decimal.next_toward">1018<span class="sig-name descname"><span class="pre">next_toward</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.next_toward" title="Link to this definition">¶</a></dt>1019<dd><p>If the two operands are unequal, return the number closest to the first1020operand in the direction of the second operand.  If both operands are1021numerically equal, return a copy of the first operand with the sign set to1022be the same as the sign of the second operand.</p>1023</dd></dl>1024 1025<dl class="py method">1026<dt class="sig sig-object py" id="decimal.Decimal.normalize">1027<span class="sig-name descname"><span class="pre">normalize</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.normalize" title="Link to this definition">¶</a></dt>1028<dd><p>Used for producing canonical values of an equivalence1029class within either the current context or the specified context.</p>1030<p>This has the same semantics as the unary plus operation, except that if1031the final result is finite it is reduced to its simplest form, with all1032trailing zeros removed and its sign preserved. That is, while the1033coefficient is non-zero and a multiple of ten the coefficient is divided1034by ten and the exponent is incremented by 1. Otherwise (the coefficient is1035zero) the exponent is set to 0. In all cases the sign is unchanged.</p>1036<p>For example, <code class="docutils literal notranslate"><span class="pre">Decimal('32.100')</span></code> and <code class="docutils literal notranslate"><span class="pre">Decimal('0.321000e+2')</span></code> both1037normalize to the equivalent value <code class="docutils literal notranslate"><span class="pre">Decimal('32.1')</span></code>.</p>1038<p>Note that rounding is applied <em>before</em> reducing to simplest form.</p>1039<p>In the latest versions of the specification, this operation is also known1040as <code class="docutils literal notranslate"><span class="pre">reduce</span></code>.</p>1041</dd></dl>1042 1043<dl class="py method">1044<dt class="sig sig-object py" id="decimal.Decimal.number_class">1045<span class="sig-name descname"><span class="pre">number_class</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.number_class" title="Link to this definition">¶</a></dt>1046<dd><p>Return a string describing the <em>class</em> of the operand.  The returned value1047is one of the following ten strings.</p>1048<ul class="simple">1049<li><p><code class="docutils literal notranslate"><span class="pre">&quot;-Infinity&quot;</span></code>, indicating that the operand is negative infinity.</p></li>1050<li><p><code class="docutils literal notranslate"><span class="pre">&quot;-Normal&quot;</span></code>, indicating that the operand is a negative normal number.</p></li>1051<li><p><code class="docutils literal notranslate"><span class="pre">&quot;-Subnormal&quot;</span></code>, indicating that the operand is negative and subnormal.</p></li>1052<li><p><code class="docutils literal notranslate"><span class="pre">&quot;-Zero&quot;</span></code>, indicating that the operand is a negative zero.</p></li>1053<li><p><code class="docutils literal notranslate"><span class="pre">&quot;+Zero&quot;</span></code>, indicating that the operand is a positive zero.</p></li>1054<li><p><code class="docutils literal notranslate"><span class="pre">&quot;+Subnormal&quot;</span></code>, indicating that the operand is positive and subnormal.</p></li>1055<li><p><code class="docutils literal notranslate"><span class="pre">&quot;+Normal&quot;</span></code>, indicating that the operand is a positive normal number.</p></li>1056<li><p><code class="docutils literal notranslate"><span class="pre">&quot;+Infinity&quot;</span></code>, indicating that the operand is positive infinity.</p></li>1057<li><p><code class="docutils literal notranslate"><span class="pre">&quot;NaN&quot;</span></code>, indicating that the operand is a quiet NaN (Not a Number).</p></li>1058<li><p><code class="docutils literal notranslate"><span class="pre">&quot;sNaN&quot;</span></code>, indicating that the operand is a signaling NaN.</p></li>1059</ul>1060</dd></dl>1061 1062<dl class="py method">1063<dt class="sig sig-object py" id="decimal.Decimal.quantize">1064<span class="sig-name descname"><span class="pre">quantize</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">exp</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rounding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.quantize" title="Link to this definition">¶</a></dt>1065<dd><p>Return a value equal to the first operand after rounding and having the1066exponent of the second operand.</p>1067<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;1.41421356&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">&#39;1.000&#39;</span><span class="p">))</span>1068<span class="go">Decimal(&#39;1.414&#39;)</span>1069</pre></div>1070</div>1071<p>Unlike other operations, if the length of the coefficient after the1072quantize operation would be greater than precision, then an1073<a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a> is signaled. This guarantees that, unless there1074is an error condition, the quantized exponent is always equal to that of1075the right-hand operand.</p>1076<p>Also unlike other operations, quantize never signals Underflow, even if1077the result is subnormal and inexact.</p>1078<p>If the exponent of the second operand is larger than that of the first1079then rounding may be necessary.  In this case, the rounding mode is1080determined by the <code class="docutils literal notranslate"><span class="pre">rounding</span></code> argument if given, else by the given1081<code class="docutils literal notranslate"><span class="pre">context</span></code> argument; if neither argument is given the rounding mode of1082the current thread’s context is used.</p>1083<p>An error is returned whenever the resulting exponent is greater than1084<a class="reference internal" href="#decimal.Context.Emax" title="decimal.Context.Emax"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Emax</span></code></a> or less than <a class="reference internal" href="#decimal.Context.Etiny" title="decimal.Context.Etiny"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Etiny()</span></code></a>.</p>1085</dd></dl>1086 1087<dl class="py method">1088<dt class="sig sig-object py" id="decimal.Decimal.radix">1089<span class="sig-name descname"><span class="pre">radix</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.radix" title="Link to this definition">¶</a></dt>1090<dd><p>Return <code class="docutils literal notranslate"><span class="pre">Decimal(10)</span></code>, the radix (base) in which the <code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code>1091class does all its arithmetic.  Included for compatibility with the1092specification.</p>1093</dd></dl>1094 1095<dl class="py method">1096<dt class="sig sig-object py" id="decimal.Decimal.remainder_near">1097<span class="sig-name descname"><span class="pre">remainder_near</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.remainder_near" title="Link to this definition">¶</a></dt>1098<dd><p>Return the remainder from dividing <em>self</em> by <em>other</em>.  This differs from1099<code class="docutils literal notranslate"><span class="pre">self</span> <span class="pre">%</span> <span class="pre">other</span></code> in that the sign of the remainder is chosen so as to1100minimize its absolute value.  More precisely, the return value is1101<code class="docutils literal notranslate"><span class="pre">self</span> <span class="pre">-</span> <span class="pre">n</span> <span class="pre">*</span> <span class="pre">other</span></code> where <code class="docutils literal notranslate"><span class="pre">n</span></code> is the integer nearest to the exact1102value of <code class="docutils literal notranslate"><span class="pre">self</span> <span class="pre">/</span> <span class="pre">other</span></code>, and if two integers are equally near then the1103even one is chosen.</p>1104<p>If the result is zero then its sign will be the sign of <em>self</em>.</p>1105<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">18</span><span class="p">)</span><span class="o">.</span><span class="n">remainder_near</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span>1106<span class="go">Decimal(&#39;-2&#39;)</span>1107<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">25</span><span class="p">)</span><span class="o">.</span><span class="n">remainder_near</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span>1108<span class="go">Decimal(&#39;5&#39;)</span>1109<span class="gp">&gt;&gt;&gt; </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">35</span><span class="p">)</span><span class="o">.</span><span class="n">remainder_near</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span>1110<span class="go">Decimal(&#39;-5&#39;)</span>1111</pre></div>1112</div>1113</dd></dl>1114 1115<dl class="py method">1116<dt class="sig sig-object py" id="decimal.Decimal.rotate">1117<span class="sig-name descname"><span class="pre">rotate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.rotate" title="Link to this definition">¶</a></dt>1118<dd><p>Return the result of rotating the digits of the first operand by an amount1119specified by the second operand.  The second operand must be an integer in1120the range -precision through precision.  The absolute value of the second1121operand gives the number of places to rotate.  If the second operand is1122positive then rotation is to the left; otherwise rotation is to the right.1123The coefficient of the first operand is padded on the left with zeros to1124length precision if necessary.  The sign and exponent of the first operand1125are unchanged.</p>1126</dd></dl>1127 1128<dl class="py method">1129<dt class="sig sig-object py" id="decimal.Decimal.same_quantum">1130<span class="sig-name descname"><span class="pre">same_quantum</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.same_quantum" title="Link to this definition">¶</a></dt>1131<dd><p>Test whether self and other have the same exponent or whether both are1132<code class="docutils literal notranslate"><span class="pre">NaN</span></code>.</p>1133<p>This operation is unaffected by context and is quiet: no flags are changed1134and no rounding is performed.  As an exception, the C version may raise1135InvalidOperation if the second operand cannot be converted exactly.</p>1136</dd></dl>1137 1138<dl class="py method">1139<dt class="sig sig-object py" id="decimal.Decimal.scaleb">1140<span class="sig-name descname"><span class="pre">scaleb</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.scaleb" title="Link to this definition">¶</a></dt>1141<dd><p>Return the first operand with exponent adjusted by the second.1142Equivalently, return the first operand multiplied by <code class="docutils literal notranslate"><span class="pre">10**other</span></code>.  The1143second operand must be an integer.</p>1144</dd></dl>1145 1146<dl class="py method">1147<dt class="sig sig-object py" id="decimal.Decimal.shift">1148<span class="sig-name descname"><span class="pre">shift</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">other</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.shift" title="Link to this definition">¶</a></dt>1149<dd><p>Return the result of shifting the digits of the first operand by an amount1150specified by the second operand.  The second operand must be an integer in1151the range -precision through precision.  The absolute value of the second1152operand gives the number of places to shift.  If the second operand is1153positive then the shift is to the left; otherwise the shift is to the1154right.  Digits shifted into the coefficient are zeros.  The sign and1155exponent of the first operand are unchanged.</p>1156</dd></dl>1157 1158<dl class="py method">1159<dt class="sig sig-object py" id="decimal.Decimal.sqrt">1160<span class="sig-name descname"><span class="pre">sqrt</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.sqrt" title="Link to this definition">¶</a></dt>1161<dd><p>Return the square root of the argument to full precision.</p>1162</dd></dl>1163 1164<dl class="py method">1165<dt class="sig sig-object py" id="decimal.Decimal.to_eng_string">1166<span class="sig-name descname"><span class="pre">to_eng_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.to_eng_string" title="Link to this definition">¶</a></dt>1167<dd><p>Convert to a string, using engineering notation if an exponent is needed.</p>1168<p>Engineering notation has an exponent which is a multiple of 3.  This1169can leave up to 3 digits to the left of the decimal place and may1170require the addition of either one or two trailing zeros.</p>1171<p>For example, this converts <code class="docutils literal notranslate"><span class="pre">Decimal('123E+1')</span></code> to <code class="docutils literal notranslate"><span class="pre">Decimal('1.23E+3')</span></code>.</p>1172</dd></dl>1173 1174<dl class="py method">1175<dt class="sig sig-object py" id="decimal.Decimal.to_integral">1176<span class="sig-name descname"><span class="pre">to_integral</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">rounding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.to_integral" title="Link to this definition">¶</a></dt>1177<dd><p>Identical to the <a class="reference internal" href="#decimal.Decimal.to_integral_value" title="decimal.Decimal.to_integral_value"><code class="xref py py-meth docutils literal notranslate"><span class="pre">to_integral_value()</span></code></a> method.  The <code class="docutils literal notranslate"><span class="pre">to_integral</span></code>1178name has been kept for compatibility with older versions.</p>1179</dd></dl>1180 1181<dl class="py method">1182<dt class="sig sig-object py" id="decimal.Decimal.to_integral_exact">1183<span class="sig-name descname"><span class="pre">to_integral_exact</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">rounding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.to_integral_exact" title="Link to this definition">¶</a></dt>1184<dd><p>Round to the nearest integer, signaling <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a> or1185<a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal notranslate"><span class="pre">Rounded</span></code></a> as appropriate if rounding occurs.  The rounding mode is1186determined by the <code class="docutils literal notranslate"><span class="pre">rounding</span></code> parameter if given, else by the given1187<code class="docutils literal notranslate"><span class="pre">context</span></code>.  If neither parameter is given then the rounding mode of the1188current context is used.</p>1189</dd></dl>1190 1191<dl class="py method">1192<dt class="sig sig-object py" id="decimal.Decimal.to_integral_value">1193<span class="sig-name descname"><span class="pre">to_integral_value</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">rounding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.to_integral_value" title="Link to this definition">¶</a></dt>1194<dd><p>Round to the nearest integer without signaling <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a> or1195<a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal notranslate"><span class="pre">Rounded</span></code></a>.  If given, applies <em>rounding</em>; otherwise, uses the1196rounding method in either the supplied <em>context</em> or the current context.</p>1197</dd></dl>1198 1199<p>Decimal numbers can be rounded using the <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> function:</p>1200<dl class="describe">

Showing the first 1,200 of 2866 lines. Download the file for the rest.