# `decimal128` – Support for BSON Decimal128

Tools for working with the BSON decimal128 type.

Added in version 3.4.

class bson.decimal128.Decimal128(value)

  BSON Decimal128 type:

      >>> Decimal128(Decimal("0.0005"))
      Decimal128('0.0005')
      >>> Decimal128("0.0005")
      Decimal128('0.0005')
      >>> Decimal128((3474527112516337664, 5))
      Decimal128('0.0005')

  Parameters:

    value (_VALUE_OPTIONS) – 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.Context` configured for IEEE-754 Decimal128 when validating parameters. Signals like `decimal.InvalidOperation`, `decimal.Inexact`, and `decimal.Overflow` are trapped and raised as exceptions:

      >>> Decimal128(".13.1")
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
        ...
      decimal.InvalidOperation: [<class 'decimal.ConversionSyntax'>]
      >>>
      >>> Decimal128("1E-6177")
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
        ...
      decimal.Inexact: [<class 'decimal.Inexact'>]
      >>>
      >>> Decimal128("1E6145")
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
        ...
      decimal.Overflow: [<class 'decimal.Overflow'>, <class 'decimal.Rounded'>]

  To ensure the result of a calculation can always be stored as BSON Decimal128 use the context returned by `create_decimal128_context()`:

      >>> import decimal
      >>> decimal128_ctx = create_decimal128_context()
      >>> with decimal.localcontext(decimal128_ctx) as ctx:
      ...     Decimal128(ctx.create_decimal(".13.3"))
      ...
      Decimal128('NaN')
      >>>
      >>> with decimal.localcontext(decimal128_ctx) as ctx:
      ...     Decimal128(ctx.create_decimal("1E-6177"))
      ...
      Decimal128('0E-6176')
      >>>
      >>> with decimal.localcontext(DECIMAL128_CTX) as ctx:
      ...     Decimal128(ctx.create_decimal("1E6145"))
      ...
      Decimal128('Infinity')

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

      >>> Decimal128(Decimal('NaN'))
      Decimal128('NaN')
      >>> Decimal128(Decimal('-NaN'))
      Decimal128('NaN')
      >>> Decimal128(Decimal('sNaN'))
      Decimal128('NaN')
      >>> Decimal128(Decimal('-sNaN'))
      Decimal128('NaN')

  However, `to_decimal()` will return the exact value:

      >>> Decimal128(Decimal('NaN')).to_decimal()
      Decimal('NaN')
      >>> Decimal128(Decimal('-NaN')).to_decimal()
      Decimal('-NaN')
      >>> Decimal128(Decimal('sNaN')).to_decimal()
      Decimal('sNaN')
      >>> Decimal128(Decimal('-sNaN')).to_decimal()
      Decimal('-sNaN')

  Two instances of `Decimal128` compare equal if their Binary Integer Decimal encodings are equal:

      >>> Decimal128('NaN') == Decimal128('NaN')
      True
      >>> Decimal128('NaN').bid == Decimal128('NaN').bid
      True

  This differs from `decimal.Decimal` comparisons for NaN:

      >>> Decimal('NaN') == Decimal('NaN')
      False

  property bid: bytes

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

  classmethod from_bid(value)

    Create an instance of `Decimal128` from Binary Integer Decimal string.

    Parameters:

      value (bytes) – 16 byte string (128-bit IEEE 754-2008 decimal floating point in Binary Integer Decimal (BID) format).

    Return type:

      Decimal128

  to_decimal()

    Returns an instance of `decimal.Decimal` for this `Decimal128`.

    Return type:

      Decimal

class bson.decimal128.DecimalDecoder

  Converts BSON `Decimal128` to Python `decimal.Decimal`.

  For example::

    opts = CodecOptions(type_registry=TypeRegistry([DecimalDecoder()])) bson.decode(data, codec_options=opts)

  Added in version 4.15.

  property bson_type: Type[Decimal128]

    The BSON type to be converted into our own type.

  transform_bson(value)

    Convert the given BSON value into our own type.

    Parameters:

      value (Any)

    Return type:

      Decimal

class bson.decimal128.DecimalEncoder

  Converts Python `decimal.Decimal` to BSON `Decimal128`.

  For example::

    opts = CodecOptions(type_registry=TypeRegistry([DecimalEncoder()])) bson.encode({“d”: decimal.Decimal(‘1.0’)}, codec_options=opts)

  Added in version 4.15.

  property python_type: Type[Decimal]

    The Python type to be converted into something serializable.

  transform_python(value)

    Convert the given Python object into something serializable.

    Parameters:

      value (Any)

    Return type:

      Decimal128

bson.decimal128.create_decimal128_context()

  Returns an instance of `decimal.Context` appropriate for working with IEEE-754 128-bit decimal floating point values.

  Return type:

    Context