Python/docs/3.9/library/decimal

decimal — 十进制定点和浮点运算

源代码： :source:`Lib/decimal.py`

---

decimal 模块支持快速正确舍入的十进制浮点运算。 与 float 数据类型相比，它具有以下几个优点：

• 十进制“基于浮点模型，该模型是为人而设计的，并且必然具有最重要的指导原则——计算机必须提供一种与人们在学校学习的算术相同的算术。” – 摘自十进制算术规范。

• 十进制数可以精确表示。 相比之下，像 1.1 和 2.2 这样的数字在二进制浮点数中没有精确的表示。 最终用户通常不希望 1.1 + 2.2 显示为 3.3000000000000003，因为它与二进制浮点数一样。

• 精确性延续到算术中。 在十进制浮点数中，0.1 + 0.1 + 0.1 - 0.3 正好等于零。 在二进制浮点中，结果是 5.5511151231257827e-017。 虽然接近于零，但差异阻止了可靠的相等性测试，并且差异可能会累积。 出于这个原因，十进制在具有严格等式不变量的会计应用程序中是首选。

• 十进制模块包含重要位置的概念，因此 1.30 + 1.20 是 2.50。 保留尾随零以指示重要性。 这是货币应用程序的惯用表示。 对于乘法，“教科书”方法使用被乘数中的所有数字。 例如，1.3 * 1.2 给出 1.56，而 1.30 * 1.20 给出 1.5600。

• 与基于硬件的二进制浮点数不同，decimal 模块具有用户可更改的精度（默认为 28 位），该精度可以根据给定问题的需要而定：

  >>> from decimal import *
  >>> getcontext().prec = 6
  >>> Decimal(1) / Decimal(7)
  Decimal('0.142857')
  >>> getcontext().prec = 28
  >>> Decimal(1) / Decimal(7)
  Decimal('0.1428571428571428571428571429')

  Copy

• 二进制和十进制浮点数都是根据已发布的标准实现的。 虽然内置 float 类型仅公开了其功能的一小部分，但 decimal 模块公开了标准的所有必需部分。 需要时，程序员可以完全控制舍入和信号处理。 这包括通过使用异常来阻止任何不精确操作来强制执行精确算术的选项。

• 十进制模块旨在支持“无偏见的精确未舍入十进制算术（有时称为定点算术）和舍入浮点算术”。 – 摘自十进制算术规范。

模块设计以三个概念为中心：十进制数、算术上下文和信号。

十进制数是不可变的。 它有一个符号、系数数字和一个指数。 为了保持显着性，系数数字不会截断尾随零。 小数还包括特殊值，例如 Infinity、-Infinity 和 NaN。 该标准还将 -0 与 +0 区分开来。

算术的上下文是指定精度、舍入规则、指数限制、指示运算结果的标志以及确定信号是否被视为异常的陷阱启动器的环境。 舍入选项包括 ROUND_CEILING、ROUND_DOWN、ROUND_FLOOR、ROUND_HALF_DOWN、ROUND_HALF_X64X1X1X1X14 、ROUND_UP 和 ROUND_05UP。

信号是在计算过程中出现的一组异常情况。 根据应用程序的需要，信号可能会被忽略，被视为信息，或被视为异常。 十进制模块中的信号有：Clamped、InvalidOperation、DivisionByZero、Inexact、Rounded、 ]次正常、溢出、下溢和FloatOperation。

对于每个信号，都有一个标志和一个陷阱使能器。 当遇到信号时，其标志设置为 1，然后，如果陷阱启用器设置为 1，则会引发异常。 标志是粘性的，因此用户需要在监视计算之前重置它们。

也可以看看

• IBM 的通用十进制算术规范，通用十进制算术规范。

快速入门教程

使用小数的通常开始是导入模块，使用 getcontext() 查看当前上下文，并在必要时为精度、舍入或启用陷阱设置新值：

>>> from decimal import *
>>> getcontext()
Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,
        InvalidOperation])

>>> getcontext().prec = 7       # Set a new precision

Copy

Decimal 实例可以由整数、字符串、浮点数或元组构成。 从整数或浮点数构造执行该整数或浮点数的值的精确转换。 十进制数包括特殊值，例如代表“非数字”的 NaN、正负 Infinity 和 -0：

>>> getcontext().prec = 28
>>> Decimal(10)
Decimal('10')
>>> Decimal('3.14')
Decimal('3.14')
>>> Decimal(3.14)
Decimal('3.140000000000000124344978758017532527446746826171875')
>>> Decimal((0, (3, 1, 4), -2))
Decimal('3.14')
>>> Decimal(str(2.0 ** 0.5))
Decimal('1.4142135623730951')
>>> Decimal(2) ** Decimal('0.5')
Decimal('1.414213562373095048801688724')
>>> Decimal('NaN')
Decimal('NaN')
>>> Decimal('-Infinity')
Decimal('-Infinity')

Copy

如果 FloatOperation 信号被捕获，构造函数中小数和浮点数的意外混合或排序比较会引发异常：

>>> c = getcontext()
>>> c.traps[FloatOperation] = True
>>> Decimal(3.14)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
>>> Decimal('3.5') < 3.7
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
>>> Decimal('3.5') == 3.5
True

Copy

3.3 版中的新功能。

新十进制的重要性仅由输入的位数决定。 上下文精度和舍入仅在算术运算期间起作用。

>>> getcontext().prec = 6
>>> Decimal('3.0')
Decimal('3.0')
>>> Decimal('3.1415926535')
Decimal('3.1415926535')
>>> Decimal('3.1415926535') + Decimal('2.7182818285')
Decimal('5.85987')
>>> getcontext().rounding = ROUND_UP
>>> Decimal('3.1415926535') + Decimal('2.7182818285')
Decimal('5.85988')

如果超出 C 版本的内部限制，则构造一个小数会引发 InvalidOperation：

>>> Decimal("1e9999999999999999999")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>]

Copy

在 3.3 版中更改。

Decimals 可以与 Python 的其他大部分内容很好地交互。 这是一个小十进制浮点飞行马戏团：

>>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()))
>>> max(data)
Decimal('9.25')
>>> min(data)
Decimal('0.03')
>>> sorted(data)
[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),
 Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]
>>> sum(data)
Decimal('19.29')
>>> a,b,c = data[:3]
>>> str(a)
'1.34'
>>> float(a)
1.34
>>> round(a, 1)
Decimal('1.3')
>>> int(a)
1
>>> a * 5
Decimal('6.70')
>>> a * b
Decimal('2.5058')
>>> c % a
Decimal('0.77')

一些数学函数也可用于 Decimal：

>>> getcontext().prec = 28
>>> Decimal(2).sqrt()
Decimal('1.414213562373095048801688724')
>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal('10').ln()
Decimal('2.302585092994045684017991455')
>>> Decimal('10').log10()
Decimal('1')

Copy

quantize() 方法将数字四舍五入为固定指数。 此方法对于经常将结果四舍五入到固定数量位置的货币应用程序很有用：

>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
Decimal('7.32')
>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
Decimal('8')

Copy

如上所示，getcontext() 函数访问当前上下文并允许更改设置。 这种方法可以满足大多数应用程序的需求。

对于更高级的工作，使用 Context() 构造函数创建备用上下文可能很有用。 要激活备用，请使用 setcontext() 函数。

根据标准，decimal 模块提供了两个随时可用的标准上下文，BasicContext 和 ExtendedContext。 前者对于调试特别有用，因为许多陷阱都已启用：

>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
>>> setcontext(myothercontext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857142857142857142857142857')

>>> ExtendedContext
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[], traps=[])
>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857143')
>>> Decimal(42) / Decimal(0)
Decimal('Infinity')

>>> setcontext(BasicContext)
>>> Decimal(42) / Decimal(0)
Traceback (most recent call last):
  File "<pyshell#143>", line 1, in -toplevel-
    Decimal(42) / Decimal(0)
DivisionByZero: x / 0

上下文还具有用于监视计算过程中遇到的异常情况的信号标志。 标志保持设置直到明确清除，因此最好在每组受监控计算之前使用 clear_flags() 方法清除标志。

>>> setcontext(ExtendedContext)
>>> getcontext().clear_flags()
>>> Decimal(355) / Decimal(113)
Decimal('3.14159292')
>>> getcontext()
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])

Copy

flags 条目显示 Pi 的有理近似值被四舍五入（超出上下文精度的数字被丢弃）并且结果不准确（一些被丢弃的数字是非零的） .

使用上下文的 traps 字段中的字典设置单个陷阱：

>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(0)
Decimal('Infinity')
>>> getcontext().traps[DivisionByZero] = 1
>>> Decimal(1) / Decimal(0)
Traceback (most recent call last):
  File "<pyshell#112>", line 1, in -toplevel-
    Decimal(1) / Decimal(0)
DivisionByZero: x / 0

大多数程序仅在程序开始时调整当前上下文一次。 而且，在许多应用程序中，通过在循环内进行一次强制转换，数据会被转换为 Decimal。 创建上下文集和小数后，程序的大部分处理数据与其他 Python 数字类型没有什么不同。

十进制对象

class decimal.Decimal(value='0', context=None)

根据 值 构造一个新的 Decimal 对象。

value 可以是整数、字符串、元组、float 或另一个 Decimal 对象。 如果没有给出 value，则返回 Decimal('0')。 如果 value 是一个字符串，它应该在去除前导和尾随空格字符以及整个下划线后符合十进制数字字符串语法：

sign           ::=  '+' | '-'
digit          ::=  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
indicator      ::=  'e' | 'E'
digits         ::=  digit [digit]...
decimal-part   ::=  digits '.' [digits] | ['.'] digits
exponent-part  ::=  indicator [sign] digits
infinity       ::=  'Infinity' | 'Inf'
nan            ::=  'NaN' [digits] | 'sNaN' [digits]
numeric-value  ::=  decimal-part [exponent-part] | infinity
numeric-string ::=  [sign] numeric-value | [sign] nan

Copy

在 digit 出现在上面的地方也允许使用其他 Unicode 十进制数字。 这些包括来自各种其他字母表的十进制数字（例如，阿拉伯-印度语和梵文数字）以及全角数字 '\uff10' 到 '\uff19'。

如果 value 是一个 元组 ，它应该具有三个分量，一个符号（0 为正或 1 为负），一个 元组 的数字和整数指数。 例如，Decimal((0, (1, 4, 1, 4), -3)) 返回 Decimal('1.414')。

如果 value 是 float，则二进制浮点值将无损地转换为其精确的十进制等效值。 这种转换通常需要 53 位或更多位的精度。 例如，Decimal(float('1.1')) 转换为 Decimal('1.100000000000000088817841970012523233890533447265625')。

context 精度不影响存储的位数。 这完全由 值 中的位数决定。 例如，即使上下文精度只有三个，Decimal('3.00000') 也会记录所有五个零。

context 参数的目的是确定如果 value 是格式错误的字符串，该怎么办。 如果上下文捕获 InvalidOperation，则会引发异常； 否则，构造函数返回一个新的 Decimal，其值为 NaN。

一旦构造，Decimal 对象是不可变的。

3.2 版更改： 现在允许构造函数的参数是 float 实例。

在 3.3 版中更改：如果设置了 FloatOperation 陷阱，则 float 参数会引发异常。 默认情况下，陷阱是关闭的。

3.6 版更改： 允许使用下划线进行分组，就像代码中的整数和浮点文字一样。

十进制浮点对象与其他内置数字类型共享许多属性，例如 float 和 int。 所有常用的数学运算和特殊方法都适用。 同样，十进制对象可以被复制、腌制、打印、用作字典键、用作集合元素、比较、排序和强制转换为另一种类型（例如 float 或 int） .

Decimal 对象的算术与整数和浮点数的算术之间存在一些细微差别。 当余数运算符 % 应用于 Decimal 对象时，结果的符号是 dividend 的符号而不是除数的符号：

>>> (-7) % 4
1
>>> Decimal(-7) % Decimal(4)
Decimal('-3')

Copy

整数除法运算符 // 的行为类似，返回真商的整数部分（向零截断）而不是其底，以保留通常的恒等式 x == (x // y) * y + x % y：

>>> -7 // 4
-2
>>> Decimal(-7) // Decimal(4)
Decimal('-1')

Copy

% 和 // 运算符实现了 remainder 和 divide-integer 操作（分别），如规范中所述。

在算术运算中，小数对象通常不能与浮点数或 fractions.Fraction 的实例组合：例如，尝试将 Decimal 添加到 float 将引发 TypeError。 但是，可以使用 Python 的比较运算符将 Decimal 实例 x 与另一个数字 y 进行比较。 这避免了在不同类型的数字之间进行相等比较时的混淆结果。

3.2 版更改： 现在完全支持 Decimal 实例和其他数字类型之间的混合类型比较。

除了标准的数字属性之外，十进制浮点对象还有许多专门的方法：

adjusted()

在移出系数最右边的数字后返回调整后的指数，直到只剩下前导数字：Decimal('321e+5').adjusted() 返回七。 用于确定最高有效数字相对于小数点的位置。

as_integer_ratio()

返回一对 (n, d) 整数，这些整数将给定的 Decimal 实例表示为分数，以最低项和正分母表示：

>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)

Copy

转换是准确的。 在无穷大上引发 OverflowError 并在 NaN 上引发 ValueError。

3.6 版中的新功能。

as_tuple()

返回数字的 命名元组 表示：DecimalTuple(sign, digits, exponent)。

canonical()

返回参数的规范编码。 目前，Decimal 实例的编码始终是规范的，因此此操作返回其参数不变。

compare(other, context=None)

比较两个 Decimal 实例的值。 compare() 返回一个 Decimal 实例，如果任一操作数为 NaN，则结果为 NaN：

a or b is a NaN  ==> Decimal('NaN')
a < b            ==> Decimal('-1')
a == b           ==> Decimal('0')
a > b            ==> Decimal('1')

Copy

compare_signal(other, context=None)

此操作与 compare() 方法相同，只是所有 NaN 都发出信号。 也就是说，如果两个操作数都不是信号 NaN，则任何安静的 NaN 操作数都被视为信号 NaN。

compare_total(other, context=None)

使用它们的抽象表示而不是它们的数值比较两个操作数。 类似于 compare() 方法，但结果给出了 Decimal 实例的总排序。 具有相同数值但不同表示形式的两个 Decimal 实例在此排序中比较不相等：

>>> Decimal('12.0').compare_total(Decimal('12'))
Decimal('-1')

Copy

Quiet 和 Signaling NaN 也包含在总排序中。 如果两个操作数具有相同的表示形式，则此函数的结果为 Decimal('0')，如果第一个操作数在总顺序中低于第二个，则为 Decimal('-1')，如果第一个操作数的顺序为 Decimal('1')操作数的总顺序高于第二个操作数。 有关总订单的详细信息，请参阅规范。

此操作不受上下文影响并且是安静的：不更改标志且不执行舍入。 作为一个例外，如果无法准确转换第二个操作数，C 版本可能会引发 InvalidOperation。

compare_total_mag(other, context=None)

使用它们的抽象表示而不是它们的值来比较两个操作数，如 compare_total()，但忽略每个操作数的符号。 x.compare_total_mag(y) 相当于 x.copy_abs().compare_total(y.copy_abs())。

此操作不受上下文影响并且是安静的：不更改标志且不执行舍入。 作为一个例外，如果无法准确转换第二个操作数，C 版本可能会引发 InvalidOperation。

conjugate()

只返回self，此方法仅符合Decimal Specification。

copy_abs()

返回参数的绝对值。 此操作不受上下文影响并且是安静的：不更改标志且不执行舍入。

copy_negate()

返回参数的否定。 此操作不受上下文影响并且是安静的：不更改标志且不执行舍入。

copy_sign(other, context=None)

返回第一个操作数的副本，其符号设置为与第二个操作数的符号相同。 例如：

>>> Decimal('2.3').copy_sign(Decimal('-1.5'))
Decimal('-2.3')

Copy

此操作不受上下文影响并且是安静的：不更改标志且不执行舍入。 作为一个例外，如果无法准确转换第二个操作数，C 版本可能会引发 InvalidOperation。

exp(context=None)

返回给定数字的（自然）指数函数 e**x 的值。 结果使用 ROUND_HALF_EVEN 舍入模式正确舍入。

>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal(321).exp()
Decimal('2.561702493119680037517373933E+139')

Copy

from_float(f)

准确地将浮点数转换为十进制数的类方法。

注意 Decimal.from_float(0.1) 与 Decimal('0.1') 不同。 由于 0.1 不能用二进制浮点精确表示，因此该值存储为最接近的可表示值，即 0x1.999999999999ap-4。 十进制的等效值是 0.1000000000000000055511151231257827021181583404541015625。

笔记

从 Python 3.2 开始，Decimal 实例也可以直接从 float 构造。

>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
>>> Decimal.from_float(float('nan'))
Decimal('NaN')
>>> Decimal.from_float(float('inf'))
Decimal('Infinity')
>>> Decimal.from_float(float('-inf'))
Decimal('-Infinity')

3.1 版中的新功能。

fma(other, third, context=None)

融合乘加。 返回 self*other+third ，中间产品 self*other 没有四舍五入。

>>> Decimal(2).fma(3, 5)
Decimal('11')

Copy

is_canonical()

如果参数是规范的，则返回 True，否则返回 False。 目前，Decimal 实例总是规范的，所以这个操作总是返回 True。

is_finite()

如果参数是有限数，则返回 True，如果参数是无穷大或 NaN，则返回 False。

is_infinite()

如果参数是正无穷大或负无穷大，则返回 True，否则返回 False。

is_nan()

如果参数是（安静或信号）NaN，则返回 True，否则返回 False。

is_normal(context=None)

如果参数是 normal 有限数，则返回 True。 如果参数为零、次正规、无穷大或 NaN，则返回 False。

is_qnan()

如果参数是安静的 NaN，则返回 True，否则返回 False。

is_signed()

如果参数有负号，则返回 True，否则返回 False。 请注意，零和 NaN 都可以带有符号。

is_snan()

如果参数是信号 NaN，则返回 True，否则返回 False。

is_subnormal(context=None)

如果参数不正常，则返回 True，否则返回 False。

is_zero()

如果参数是（正或负）零，则返回 True，否则返回 False。

ln(context=None)

返回操作数的自然（以 e 为底）对数。 结果使用 ROUND_HALF_EVEN 舍入模式正确舍入。

log10(context=None)

返回操作数的以 10 为底的对数。 结果使用 ROUND_HALF_EVEN 舍入模式正确舍入。

logb(context=None)

对于非零数，将其操作数的调整指数作为 Decimal 实例返回。 如果操作数为零，则返回 Decimal('-Infinity') 并引发 DivisionByZero 标志。 如果操作数是无穷大，则返回 Decimal('Infinity')。

logical_and(other, context=None)

logical_and() 是一个逻辑运算，它采用两个 逻辑操作数 （请参阅 逻辑操作数 ）。 结果是两个操作数的数字 and。

logical_invert(context=None)

logical_invert() 是逻辑运算。 结果是操作数的数字反转。

logical_or(other, context=None)

logical_or() 是一个逻辑运算，它采用两个 逻辑操作数 （请参阅 逻辑操作数 ）。 结果是两个操作数的数字 or。

logical_xor(other, context=None)

logical_xor() 是一个逻辑运算，它采用两个 逻辑操作数 （参见 逻辑操作数 ）。 结果是两个操作数的逐位异或。

max(other, context=None)

与 max(self, other) 类似，除了在返回之前应用上下文舍入规则，并且 NaN 值要么发出信号要么忽略（取决于上下文以及它们是发出信号还是静默）。

max_mag(other, context=None)

类似于 max() 方法，但比较是使用操作数的绝对值完成的。

min(other, context=None)

与 min(self, other) 类似，除了在返回之前应用上下文舍入规则，并且 NaN 值要么发出信号要么忽略（取决于上下文以及它们是发出信号还是静默）。

min_mag(other, context=None)

类似于 min() 方法，但比较是使用操作数的绝对值完成的。

next_minus(context=None)

返回在给定上下文（如果没有给定上下文，则在当前线程的上下文）中小于给定操作数的最大可表示数。

next_plus(context=None)

返回在给定上下文（如果没有给定上下文，则在当前线程的上下文）中大于给定操作数的可表示的最小数字。

next_toward(other, context=None)

如果两个操作数不相等，则返回在第二个操作数的方向上最接近第一个操作数的数字。 如果两个操作数在数值上相等，则返回第一个操作数的副本，其符号设置为与第二个操作数的符号相同。

normalize(context=None)

通过去除最右边的尾随零并将等于 Decimal('0') 的任何结果转换为 Decimal('0e0') 来标准化数字。 用于为等价类的属性生成规范值。 例如，Decimal('32.100') 和 Decimal('0.321000e+2') 都归一化为等效值 Decimal('32.1')。

number_class(context=None)

返回描述操作数的 类 的字符串。 返回值是以下十个字符串之一。

• "-Infinity"，表示操作数为负无穷大。

• "-Normal"，表示操作数为负数。

• "-Subnormal"，表示操作数为负数，次正规。

• "-Zero"，表示操作数为负零。

• "+Zero"，表示操作数为正零。

• "+Subnormal"，表示操作数为正，次正规。

• "+Normal"，表示操作数为正数。

• "+Infinity"，表示操作数为正无穷大。

• "NaN"，表示操作数是一个安静的 NaN（Not a Number）。

• "sNaN"，表示操作数为信令NaN。

quantize(exp, rounding=None, context=None)

在舍入并具有第二个操作数的指数后返回等于第一个操作数的值。

>>> Decimal('1.41421356').quantize(Decimal('1.000'))
Decimal('1.414')

Copy

与其他操作不同，如果量化操作后系数的长度大于精度，则会发出 InvalidOperation 信号。 这保证了除非出现错误条件，否则量化指数始终等于右侧操作数的指数。

同样与其他操作不同的是，量化从不发出下溢信号，即使结果不正常且不准确。

如果第二个操作数的指数大于第一个的指数，则可能需要舍入。 在这种情况下，舍入模式由 rounding 参数决定，否则由 context 参数决定； 如果两个参数都没有给出，则使用当前线程上下文的舍入模式。

只要结果指数大于 Emax 或小于 Etiny，就会返回错误。

radix()

返回 Decimal(10)，Decimal 类执行其所有算术的基数（基数）。 包括在内是为了与规范兼容。

remainder_near(other, context=None)

返回将 self 除以 other 的余数。 这与 self % other 的不同之处在于余数的符号被选择为使其绝对值最小。 更准确地说，返回值是 self - n * other，其中 n 是最接近 self / other 确切值的整数，如果两个整数相等，则选择偶数。

如果结果为零，则其符号将是 self 的符号。

>>> Decimal(18).remainder_near(Decimal(10))
Decimal('-2')
>>> Decimal(25).remainder_near(Decimal(10))
Decimal('5')
>>> Decimal(35).remainder_near(Decimal(10))
Decimal('-5')

Copy

rotate(other, context=None)

返回按第二个操作数指定的量旋转第一个操作数的数字的结果。 第二个操作数必须是从 -precision 到 precision 范围内的整数。 第二个操作数的绝对值给出了要旋转的位置数。 如果第二个操作数为正，则向左旋转； 否则向右旋转。 如有必要，第一个操作数的系数在左侧填充零以达到长度精度。 第一个操作数的符号和指数不变。

same_quantum(other, context=None)

测试 self 和 other 是否具有相同的指数或两者是否都是 NaN。

此操作不受上下文影响并且是安静的：不更改标志且不执行舍入。 作为一个例外，如果无法准确转换第二个操作数，C 版本可能会引发 InvalidOperation。

scaleb(other, context=None)

返回第一个操作数，其指数由第二个调整。 等效地，返回乘以 10**other 的第一个操作数。 第二个操作数必须是整数。

shift(other, context=None)

返回按第二个操作数指定的量移动第一个操作数的数字的结果。 第二个操作数必须是从 -precision 到 precision 范围内的整数。 第二个操作数的绝对值给出了要移位的位数。 如果第二个操作数为正，则向左移位； 否则向右移动。 移入系数的数字为零。 第一个操作数的符号和指数不变。

sqrt(context=None)

将参数的平方根返回到全精度。

to_eng_string(context=None)

如果需要指数，则使用工程符号转换为字符串。

工程符号的指数是 3 的倍数。 这最多可以在小数位左侧留下 3 位数字，并且可能需要添加一个或两个尾随零。

例如，这将 Decimal('123E+1') 转换为 Decimal('1.23E+3')。

to_integral(rounding=None, context=None)

与 to_integral_value() 方法相同。 保留 to_integral 名称是为了与旧版本兼容。

to_integral_exact(rounding=None, context=None)

舍入到最接近的整数，如果发生舍入，则根据需要发出 不精确 或 舍入 信号。 如果给定，舍入模式由 rounding 参数确定，否则由给定的 context 确定。 如果没有给出参数，则使用当前上下文的舍入模式。

to_integral_value(rounding=None, context=None)

舍入到最接近的整数而不用信号 Inexact 或 Rounded。 如果给定，则应用 rounding; 否则，在提供的 context 或当前上下文中使用舍入方法。

逻辑操作数

logical_and()、logical_invert()、logical_or() 和 logical_xor() 方法期望它们的参数是 逻辑操作数 。 逻辑操作数是一个Decimal实例，其指数和符号都为零，并且其数字都是0或1。

上下文对象

上下文是算术运算的环境。 它们控制精度、设置舍入规则、确定哪些信号被视为例外，并限制指数的范围。

每个线程都有自己的当前上下文，可以使用 getcontext() 和 setcontext() 函数访问或更改：

decimal.getcontext()

返回活动线程的当前上下文。

decimal.setcontext(c)

将活动线程的当前上下文设置为 c。

您还可以使用 with 语句和 localcontext() 函数来临时更改活动上下文。

decimal.localcontext(ctx=None)

返回一个上下文管理器，它将在进入 with-语句时将活动线程的当前上下文设置为 ctx 的副本，并在退出 with-语句时恢复先前的上下文。 如果未指定上下文，则使用当前上下文的副本。

例如，下面的代码将当前的十进制精度设置为 42 位，执行一次计算，然后自动恢复之前的上下文：

from decimal import localcontext

with localcontext() as ctx:
    ctx.prec = 42   # Perform a high precision calculation
    s = calculate_something()
s = +s  # Round the final result back to the default precision

Copy

也可以使用下面描述的 Context 构造函数创建新的上下文。 此外，该模块还提供了三个预制上下文：

class decimal.BasicContext

这是通用十进制算术规范定义的标准上下文。 精度设置为九。 舍入设置为 ROUND_HALF_UP。 清除所有标志。 除了 Inexact、Rounded 和 Subnormal 之外，所有陷阱都已启用（视为例外）。

由于启用了许多陷阱，因此此上下文可用于调试。

class decimal.ExtendedContext

这是通用十进制算术规范定义的标准上下文。 精度设置为九。 舍入设置为 ROUND_HALF_EVEN。 清除所有标志。 没有启用陷阱（因此在计算过程中不会引发异常）。

由于陷阱被禁用，此上下文对于更喜欢具有 NaN 或 Infinity 结果值而不是引发异常的应用程序很有用。 这允许应用程序在存在可能停止程序的情况下完成运行。

class decimal.DefaultContext

Context 构造函数使用此上下文作为新上下文的原型。 更改字段（如精度）会更改由 Context 构造函数创建的新上下文的默认值。

此上下文在多线程环境中最有用。 在线程启动之前更改字段之一具有设置系统范围默认值的效果。 不建议在线程启动后更改字段，因为它需要线程同步以防止竞争条件。

在单线程环境中，最好根本不使用此上下文。 相反，只需如下所述显式地创建上下文。

默认值为 prec=28、rounding=ROUND_HALF_EVEN，并为 Overflow、InvalidOperation 启用陷阱X141X] 和 DivisionByZero。

除了提供的三个上下文之外，还可以使用 Context 构造函数创建新的上下文。

class decimal.Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None)

创建一个新的上下文。 如果字段未指定或为 None，则从 DefaultContext 复制默认值。 如果 flags 字段未指定或为 None，则清除所有标志。

prec 是 [1, MAX_PREC] 范围内的整数，用于设置上下文中算术运算的精度。

rounding 选项是 Rounding Modes 部分中列出的常量之一。

traps 和 flags 字段列出了要设置的任何信号。 通常，新上下文应该只设置陷阱并清除标志。

Emin 和 Emax 字段是指定指数允许的外部限制的整数。 Emin 必须在 [MIN_EMIN、0]、Emax 范围内 [0、 范围内MAX_EMAX]。

capitals 字段是 0 或 1（默认值）。 如果设置为 1，指数以大写 E 打印； 否则，使用小写 e：Decimal('6.02e+23')。

clamp 字段是 0（默认值）或 1。 如果设置为 1，则在此上下文中可表示的 Decimal 实例的指数 e 严格限制在 Emin - prec + 1 <= e <= Emax - prec + 1 范围内。 如果 clamp 是 0，那么一个较弱的条件成立：Decimal 实例的调整指数至多是 Emax。 当 clamp 为 1 时，一个大的正常数将尽可能减少其指数并在其系数中添加相应数量的零，以适应指数约束； 这会保留数字的值，但会丢失有关重要尾随零的信息。 例如：

>>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')
Decimal('1.23000E+999')

Copy

1 的 clamp 值允许与 IEEE 754 中指定的固定宽度十进制交换格式兼容。

Context 类定义了几个通用方法以及大量直接在给定上下文中进行算术的方法。 此外，对于上述每个 Decimal 方法（adjusted() 和 as_tuple() 方法除外），都有一个对应的 Context 方法. 例如，对于 Context 实例 C 和 Decimal 实例 x，C.exp(x) 等价于 x.exp(context=C) . 每个 Context 方法都接受一个 Python 整数（int 的一个实例），只要接受 Decimal 实例。

clear_flags()

将所有标志重置为 0。

clear_traps()

将所有陷阱重置为 0。

3.3 版中的新功能。

copy()

返回上下文的副本。

copy_decimal(num)

返回 Decimal 实例 num 的副本。

create_decimal(num)

从 num 创建一个新的 Decimal 实例，但使用 self 作为上下文。 与 Decimal 构造函数不同，上下文精度、舍入方法、标志和陷阱应用于转换。

这很有用，因为常量的精度通常高于应用程序所需的精度。 另一个好处是四舍五入可以立即消除超出当前精度的数字的意外影响。 在以下示例中，使用未舍入的输入意味着将零添加到总和可以更改结果：

>>> getcontext().prec = 3
>>> Decimal('3.4445') + Decimal('1.0023')
Decimal('4.45')
>>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
Decimal('4.44')

该方法实现了IBM 规范的to-number 操作。 如果参数是字符串，则不允许前导或尾随空格或下划线。

create_decimal_from_float(f)

从浮点数 f 创建一个新的 Decimal 实例，但使用 self 作为上下文进行舍入。 与 Decimal.from_float() 类方法不同，上下文精度、舍入方法、标志和陷阱应用于转换。

>>> context = Context(prec=5, rounding=ROUND_DOWN)
>>> context.create_decimal_from_float(math.pi)
Decimal('3.1415')
>>> context = Context(prec=5, traps=[Inexact])
>>> context.create_decimal_from_float(math.pi)
Traceback (most recent call last):
    ...
decimal.Inexact: None

3.1 版中的新功能。

Etiny()

返回一个等于 Emin - prec + 1 的值，这是次正规结果的最小指数值。 发生下溢时，指数设置为 Etiny。

Etop()

返回一个等于 Emax - prec + 1 的值。

处理小数的常用方法是创建 Decimal 实例，然后应用在活动线程的当前上下文中发生的算术运算。 另一种方法是使用上下文方法在特定上下文中进行计算。 这些方法类似于 Decimal 类的方法，这里只简要介绍。

abs(x)

返回 x 的绝对值。

add(x, y)

返回 x 和 y 的和。

canonical(x)

返回相同的 Decimal 对象 x。

compare(x, y)

在数值上比较 x 和 y。

compare_signal(x, y)

以数字方式比较两个操作数的值。

compare_total(x, y)

使用抽象表示比较两个操作数。

compare_total_mag(x, y)

使用抽象表示比较两个操作数，忽略符号。

copy_abs(x)

返回符号设置为 0 的 x 的副本。

copy_negate(x)

返回符号反转的 x 的副本。

copy_sign(x, y)

将符号从 y 复制到 x。

divide(x, y)

返回 x 除以 y。

divide_int(x, y)

返回 x 除以 y，截断为整数。

divmod(x, y)

将两个数字相除并返回结果的整数部分。

exp(x)

返回 e ** x。

fma(x, y, z)

返回 x 乘以 y，再加上 z。

is_canonical(x)

如果 x 是规范的，则返回 True； 否则返回 False。

is_finite(x)

如果 x 是有限的，则返回 True； 否则返回 False。

is_infinite(x)

如果 x 是无限的，则返回 True； 否则返回 False。

is_nan(x)

如果 x 是 qNaN 或 sNaN，则返回 True； 否则返回 False。

is_normal(x)

如果 x 是正常数，则返回 True； 否则返回 False。

is_qnan(x)

如果 x 是一个安静的 NaN，则返回 True； 否则返回 False。

is_signed(x)

如果 x 为负，则返回 True； 否则返回 False。

is_snan(x)

如果 x 是信号 NaN，则返回 True； 否则返回 False。

is_subnormal(x)

如果 x 低于正常值，则返回 True； 否则返回 False。

is_zero(x)

如果 x 为零，则返回 True； 否则返回 False。

ln(x)

返回 x 的自然（以 e 为底）对数。

log10(x)

返回 x 的以 10 为底的对数。

logb(x)

返回操作数的 MSD 大小的指数。

logical_and(x, y)

在每个操作数的数字之间应用逻辑运算 和 。

logical_invert(x)

反转 x 中的所有数字。

logical_or(x, y)

在每个操作数的数字之间应用逻辑运算 或 。

logical_xor(x, y)

在每个操作数的数字之间应用逻辑运算 xor。

max(x, y)

以数字方式比较两个值并返回最大值。

max_mag(x, y)

以数字方式比较值，忽略其符号。

min(x, y)

以数字方式比较两个值并返回最小值。

min_mag(x, y)

以数字方式比较值，忽略其符号。

minus(x)

减号对应于 Python 中的一元前缀减号运算符。

multiply(x, y)

返回 x 和 y 的乘积。

next_minus(x)

返回小于 x 的最大可表示数。

next_plus(x)

返回大于 x 的最小可表示数字。

next_toward(x, y)

返回最接近 x 的数字，方向为 y。

normalize(x)

将 x 简化为最简单的形式。

number_class(x)

返回 x 类的指示。

plus(x)

加号对应于 Python 中的一元前缀加号运算符。 此操作应用上下文精度和舍入，因此它是 不是 身份操作。

power(x, y, modulo=None)

将 x 返回到 y 的幂，如果给定，则减少模 modulo。

使用两个参数，计算 x**y。 如果 x 为负，则 y 必须是整数。 结果将是不精确的，除非 y 是整数并且结果是有限的并且可以精确地用“精度”数字表示。 使用上下文的舍入模式。 结果在 Python 版本中总是正确四舍五入。

Decimal(0) ** Decimal(0) 导致 InvalidOperation，如果 InvalidOperation 未被捕获，则导致 Decimal('NaN')。

3.3 版更改：C 模块根据正确舍入的 exp() 和 ln() 计算 power()职能。 结果是明确定义的，但只是“几乎总是正确四舍五入”。

使用三个参数，计算 (x**y) % modulo。 对于三参数形式，对参数的以下限制成立：

• 所有三个参数都必须是整数

• y 必须为非负

• x 或 y 中的至少一个必须是非零值

• modulo 必须为非零且最多为“精度”数字

由 Context.power(x, y, modulo) 产生的值等于通过以无限精度计算 (x**y) % modulo 获得的值，但计算效率更高。 结果的指数为零，与 x、y 和 modulo 的指数无关。 结果总是准确的。

quantize(x, y)

返回一个等于 x（四舍五入）的值，其指数为 y。

radix()

只返回 10，因为这是十进制，:)

remainder(x, y)

返回整数除法的余数。

结果的符号（如果非零）与原始被除数的符号相同。

remainder_near(x, y)

返回 x - y * n，其中 n 是最接近 x / y 精确值的整数（如果结果为 0，则其符号将是 x 的符号]）。

rotate(x, y)

返回 x、y 次的旋转副本。

same_quantum(x, y)

如果两个操作数具有相同的指数，则返回 True。

scaleb(x, y)

将第二个值与 exp 相加后返回第一个操作数。

shift(x, y)

返回 x、y 次的移位副本。

sqrt(x)

非负数的平方根到上下文精度。

subtract(x, y)

返回 x 和 y 之间的差值。

to_eng_string(x)

如果需要指数，则使用工程符号转换为字符串。

工程符号的指数是 3 的倍数。 这最多可以在小数位左侧留下 3 位数字，并且可能需要添加一个或两个尾随零。

to_integral_exact(x)

舍入为整数。

to_sci_string(x)

使用科学记数法将数字转换为字符串。

常数

本节中的常量仅与 C 模块相关。 为了兼容性，它们也包含在纯 Python 版本中。

	32 位	64 位
decimal.MAX_PREC	425000000	999999999999999999
decimal.MAX_EMAX	425000000	999999999999999999
decimal.MIN_EMIN	-425000000	-999999999999999999
decimal.MIN_ETINY	-849999999	-1999999999999999997

decimal.HAVE_THREADS

值为 True。 已弃用，因为 Python 现在总是有线程。

自 3.9 版起已弃用。

decimal.HAVE_CONTEXTVAR

默认值为 True。 如果 Python 编译为 --without-decimal-contextvar，则 C 版本使用线程本地而不是协程本地上下文，值为 False。 在某些嵌套上下文场景中，这会稍微快一些。

3.9 版新功能： 向后移植到 3.7 和 3.8。

舍入模式

decimal.ROUND_CEILING

朝 Infinity 舍入。

decimal.ROUND_DOWN

向零舍入。

decimal.ROUND_FLOOR

朝 -Infinity 舍入。

decimal.ROUND_HALF_DOWN

舍入到最接近的关系，并趋向于零。

decimal.ROUND_HALF_EVEN

舍入到最接近的关系到最接近的偶数整数。

decimal.ROUND_HALF_UP

舍入到最接近的关系，从零开始。

decimal.ROUND_UP

从零舍入。

decimal.ROUND_05UP

如果向零舍入后的最后一位数字是 0 或 5，则从零舍入； 否则向零舍入。

信号

信号表示计算过程中出现的条件。 每个对应一个上下文标志和一个上下文陷阱启动器。

每当遇到条件时都会设置上下文标志。 在计算之后，可以出于信息目的检查标志（例如，以确定计算是否准确）。 检查标志后，请务必在开始下一次计算之前清除所有标志。

如果为信号设置了上下文的陷阱启用程序，则该条件会导致引发 Python 异常。 例如，如果设置了 DivisionByZero 陷阱，则在遇到该条件时会引发 DivisionByZero 异常。

class decimal.Clamped

更改了指数以适应表示约束。

通常，当指数超出上下文的 Emin 和 Emax 限制时，就会发生钳位。 如果可能，通过向系数添加零来减小指数以适合。

class decimal.DecimalException

其他信号的基类和 ArithmeticError 的子类。

class decimal.DivisionByZero

表示非无限数除以零。

可以与除法、模除法一起发生，或者在将一个数字提高到负幂时发生。 如果该信号未被捕获，则返回 Infinity 或 -Infinity，其符号由计算输入确定。

class decimal.Inexact

表示发生了舍入并且结果不准确。

在舍入期间丢弃非零数字时的信号。 返回四舍五入的结果。 信号标志或陷阱用于检测结果何时不准确。

class decimal.InvalidOperation

执行了无效的操作。

表示请求的操作没有意义。 如果没有被捕获，则返回 NaN。 可能的原因包括：

Infinity - Infinity
0 * Infinity
Infinity / Infinity
x % 0
Infinity % x
sqrt(-x) and x > 0
0 ** 0
x ** (non-integer)
x ** Infinity

Copy

class decimal.Overflow

数值溢出。

表示在发生舍入后指数大于 Emax。 如果没有被困，结果取决于舍入模式，要么向内拉到最大的可表示有限数，要么向外舍入到 Infinity。 在任何一种情况下，Inexact 和 Rounded 也会发出信号。

class decimal.Rounded

尽管可能没有信息丢失，但发生了舍入。

每当舍入丢弃数字时发出信号； 即使这些数字为零（例如将 5.00 舍入为 5.0）。 如果没有被捕获，则返回结果不变。 该信号用于检测有效数字的丢失。

class decimal.Subnormal

在四舍五入之前，指数低于 Emin。

当运算结果不正常（指数太小）时发生。 如果没有被捕获，则返回结果不变。

class decimal.Underflow

数值下溢，结果四舍五入为零。

在通过四舍五入将次正规结果推到零时发生。 不精确 和 次正常 也会发出信号。

class decimal.FloatOperation

为混合浮点数和小数启用更严格的语义。

如果信号未被捕获（默认），则允许在 Decimal 构造函数、create_decimal() 和所有比较运算符中混合浮点数和小数。 转换和比较都是精确的。 通过在上下文标志中设置 FloatOperation 来静默记录混合操作的任何发生。 使用 from_float() 或 create_decimal_from_float() 的显式转换不设置标志。

否则（信号被捕获），只有相等比较和显式转换是静默的。 所有其他混合操作引发 FloatOperation。

下表总结了信号的层次结构：

exceptions.ArithmeticError(exceptions.Exception)
    DecimalException
        Clamped
        DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
        Inexact
            Overflow(Inexact, Rounded)
            Underflow(Inexact, Rounded, Subnormal)
        InvalidOperation
        Rounded
        Subnormal
        FloatOperation(DecimalException, exceptions.TypeError)

Copy

浮点注释

以更高的精度减少舍入误差

十进制浮点数的使用消除了十进制表示错误（可以准确表示0.1）； 但是，当非零数字超过固定精度时，某些操作仍然会产生舍入误差。

舍入误差的影响可以通过增加或减少几乎抵消的量而放大，从而导致显着性损失。 Knuth 提供了两个有启发性的例子，其中精度不足的舍入浮点运算会导致加法的关联和分配属性崩溃：

# Examples from Seminumerical Algorithms, Section 4.2.2.
>>> from decimal import Decimal, getcontext
>>> getcontext().prec = 8

>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.5111111')
>>> u + (v + w)
Decimal('10')

>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.01')
>>> u * (v+w)
Decimal('0.0060000')

decimal 模块可以通过充分扩展精度来恢复身份，以避免丢失重要性：

>>> getcontext().prec = 20
>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.51111111')
>>> u + (v + w)
Decimal('9.51111111')
>>>
>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.0060000')
>>> u * (v+w)
Decimal('0.0060000')

特殊值

decimal 模块的数字系统提供了特殊值，包括 NaN、sNaN、-Infinity、Infinity 和两个零，[ X143X] 和 -0。

无穷大可以直接构造为：Decimal('Infinity')。 此外，当 DivisionByZero 信号未被捕获时，它们可能由除以零引起。 同样，当 Overflow 信号未被捕获时，四舍五入可能会导致超出最大可表示数限制的无穷大。

无穷大是有符号的（仿射），可用于算术运算，将它们视为非常大的不确定数。 例如，向无穷大添加一个常数会得到另一个无穷大的结果。

某些操作不确定并返回 NaN，或者如果 InvalidOperation 信号被捕获，则引发异常。 例如，0/0 返回 NaN，表示“不是数字”。 这种 NaN 是安静的，一旦创建，将通过其他计算始终产生另一个 NaN。 此行为对于偶尔丢失输入的一系列计算很有用 - 它允许计算继续进行，同时将特定结果标记为无效。

一个变体是 sNaN，它在每次操作后发出信号而不是保持安静。 当无效结果需要中断计算以进行特殊处理时，这是一个有用的返回值。

当涉及到 NaN 时，Python 的比较运算符的行为可能有点令人惊讶。 其中一个操作数是安静或信号 NaN 的相等性测试总是返回 False（即使在执行 Decimal('NaN')==Decimal('NaN') 时），而不等性测试总是返回 ]真。 尝试使用 <、<=、> 或 >= 运算符中的任何一个来比较两个小数将引发 InvalidOperation 信号，如果任一操作数是 NaN，如果该信号未被捕获，则返回 False。 请注意，通用十进制算术规范没有指定直接比较的行为； 这些涉及 NaN 的比较规则取自 IEEE 854 标准（参见第 5.7 节中的表 3）。 为确保严格遵守标准，请改用 compare() 和 compare-signal() 方法。

带符号的零可能来自下溢的计算。 如果计算的精度更高，他们会保留会产生的符号。 由于它们的大小为零，因此正零和负零都被视为相等，并且它们的符号是信息性的。

除了两个不同但相等的有符号零之外，还有各种具有不同精度但值相等的零表示。 这需要一点习惯。 对于习惯于归一化浮点表示的眼睛来说，下面的计算返回一个等于零的值并不是很明显：

>>> 1 / Decimal('Infinity')
Decimal('0E-1000026')

Copy

使用线程

getcontext() 函数为每个线程访问不同的 Context 对象。 拥有单独的线程上下文意味着线程可以在不干扰其他线程的情况下进行更改（例如 getcontext().prec=10）。

同样，setcontext() 函数自动将其目标分配给当前线程。

如果 setcontext() 在 getcontext() 之前没有被调用，那么 getcontext() 将自动创建一个新的上下文以供当前线程使用。

新的上下文是从名为 DefaultContext 的原型上下文中复制的。 要控制默认值以便每个线程在整个应用程序中使用相同的值，请直接修改 DefaultContext 对象。 这应该在 任何线程启动之前完成 ，以便在调用 getcontext() 的线程之间不会出现竞争条件。 例如：

# Set applicationwide defaults for all threads about to be launched
DefaultContext.prec = 12
DefaultContext.rounding = ROUND_DOWN
DefaultContext.traps = ExtendedContext.traps.copy()
DefaultContext.traps[InvalidOperation] = 1
setcontext(DefaultContext)

# Afterwards, the threads can be started
t1.start()
t2.start()
t3.start()
 . . .

Copy

食谱

以下是一些用作实用函数并演示使用 Decimal 类的方法的方法：

def moneyfmt(value, places=2, curr='', sep=',', dp='.',
             pos='', neg='-', trailneg=''):
    """Convert Decimal to a money formatted string.

    places:  required number of places after the decimal point
    curr:    optional currency symbol before the sign (may be blank)
    sep:     optional grouping separator (comma, period, space, or blank)
    dp:      decimal point indicator (comma or period)
             only specify as blank when places is zero
    pos:     optional sign for positive numbers: '+', space or blank
    neg:     optional sign for negative numbers: '-', '(', space or blank
    trailneg:optional trailing minus indicator:  '-', ')', space or blank

    >>> d = Decimal('-1234567.8901')
    >>> moneyfmt(d, curr='$')
    '-$1,234,567.89'
    >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
    '1.234.568-'
    >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
    '($1,234,567.89)'
    >>> moneyfmt(Decimal(123456789), sep=' ')
    '123 456 789.00'
    >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
    '<0.02>'

    """
    q = Decimal(10) ** -places      # 2 places --> '0.01'
    sign, digits, exp = value.quantize(q).as_tuple()
    result = []
    digits = list(map(str, digits))
    build, next = result.append, digits.pop
    if sign:
        build(trailneg)
    for i in range(places):
        build(next() if digits else '0')
    if places:
        build(dp)
    if not digits:
        build('0')
    i = 0
    while digits:
        build(next())
        i += 1
        if i == 3 and digits:
            i = 0
            build(sep)
    build(curr)
    build(neg if sign else pos)
    return ''.join(reversed(result))

def pi():
    """Compute Pi to the current precision.

    >>> print(pi())
    3.141592653589793238462643383

    """
    getcontext().prec += 2  # extra digits for intermediate steps
    three = Decimal(3)      # substitute "three=3.0" for regular floats
    lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
    while s != lasts:
        lasts = s
        n, na = n+na, na+8
        d, da = d+da, da+32
        t = (t * n) / d
        s += t
    getcontext().prec -= 2
    return +s               # unary plus applies the new precision

def exp(x):
    """Return e raised to the power of x.  Result type matches input type.

    >>> print(exp(Decimal(1)))
    2.718281828459045235360287471
    >>> print(exp(Decimal(2)))
    7.389056098930650227230427461
    >>> print(exp(2.0))
    7.38905609893
    >>> print(exp(2+0j))
    (7.38905609893+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num = 0, 0, 1, 1, 1
    while s != lasts:
        lasts = s
        i += 1
        fact *= i
        num *= x
        s += num / fact
    getcontext().prec -= 2
    return +s

def cos(x):
    """Return the cosine of x as measured in radians.

    The Taylor series approximation works best for a small value of x.
    For larger values, first compute x = x % (2 * pi).

    >>> print(cos(Decimal('0.5')))
    0.8775825618903727161162815826
    >>> print(cos(0.5))
    0.87758256189
    >>> print(cos(0.5+0j))
    (0.87758256189+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
    while s != lasts:
        lasts = s
        i += 2
        fact *= i * (i-1)
        num *= x * x
        sign *= -1
        s += num / fact * sign
    getcontext().prec -= 2
    return +s

def sin(x):
    """Return the sine of x as measured in radians.

    The Taylor series approximation works best for a small value of x.
    For larger values, first compute x = x % (2 * pi).

    >>> print(sin(Decimal('0.5')))
    0.4794255386042030002732879352
    >>> print(sin(0.5))
    0.479425538604
    >>> print(sin(0.5+0j))
    (0.479425538604+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
    while s != lasts:
        lasts = s
        i += 2
        fact *= i * (i-1)
        num *= x * x
        sign *= -1
        s += num / fact * sign
    getcontext().prec -= 2
    return +s

Copy

十进制常见问题

问。 输入decimal.Decimal('1234.5')很麻烦。 有没有办法在使用交互式解释器时尽量减少打字？

1. 一些用户将构造函数缩写为一个字母：

   >>> D = decimal.Decimal
   >>> D('1.23') + D('3.45')
   Decimal('4.68')

   Copy

问。 在有两位小数的定点应用中，有些输入有很多位，需要四舍五入。 其他人不应该有多余的数字，需要进行验证。 应该使用哪些方法？

一种。 quantize() 方法四舍五入到固定的小数位数。 如果设置了 Inexact 陷阱，它也可用于验证：

>>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')

Copy

>>> # Round to two places
>>> Decimal('3.214').quantize(TWOPLACES)
Decimal('3.21')

Copy

>>> # Validate that a number does not exceed two places
>>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Decimal('3.21')

Copy

>>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Traceback (most recent call last):
   ...
Inexact: None

Copy

问。 一旦我有有效的两个地方输入，我如何在整个应用程序中保持不变？

一种。 一些运算，如加法、减法和乘以整数会自动保留不动点。 其他运算，如除法和非整数乘法，会改变小数位数，需要跟上 quantize() 步：

>>> a = Decimal('102.72')           # Initial fixed-point values
>>> b = Decimal('3.17')
>>> a + b                           # Addition preserves fixed-point
Decimal('105.89')
>>> a - b
Decimal('99.55')
>>> a * 42                          # So does integer multiplication
Decimal('4314.24')
>>> (a * b).quantize(TWOPLACES)     # Must quantize non-integer multiplication
Decimal('325.62')
>>> (b / a).quantize(TWOPLACES)     # And quantize division
Decimal('0.03')

Copy

在开发定点应用时，可以方便地定义处理quantize()步骤的函数：

>>> def mul(x, y, fp=TWOPLACES):
...     return (x * y).quantize(fp)
>>> def div(x, y, fp=TWOPLACES):
...     return (x / y).quantize(fp)

Copy

>>> mul(a, b)                       # Automatically preserve fixed-point
Decimal('325.62')
>>> div(b, a)
Decimal('0.03')

Copy

问。 有很多方法可以表达相同的值。 数字 200、200.000、2E2 和 02E+4 在不同的精度下都具有相同的值。 有没有办法将它们转换为单个可识别的规范值？

一种。 normalize() 方法将所有等效值映射到单个代表：

>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
>>> [v.normalize() for v in values]
[Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]

Copy

问。 一些十进制值总是用指数表示法打印。 有没有办法获得非指数表示？

一种。 对于某些值，指数表示法是表示系数中重要位置数的唯一方法。 例如，将 5.0E+3 表示为 5000 可以保持值不变，但不能显示原始的两位重要性。

如果应用程序不关心跟踪重要性，则很容易删除指数和尾随零，失去重要性，但保持值不变：

>>> def remove_exponent(d):
...     return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()

Copy

>>> remove_exponent(Decimal('5E+3'))
Decimal('5000')

Copy

17. 有没有办法将常规浮点数转换为 十进制 ？

一种。 是的，任何二进制浮点数都可以精确地表示为十进制，尽管精确转换可能比直觉所建议的精度更高：

>>> Decimal(math.pi)
Decimal('3.141592653589793115997963468544185161590576171875')

问。 在复杂的计算中，我如何确保我没有因为精度不足或四舍五入异常而得到虚假结果。

一种。 十进制模块使测试结果变得容易。 最佳做法是使用更高的精度和各种舍入模式重新运行计算。 差异很大的结果表明精度不足、舍入模式问题、病态输入或数值不稳定的算法。

问。 我注意到上下文精度应用于操作的结果而不是输入。 混合不同精度的值时有什么需要注意的吗？

一种。 是的。 原则是所有值都被认为是精确的，对这些值的算术也是如此。 只对结果进行四舍五入。 输入的优点是“你输入的就是你得到的”。 一个缺点是，如果您忘记输入尚未四舍五入，结果可能看起来很奇怪：

>>> getcontext().prec = 3
>>> Decimal('3.104') + Decimal('2.104')
Decimal('5.21')
>>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
Decimal('5.20')

解决方案是提高精度或使用一元加运算强制舍入输入：

>>> getcontext().prec = 3
>>> +Decimal('1.23456789')      # unary plus triggers rounding
Decimal('1.23')

或者，可以使用 Context.create_decimal() 方法在创建时舍入输入：

>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
Decimal('1.2345')

Copy

17. CPython 实现对于大量数据是否快速？

一种。 是的。 在 CPython 和 PyPy3 实现中，十进制模块的 C/CFFI 版本集成了高速 libmpdec 库，用于任意精度的正确舍入十进制浮点运算 1。 libmpdec 使用 Karatsuba 乘法 处理中等大小的数字，使用 数论变换 处理非常大的数字。

上下文必须适用于精确的任意精度算术。 Emin 和 Emax 应始终设置为最大值，clamp 应始终为 0（默认值）。 设置 prec 需要小心。

尝试 bignum 算法的最简单方法是使用 prec 和 2 的最大值：

>>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))
>>> x = Decimal(2) ** 256
>>> x / 128
Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')

Copy

对于不精确的结果，MAX_PREC 在 64 位平台上太大了，可用内存不足：

>>> Decimal(1) / 3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
MemoryError

Copy

在过度分配的系统上（例如 Linux），更复杂的方法是根据可用 RAM 量调整 prec。 假设您有 8GB 的 RAM 并期望有 10 个同时操作数，每个操作数最多使用 500MB：

>>> import sys
>>>
>>> # Maximum number of digits for a single operand using 500MB in 8-byte words
>>> # with 19 digits per word (4-byte and 9 digits for the 32-bit build):
>>> maxdigits = 19 * ((500 * 1024**2) // 8)
>>>
>>> # Check that this works:
>>> c = Context(prec=maxdigits, Emax=MAX_EMAX, Emin=MIN_EMIN)
>>> c.traps[Inexact] = True
>>> setcontext(c)
>>>
>>> # Fill the available precision with nines:
>>> x = Decimal(0).logical_invert() * 9
>>> sys.getsizeof(x)
524288112
>>> x + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  decimal.Inexact: [<class 'decimal.Inexact'>]

Copy

一般来说（尤其是在没有过度分配的系统上），如果希望所有计算都是准确的，建议估计更严格的界限并设置 不精确 陷阱。

1

3.3 版中的新功能。

2

3.9 版更改： 这种方法现在适用于除非整数幂以外的所有精确结果。