decimal128 – Support for BSON Decimal128

Tools for working with the BSON decimal128 type.

New in version 3.4.

Note

The Decimal128 BSON type requires MongoDB 3.4+.

  • class bson.decimal128.Decimal128(value)
  • BSON Decimal128 type:
  1. >>> Decimal128(Decimal("0.0005"))
  2. Decimal128('0.0005')
  3. >>> Decimal128("0.0005")
  4. Decimal128('0.0005')
  5. >>> Decimal128((3474527112516337664, 5))
  6. Decimal128('0.0005')

Parameters:

  • value: An instance of decimal.Decimal, string, or tuple of(high bits, low bits) from Binary Integer Decimal (BID) format.

Note

Decimal128 uses an instance of decimal.Contextconfigured for IEEE-754 Decimal128 when validating parameters.Signals like decimal.InvalidOperation, decimal.Inexact,and decimal.Overflow are trapped and raised as exceptions:

  1. >>> Decimal128(".13.1")
  2. Traceback (most recent call last):
  3.   File "<stdin>", line 1, in <module>
  4.   ...
  5. decimal.InvalidOperation: [<class 'decimal.ConversionSyntax'>]
  6. >>>
  7. >>> Decimal128("1E-6177")
  8. Traceback (most recent call last):
  9.   File "<stdin>", line 1, in <module>
  10.   ...
  11. decimal.Inexact: [<class 'decimal.Inexact'>]
  12. >>>
  13. >>> Decimal128("1E6145")
  14. Traceback (most recent call last):
  15.   File "<stdin>", line 1, in <module>
  16.   ...
  17. decimal.Overflow: [<class 'decimal.Overflow'>, <class 'decimal.Rounded'>]

To ensure the result of a calculation can always be stored as BSONDecimal128 use the context returned bycreate_decimal128_context():

  1. >>> import decimal
  2. >>> decimal128_ctx = create_decimal128_context()
  3. >>> with decimal.localcontext(decimal128_ctx) as ctx:
  4. ...     Decimal128(ctx.create_decimal(".13.3"))
  5. ...
  6. Decimal128('NaN')
  7. >>>
  8. >>> with decimal.localcontext(decimal128_ctx) as ctx:
  9. ...     Decimal128(ctx.create_decimal("1E-6177"))
  10. ...
  11. Decimal128('0E-6176')
  12. >>>
  13. >>> with decimal.localcontext(DECIMAL128_CTX) as ctx:
  14. ...     Decimal128(ctx.create_decimal("1E6145"))
  15. ...
  16. Decimal128('Infinity')

To match the behavior of MongoDB’s Decimal128 implementationstr(Decimal(value)) may not match str(Decimal128(value)) for NaN values:

  1. >>> Decimal128(Decimal('NaN'))
  2. Decimal128('NaN')
  3. >>> Decimal128(Decimal('-NaN'))
  4. Decimal128('NaN')
  5. >>> Decimal128(Decimal('sNaN'))
  6. Decimal128('NaN')
  7. >>> Decimal128(Decimal('-sNaN'))
  8. Decimal128('NaN')

However, to_decimal() will return the exact value:

  1. >>> Decimal128(Decimal('NaN')).to_decimal()
  2. Decimal('NaN')
  3. >>> Decimal128(Decimal('-NaN')).to_decimal()
  4. Decimal('-NaN')
  5. >>> Decimal128(Decimal('sNaN')).to_decimal()
  6. Decimal('sNaN')
  7. >>> Decimal128(Decimal('-sNaN')).to_decimal()
  8. Decimal('-sNaN')

Two instances of Decimal128 compare equal if their BinaryInteger Decimal encodings are equal:

  1. >>> Decimal128('NaN') == Decimal128('NaN')
  2. True
  3. >>> Decimal128('NaN').bid == Decimal128('NaN').bid
  4. True

This differs from decimal.Decimal comparisons for NaN:

  1. >>> Decimal('NaN') == Decimal('NaN')
  2. False
  • bid

  • The Binary Integer Decimal (BID) encoding of this instance.

  • classmethod frombid(_value)

  • Create an instance of Decimal128 from Binary IntegerDecimal string.

Parameters:

  1. - _value_: 16 byte string (128-bit IEEE 754-2008 decimal floatingpoint in Binary Integer Decimal (BID) format).
  • bson.decimal128.create_decimal128_context()
  • Returns an instance of decimal.Context appropriatefor working with IEEE-754 128-bit decimal floating point values.