decimal128 1.0.2

No project description provided

decimal128

This package is primarily a fork of the decimal128 support found in the MondoDB python driver. The motivation for this project is to provide a standalone package with no dependencies that does not need all of MongoDB's python driver.

Usage

The Decimal128 class behaves largely like a standard python decimal.Decimal class. Most arithmetic operators are included and the package supports a small number of additional init values to allow for conversion from binary integer decimal (BID). Decimal128 uses an instance of decimal.Context configured for IEEE-754 Decimal128 when validating parameters.

Unlike MongoDB's Decimal128, no signals are trapped and as such, exceptions are not raised for decimal.InvalidOperation, decimal.Inexact, or decimal.Overflow.

Supported init values are str, int, float, standard decimal.Decimal objects, BID tuple, and using a classmethof for BID bytes:

>>> Decimal128("0.0625")
Decimal128('0.0625')
>>> Decimal128(Decimal("0.0625"))
Decimal128('0.0625')
>>> Decimal128(625)
Decimal128('625')
>>> Decimal128(0.0625)
Decimal128('0.0625')
>>> Decimal128((3474527112516337664,625))
Decimal128('0.0625')
>>> Decimal128.from_bid(bytes.fromhex("30380000000000000000000000000271"))
Decimal128('0.0625')

decimal.Decimal compatibility

The helper function create_decimal128_context creates a decimal.Context which ensures that decimals creted by the standard library are identical to those created by Decimal128.

>>> 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')

The to_decimal() method returns a decimal.Decimal object for the stored value.

Properties

bid(): → bytes

The binary integer decimal (BID) encoding of this instance. BIDs are 16 bytes with the highest bits encoded first:

>>> Decimal128("999").bid().hex()
'304000000000000000000000000003e7'
>>> Decimal128("NaN").bid().hex()
'7c000000000000000000000000000000'

Methods

from_bid(value: bytes)

Create an instance of Decimal128 from binary integer decimal bytes.

Parameters:

• value: 16 byte string (128-bit IEEE 754-2008 decimal floating point in binary integer decimal (BID) format).

is_infinite() → bool

Return True if self is infinite; otherwise return False.

is_nan() → bool

Return True if self is a NaN; otherwise return False.

is_signed() → bool

Return True if self is negative; otherwise return False.

to_decimal() -> decimal.Decimal

Returns an instance of decimal.Decimal for this Decimal128.

to_float() → float

Returns an instance of float for this Decimal128.

Performance

Decimal128 is considerably slower than decimal.Decimal using native libraries as all arithmetic operations involve creating new objects to perform the operation. Expect performance to be 200-300 times slower than decimal.Decimal.

Credits

decimal128 was built by Jon Connell but started as a fork of the decimal128 support found in the MondoDB python driver.

Tests are adapted from the MongoDB tests for decimal128 and also from John Dupuy's Nim implementation of decimal128.

License

This project is licensed under the Apache License 2.0.

Some tests are licensed under the MIT License which can be identified in the source comments.