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 ofdecimal.Context
configured for IEEE-754 Decimal128 when validating parameters. Signals likedecimal.InvalidOperation
,decimal.Inexact
, anddecimal.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
- 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:
- to_decimal()¶
Returns an instance of
decimal.Decimal
for thisDecimal128
.- Return type:
- 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: