<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>decimal128 – Support for BSON Decimal128 — PyMongo 3.7.2 documentation</title>
<link rel="stylesheet" href="../../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<script type="text/javascript" src="../../_static/language_data.js"></script>
<script type="text/javascript" src="../../_static/sidebar.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="errors – Exceptions raised by the bson package" href="errors.html" />
<link rel="prev" title="dbref – Tools for manipulating DBRefs (references to documents stored in MongoDB)" href="dbref.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="errors.html" title="errors – Exceptions raised by the bson package"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="dbref.html" title="dbref – Tools for manipulating DBRefs (references to documents stored in MongoDB)"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">PyMongo 3.7.2 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../index.html" >API Documentation</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" accesskey="U"><code class="docutils literal notranslate"><span class="pre">bson</span></code> – BSON (Binary JSON) Encoding and Decoding</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="module-bson.decimal128">
<span id="decimal128-support-for-bson-decimal128"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal128</span></code> – Support for BSON Decimal128<a class="headerlink" href="#module-bson.decimal128" title="Permalink to this headline">¶</a></h1>
<p>Tools for working with the BSON decimal128 type.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.4.</span></p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The Decimal128 BSON type requires MongoDB 3.4+.</p>
</div>
<dl class="class">
<dt id="bson.decimal128.Decimal128">
<em class="property">class </em><code class="descclassname">bson.decimal128.</code><code class="descname">Decimal128</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#bson.decimal128.Decimal128" title="Permalink to this definition">¶</a></dt>
<dd><p>BSON Decimal128 type:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s2">"0.0005"</span><span class="p">))</span>
<span class="go">Decimal128('0.0005')</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="s2">"0.0005"</span><span class="p">)</span>
<span class="go">Decimal128('0.0005')</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">((</span><span class="mi">3474527112516337664</span><span class="p">,</span> <span class="mi">5</span><span class="p">))</span>
<span class="go">Decimal128('0.0005')</span>
</pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><cite>value</cite>: An instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Decimal</span></code>, string, or tuple of
(high bits, low bits) from Binary Integer Decimal (BID) format.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p><a class="reference internal" href="#bson.decimal128.Decimal128" title="bson.decimal128.Decimal128"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal128</span></code></a> uses an instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Context</span></code>
configured for IEEE-754 Decimal128 when validating parameters.
Signals like <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.InvalidOperation</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Inexact</span></code>,
and <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Overflow</span></code> are trapped and raised as exceptions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="s2">".13.1"</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
<span class="c">...</span>
<span class="gr">decimal.InvalidOperation</span>: <span class="n">[<class 'decimal.ConversionSyntax'>]</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="s2">"1E-6177"</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
<span class="c">...</span>
<span class="gr">decimal.Inexact</span>: <span class="n">[<class 'decimal.Inexact'>]</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="s2">"1E6145"</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
<span class="c">...</span>
<span class="gr">decimal.Overflow</span>: <span class="n">[<class 'decimal.Overflow'>, <class 'decimal.Rounded'>]</span>
</pre></div>
</div>
<p>To ensure the result of a calculation can always be stored as BSON
Decimal128 use the context returned by
<a class="reference internal" href="#bson.decimal128.create_decimal128_context" title="bson.decimal128.create_decimal128_context"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_decimal128_context()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">decimal</span>
<span class="gp">>>> </span><span class="n">decimal128_ctx</span> <span class="o">=</span> <span class="n">create_decimal128_context</span><span class="p">()</span>
<span class="gp">>>> </span><span class="k">with</span> <span class="n">decimal</span><span class="o">.</span><span class="n">localcontext</span><span class="p">(</span><span class="n">decimal128_ctx</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">Decimal128</span><span class="p">(</span><span class="n">ctx</span><span class="o">.</span><span class="n">create_decimal</span><span class="p">(</span><span class="s2">".13.3"</span><span class="p">))</span>
<span class="gp">...</span>
<span class="go">Decimal128('NaN')</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="k">with</span> <span class="n">decimal</span><span class="o">.</span><span class="n">localcontext</span><span class="p">(</span><span class="n">decimal128_ctx</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">Decimal128</span><span class="p">(</span><span class="n">ctx</span><span class="o">.</span><span class="n">create_decimal</span><span class="p">(</span><span class="s2">"1E-6177"</span><span class="p">))</span>
<span class="gp">...</span>
<span class="go">Decimal128('0E-6176')</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="k">with</span> <span class="n">decimal</span><span class="o">.</span><span class="n">localcontext</span><span class="p">(</span><span class="n">DECIMAL128_CTX</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">Decimal128</span><span class="p">(</span><span class="n">ctx</span><span class="o">.</span><span class="n">create_decimal</span><span class="p">(</span><span class="s2">"1E6145"</span><span class="p">))</span>
<span class="gp">...</span>
<span class="go">Decimal128('Infinity')</span>
</pre></div>
</div>
<p>To match the behavior of MongoDB’s Decimal128 implementation
str(Decimal(value)) may not match str(Decimal128(value)) for NaN values:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">))</span>
<span class="go">Decimal128('NaN')</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'-NaN'</span><span class="p">))</span>
<span class="go">Decimal128('NaN')</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'sNaN'</span><span class="p">))</span>
<span class="go">Decimal128('NaN')</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'-sNaN'</span><span class="p">))</span>
<span class="go">Decimal128('NaN')</span>
</pre></div>
</div>
<p>However, <a class="reference internal" href="#bson.decimal128.Decimal128.to_decimal" title="bson.decimal128.Decimal128.to_decimal"><code class="xref py py-meth docutils literal notranslate"><span class="pre">to_decimal()</span></code></a> will return the exact value:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">))</span><span class="o">.</span><span class="n">to_decimal</span><span class="p">()</span>
<span class="go">Decimal('NaN')</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'-NaN'</span><span class="p">))</span><span class="o">.</span><span class="n">to_decimal</span><span class="p">()</span>
<span class="go">Decimal('-NaN')</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'sNaN'</span><span class="p">))</span><span class="o">.</span><span class="n">to_decimal</span><span class="p">()</span>
<span class="go">Decimal('sNaN')</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'-sNaN'</span><span class="p">))</span><span class="o">.</span><span class="n">to_decimal</span><span class="p">()</span>
<span class="go">Decimal('-sNaN')</span>
</pre></div>
</div>
<p>Two instances of <a class="reference internal" href="#bson.decimal128.Decimal128" title="bson.decimal128.Decimal128"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal128</span></code></a> compare equal if their Binary
Integer Decimal encodings are equal:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span> <span class="o">==</span> <span class="n">Decimal128</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">Decimal128</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span><span class="o">.</span><span class="n">bid</span> <span class="o">==</span> <span class="n">Decimal128</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span><span class="o">.</span><span class="n">bid</span>
<span class="go">True</span>
</pre></div>
</div>
<p>This differs from <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Decimal</span></code> comparisons for NaN:</p>
<div class="last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span> <span class="o">==</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span>
<span class="go">False</span>
</pre></div>
</div>
</div>
<dl class="attribute">
<dt id="bson.decimal128.Decimal128.bid">
<code class="descname">bid</code><a class="headerlink" href="#bson.decimal128.Decimal128.bid" title="Permalink to this definition">¶</a></dt>
<dd><p>The Binary Integer Decimal (BID) encoding of this instance.</p>
</dd></dl>
<dl class="classmethod">
<dt id="bson.decimal128.Decimal128.from_bid">
<em class="property">classmethod </em><code class="descname">from_bid</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#bson.decimal128.Decimal128.from_bid" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an instance of <a class="reference internal" href="#bson.decimal128.Decimal128" title="bson.decimal128.Decimal128"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal128</span></code></a> from Binary Integer
Decimal string.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><cite>value</cite>: 16 byte string (128-bit IEEE 754-2008 decimal floating
point in Binary Integer Decimal (BID) format).</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="bson.decimal128.Decimal128.to_decimal">
<code class="descname">to_decimal</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#bson.decimal128.Decimal128.to_decimal" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Decimal</span></code> for this
<a class="reference internal" href="#bson.decimal128.Decimal128" title="bson.decimal128.Decimal128"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal128</span></code></a>.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="bson.decimal128.create_decimal128_context">
<code class="descclassname">bson.decimal128.</code><code class="descname">create_decimal128_context</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#bson.decimal128.create_decimal128_context" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Context</span></code> appropriate
for working with IEEE-754 128-bit decimal floating point values.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="dbref.html"
title="previous chapter"><code class="docutils literal notranslate"><span class="pre">dbref</span></code> – Tools for manipulating DBRefs (references to documents stored in MongoDB)</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="errors.html"
title="next chapter"><code class="docutils literal notranslate"><span class="pre">errors</span></code> – Exceptions raised by the <code class="docutils literal notranslate"><span class="pre">bson</span></code> package</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/api/bson/decimal128.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="errors.html" title="errors – Exceptions raised by the bson package"
>next</a> |</li>
<li class="right" >
<a href="dbref.html" title="dbref – Tools for manipulating DBRefs (references to documents stored in MongoDB)"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">PyMongo 3.7.2 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../index.html" >API Documentation</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" ><code class="docutils literal notranslate"><span class="pre">bson</span></code> – BSON (Binary JSON) Encoding and Decoding</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright MongoDB, Inc. 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
bc55833f04f370ac3ed453ef5b0ad686
>
files
>
221
