2 :mod:`decimal` --- Decimal fixed point and floating point arithmetic
3 ====================================================================
6 :synopsis: Implementation of the General Decimal Arithmetic Specification.
9 .. moduleauthor:: Eric Price <eprice at tjhsst.edu>
10 .. moduleauthor:: Facundo Batista <facundo at taniquetil.com.ar>
11 .. moduleauthor:: Raymond Hettinger <python at rcn.com>
12 .. moduleauthor:: Aahz <aahz at pobox.com>
13 .. moduleauthor:: Tim Peters <tim.one at comcast.net>
16 .. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
20 .. import modules for testing inline doctests with the Sphinx doctest builder
26 # make sure each group gets a fresh context
29 The :mod:`decimal` module provides support for decimal floating point
30 arithmetic. It offers several advantages over the :class:`float` datatype:
32 * Decimal "is based on a floating-point model which was designed with people
33 in mind, and necessarily has a paramount guiding principle -- computers must
34 provide an arithmetic that works in the same way as the arithmetic that
35 people learn at school." -- excerpt from the decimal arithmetic specification.
37 * Decimal numbers can be represented exactly. In contrast, numbers like
38 :const:`1.1` do not have an exact representation in binary floating point. End
39 users typically would not expect :const:`1.1` to display as
40 :const:`1.1000000000000001` as it does with binary floating point.
42 * The exactness carries over into arithmetic. In decimal floating point, ``0.1
43 + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating point, the result
44 is :const:`5.5511151231257827e-017`. While near to zero, the differences
45 prevent reliable equality testing and differences can accumulate. For this
46 reason, decimal is preferred in accounting applications which have strict
49 * The decimal module incorporates a notion of significant places so that ``1.30
50 + 1.20`` is :const:`2.50`. The trailing zero is kept to indicate significance.
51 This is the customary presentation for monetary applications. For
52 multiplication, the "schoolbook" approach uses all the figures in the
53 multiplicands. For instance, ``1.3 * 1.2`` gives :const:`1.56` while ``1.30 *
54 1.20`` gives :const:`1.5600`.
56 * Unlike hardware based binary floating point, the decimal module has a user
57 alterable precision (defaulting to 28 places) which can be as large as needed for
60 >>> getcontext().prec = 6
61 >>> Decimal(1) / Decimal(7)
63 >>> getcontext().prec = 28
64 >>> Decimal(1) / Decimal(7)
65 Decimal('0.1428571428571428571428571429')
67 * Both binary and decimal floating point are implemented in terms of published
68 standards. While the built-in float type exposes only a modest portion of its
69 capabilities, the decimal module exposes all required parts of the standard.
70 When needed, the programmer has full control over rounding and signal handling.
71 This includes an option to enforce exact arithmetic by using exceptions
72 to block any inexact operations.
74 * The decimal module was designed to support "without prejudice, both exact
75 unrounded decimal arithmetic (sometimes called fixed-point arithmetic)
76 and rounded floating-point arithmetic." -- excerpt from the decimal
77 arithmetic specification.
79 The module design is centered around three concepts: the decimal number, the
80 context for arithmetic, and signals.
82 A decimal number is immutable. It has a sign, coefficient digits, and an
83 exponent. To preserve significance, the coefficient digits do not truncate
84 trailing zeros. Decimals also include special values such as
85 :const:`Infinity`, :const:`-Infinity`, and :const:`NaN`. The standard also
86 differentiates :const:`-0` from :const:`+0`.
88 The context for arithmetic is an environment specifying precision, rounding
89 rules, limits on exponents, flags indicating the results of operations, and trap
90 enablers which determine whether signals are treated as exceptions. Rounding
91 options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`,
92 :const:`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`,
93 :const:`ROUND_HALF_UP`, :const:`ROUND_UP`, and :const:`ROUND_05UP`.
95 Signals are groups of exceptional conditions arising during the course of
96 computation. Depending on the needs of the application, signals may be ignored,
97 considered as informational, or treated as exceptions. The signals in the
98 decimal module are: :const:`Clamped`, :const:`InvalidOperation`,
99 :const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:`Subnormal`,
100 :const:`Overflow`, and :const:`Underflow`.
102 For each signal there is a flag and a trap enabler. When a signal is
103 encountered, its flag is set to one, then, if the trap enabler is
104 set to one, an exception is raised. Flags are sticky, so the user needs to
105 reset them before monitoring a calculation.
110 * IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic
111 Specification <http://speleotrove.com/decimal/>`_.
113 * IEEE standard 854-1987, `Unofficial IEEE 854 Text
114 <http://754r.ucbtest.org/standards/854.pdf>`_.
116 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
119 .. _decimal-tutorial:
124 The usual start to using decimals is importing the module, viewing the current
125 context with :func:`getcontext` and, if necessary, setting new values for
126 precision, rounding, or enabled traps::
128 >>> from decimal import *
130 Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
131 capitals=1, flags=[], traps=[Overflow, DivisionByZero,
134 >>> getcontext().prec = 7 # Set a new precision
136 Decimal instances can be constructed from integers, strings, or tuples. To
137 create a Decimal from a :class:`float`, first convert it to a string. This
138 serves as an explicit reminder of the details of the conversion (including
139 representation error). Decimal numbers include special values such as
140 :const:`NaN` which stands for "Not a number", positive and negative
141 :const:`Infinity`, and :const:`-0`.
143 >>> getcontext().prec = 28
148 >>> Decimal((0, (3, 1, 4), -2))
150 >>> Decimal(str(2.0 ** 0.5))
151 Decimal('1.41421356237')
152 >>> Decimal(2) ** Decimal('0.5')
153 Decimal('1.414213562373095048801688724')
156 >>> Decimal('-Infinity')
159 The significance of a new Decimal is determined solely by the number of digits
160 input. Context precision and rounding only come into play during arithmetic
163 .. doctest:: newcontext
165 >>> getcontext().prec = 6
168 >>> Decimal('3.1415926535')
169 Decimal('3.1415926535')
170 >>> Decimal('3.1415926535') + Decimal('2.7182818285')
172 >>> getcontext().rounding = ROUND_UP
173 >>> Decimal('3.1415926535') + Decimal('2.7182818285')
176 Decimals interact well with much of the rest of Python. Here is a small decimal
177 floating point flying circus:
180 :options: +NORMALIZE_WHITESPACE
182 >>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
188 [Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),
189 Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]
197 >>> round(a, 1) # round() first converts to binary floating point
208 And some mathematical functions are also available to Decimal:
210 >>> getcontext().prec = 28
211 >>> Decimal(2).sqrt()
212 Decimal('1.414213562373095048801688724')
214 Decimal('2.718281828459045235360287471')
215 >>> Decimal('10').ln()
216 Decimal('2.302585092994045684017991455')
217 >>> Decimal('10').log10()
220 The :meth:`quantize` method rounds a number to a fixed exponent. This method is
221 useful for monetary applications that often round results to a fixed number of
224 >>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
226 >>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
229 As shown above, the :func:`getcontext` function accesses the current context and
230 allows the settings to be changed. This approach meets the needs of most
233 For more advanced work, it may be useful to create alternate contexts using the
234 Context() constructor. To make an alternate active, use the :func:`setcontext`
237 In accordance with the standard, the :mod:`Decimal` module provides two ready to
238 use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The
239 former is especially useful for debugging because many of the traps are
242 .. doctest:: newcontext
243 :options: +NORMALIZE_WHITESPACE
245 >>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
246 >>> setcontext(myothercontext)
247 >>> Decimal(1) / Decimal(7)
248 Decimal('0.142857142857142857142857142857142857142857142857142857142857')
251 Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
252 capitals=1, flags=[], traps=[])
253 >>> setcontext(ExtendedContext)
254 >>> Decimal(1) / Decimal(7)
255 Decimal('0.142857143')
256 >>> Decimal(42) / Decimal(0)
259 >>> setcontext(BasicContext)
260 >>> Decimal(42) / Decimal(0)
261 Traceback (most recent call last):
262 File "<pyshell#143>", line 1, in -toplevel-
263 Decimal(42) / Decimal(0)
264 DivisionByZero: x / 0
266 Contexts also have signal flags for monitoring exceptional conditions
267 encountered during computations. The flags remain set until explicitly cleared,
268 so it is best to clear the flags before each set of monitored computations by
269 using the :meth:`clear_flags` method. ::
271 >>> setcontext(ExtendedContext)
272 >>> getcontext().clear_flags()
273 >>> Decimal(355) / Decimal(113)
274 Decimal('3.14159292')
276 Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
277 capitals=1, flags=[Rounded, Inexact], traps=[])
279 The *flags* entry shows that the rational approximation to :const:`Pi` was
280 rounded (digits beyond the context precision were thrown away) and that the
281 result is inexact (some of the discarded digits were non-zero).
283 Individual traps are set using the dictionary in the :attr:`traps` field of a
286 .. doctest:: newcontext
288 >>> setcontext(ExtendedContext)
289 >>> Decimal(1) / Decimal(0)
291 >>> getcontext().traps[DivisionByZero] = 1
292 >>> Decimal(1) / Decimal(0)
293 Traceback (most recent call last):
294 File "<pyshell#112>", line 1, in -toplevel-
295 Decimal(1) / Decimal(0)
296 DivisionByZero: x / 0
298 Most programs adjust the current context only once, at the beginning of the
299 program. And, in many applications, data is converted to :class:`Decimal` with
300 a single cast inside a loop. With context set and decimals created, the bulk of
301 the program manipulates the data no differently than with other Python numeric
304 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
313 .. class:: Decimal([value [, context]])
315 Construct a new :class:`Decimal` object based from *value*.
317 *value* can be an integer, string, tuple, or another :class:`Decimal`
318 object. If no *value* is given, returns ``Decimal('0')``. If *value* is a
319 string, it should conform to the decimal numeric string syntax after leading
320 and trailing whitespace characters are removed::
323 digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
324 indicator ::= 'e' | 'E'
325 digits ::= digit [digit]...
326 decimal-part ::= digits '.' [digits] | ['.'] digits
327 exponent-part ::= indicator [sign] digits
328 infinity ::= 'Infinity' | 'Inf'
329 nan ::= 'NaN' [digits] | 'sNaN' [digits]
330 numeric-value ::= decimal-part [exponent-part] | infinity
331 numeric-string ::= [sign] numeric-value | [sign] nan
333 If *value* is a unicode string then other Unicode decimal digits
334 are also permitted where ``digit`` appears above. These include
335 decimal digits from various other alphabets (for example,
336 Arabic-Indic and Devanāgarī digits) along with the fullwidth digits
337 ``u'\uff10'`` through ``u'\uff19'``.
339 If *value* is a :class:`tuple`, it should have three components, a sign
340 (:const:`0` for positive or :const:`1` for negative), a :class:`tuple` of
341 digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))``
342 returns ``Decimal('1.414')``.
344 The *context* precision does not affect how many digits are stored. That is
345 determined exclusively by the number of digits in *value*. For example,
346 ``Decimal('3.00000')`` records all five zeros even if the context precision is
349 The purpose of the *context* argument is determining what to do if *value* is a
350 malformed string. If the context traps :const:`InvalidOperation`, an exception
351 is raised; otherwise, the constructor returns a new Decimal with the value of
354 Once constructed, :class:`Decimal` objects are immutable.
356 .. versionchanged:: 2.6
357 leading and trailing whitespace characters are permitted when
358 creating a Decimal instance from a string.
360 Decimal floating point objects share many properties with the other built-in
361 numeric types such as :class:`float` and :class:`int`. All of the usual math
362 operations and special methods apply. Likewise, decimal objects can be
363 copied, pickled, printed, used as dictionary keys, used as set elements,
364 compared, sorted, and coerced to another type (such as :class:`float` or
367 In addition to the standard numeric properties, decimal floating point
368 objects also have a number of specialized methods:
371 .. method:: adjusted()
373 Return the adjusted exponent after shifting out the coefficient's
374 rightmost digits until only the lead digit remains:
375 ``Decimal('321e+5').adjusted()`` returns seven. Used for determining the
376 position of the most significant digit with respect to the decimal point.
379 .. method:: as_tuple()
381 Return a :term:`named tuple` representation of the number:
382 ``DecimalTuple(sign, digits, exponent)``.
384 .. versionchanged:: 2.6
388 .. method:: canonical()
390 Return the canonical encoding of the argument. Currently, the encoding of
391 a :class:`Decimal` instance is always canonical, so this operation returns
392 its argument unchanged.
394 .. versionadded:: 2.6
396 .. method:: compare(other[, context])
398 Compare the values of two Decimal instances. This operation behaves in
399 the same way as the usual comparison method :meth:`__cmp__`, except that
400 :meth:`compare` returns a Decimal instance rather than an integer, and if
401 either operand is a NaN then the result is a NaN::
403 a or b is a NaN ==> Decimal('NaN')
404 a < b ==> Decimal('-1')
405 a == b ==> Decimal('0')
406 a > b ==> Decimal('1')
408 .. method:: compare_signal(other[, context])
410 This operation is identical to the :meth:`compare` method, except that all
411 NaNs signal. That is, if neither operand is a signaling NaN then any
412 quiet NaN operand is treated as though it were a signaling NaN.
414 .. versionadded:: 2.6
416 .. method:: compare_total(other)
418 Compare two operands using their abstract representation rather than their
419 numerical value. Similar to the :meth:`compare` method, but the result
420 gives a total ordering on :class:`Decimal` instances. Two
421 :class:`Decimal` instances with the same numeric value but different
422 representations compare unequal in this ordering:
424 >>> Decimal('12.0').compare_total(Decimal('12'))
427 Quiet and signaling NaNs are also included in the total ordering. The
428 result of this function is ``Decimal('0')`` if both operands have the same
429 representation, ``Decimal('-1')`` if the first operand is lower in the
430 total order than the second, and ``Decimal('1')`` if the first operand is
431 higher in the total order than the second operand. See the specification
432 for details of the total order.
434 .. versionadded:: 2.6
436 .. method:: compare_total_mag(other)
438 Compare two operands using their abstract representation rather than their
439 value as in :meth:`compare_total`, but ignoring the sign of each operand.
440 ``x.compare_total_mag(y)`` is equivalent to
441 ``x.copy_abs().compare_total(y.copy_abs())``.
443 .. versionadded:: 2.6
445 .. method:: conjugate()
447 Just returns self, this method is only to comply with the Decimal
450 .. versionadded:: 2.6
452 .. method:: copy_abs()
454 Return the absolute value of the argument. This operation is unaffected
455 by the context and is quiet: no flags are changed and no rounding is
458 .. versionadded:: 2.6
460 .. method:: copy_negate()
462 Return the negation of the argument. This operation is unaffected by the
463 context and is quiet: no flags are changed and no rounding is performed.
465 .. versionadded:: 2.6
467 .. method:: copy_sign(other)
469 Return a copy of the first operand with the sign set to be the same as the
470 sign of the second operand. For example:
472 >>> Decimal('2.3').copy_sign(Decimal('-1.5'))
475 This operation is unaffected by the context and is quiet: no flags are
476 changed and no rounding is performed.
478 .. versionadded:: 2.6
480 .. method:: exp([context])
482 Return the value of the (natural) exponential function ``e**x`` at the
483 given number. The result is correctly rounded using the
484 :const:`ROUND_HALF_EVEN` rounding mode.
487 Decimal('2.718281828459045235360287471')
488 >>> Decimal(321).exp()
489 Decimal('2.561702493119680037517373933E+139')
491 .. versionadded:: 2.6
493 .. method:: from_float(f)
495 Classmethod that converts a float to a decimal number, exactly.
497 Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`.
498 Since 0.1 is not exactly representable in binary floating point, the
499 value is stored as the nearest representable value which is
500 `0x1.999999999999ap-4`. That equivalent value in decimal is
501 `0.1000000000000000055511151231257827021181583404541015625`.
505 >>> Decimal.from_float(0.1)
506 Decimal('0.1000000000000000055511151231257827021181583404541015625')
507 >>> Decimal.from_float(float('nan'))
509 >>> Decimal.from_float(float('inf'))
511 >>> Decimal.from_float(float('-inf'))
514 .. versionadded:: 2.7
516 .. method:: fma(other, third[, context])
518 Fused multiply-add. Return self*other+third with no rounding of the
519 intermediate product self*other.
521 >>> Decimal(2).fma(3, 5)
524 .. versionadded:: 2.6
526 .. method:: is_canonical()
528 Return :const:`True` if the argument is canonical and :const:`False`
529 otherwise. Currently, a :class:`Decimal` instance is always canonical, so
530 this operation always returns :const:`True`.
532 .. versionadded:: 2.6
534 .. method:: is_finite()
536 Return :const:`True` if the argument is a finite number, and
537 :const:`False` if the argument is an infinity or a NaN.
539 .. versionadded:: 2.6
541 .. method:: is_infinite()
543 Return :const:`True` if the argument is either positive or negative
544 infinity and :const:`False` otherwise.
546 .. versionadded:: 2.6
550 Return :const:`True` if the argument is a (quiet or signaling) NaN and
551 :const:`False` otherwise.
553 .. versionadded:: 2.6
555 .. method:: is_normal()
557 Return :const:`True` if the argument is a *normal* finite non-zero
558 number with an adjusted exponent greater than or equal to *Emin*.
559 Return :const:`False` if the argument is zero, subnormal, infinite or a
560 NaN. Note, the term *normal* is used here in a different sense with
561 the :meth:`normalize` method which is used to create canonical values.
563 .. versionadded:: 2.6
565 .. method:: is_qnan()
567 Return :const:`True` if the argument is a quiet NaN, and
568 :const:`False` otherwise.
570 .. versionadded:: 2.6
572 .. method:: is_signed()
574 Return :const:`True` if the argument has a negative sign and
575 :const:`False` otherwise. Note that zeros and NaNs can both carry signs.
577 .. versionadded:: 2.6
579 .. method:: is_snan()
581 Return :const:`True` if the argument is a signaling NaN and :const:`False`
584 .. versionadded:: 2.6
586 .. method:: is_subnormal()
588 Return :const:`True` if the argument is subnormal, and :const:`False`
589 otherwise. A number is subnormal is if it is nonzero, finite, and has an
590 adjusted exponent less than *Emin*.
592 .. versionadded:: 2.6
594 .. method:: is_zero()
596 Return :const:`True` if the argument is a (positive or negative) zero and
597 :const:`False` otherwise.
599 .. versionadded:: 2.6
601 .. method:: ln([context])
603 Return the natural (base e) logarithm of the operand. The result is
604 correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
606 .. versionadded:: 2.6
608 .. method:: log10([context])
610 Return the base ten logarithm of the operand. The result is correctly
611 rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
613 .. versionadded:: 2.6
615 .. method:: logb([context])
617 For a nonzero number, return the adjusted exponent of its operand as a
618 :class:`Decimal` instance. If the operand is a zero then
619 ``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag
620 is raised. If the operand is an infinity then ``Decimal('Infinity')`` is
623 .. versionadded:: 2.6
625 .. method:: logical_and(other[, context])
627 :meth:`logical_and` is a logical operation which takes two *logical
628 operands* (see :ref:`logical_operands_label`). The result is the
629 digit-wise ``and`` of the two operands.
631 .. versionadded:: 2.6
633 .. method:: logical_invert([context])
635 :meth:`logical_invert` is a logical operation. The
636 result is the digit-wise inversion of the operand.
638 .. versionadded:: 2.6
640 .. method:: logical_or(other[, context])
642 :meth:`logical_or` is a logical operation which takes two *logical
643 operands* (see :ref:`logical_operands_label`). The result is the
644 digit-wise ``or`` of the two operands.
646 .. versionadded:: 2.6
648 .. method:: logical_xor(other[, context])
650 :meth:`logical_xor` is a logical operation which takes two *logical
651 operands* (see :ref:`logical_operands_label`). The result is the
652 digit-wise exclusive or of the two operands.
654 .. versionadded:: 2.6
656 .. method:: max(other[, context])
658 Like ``max(self, other)`` except that the context rounding rule is applied
659 before returning and that :const:`NaN` values are either signaled or
660 ignored (depending on the context and whether they are signaling or
663 .. method:: max_mag(other[, context])
665 Similar to the :meth:`.max` method, but the comparison is done using the
666 absolute values of the operands.
668 .. versionadded:: 2.6
670 .. method:: min(other[, context])
672 Like ``min(self, other)`` except that the context rounding rule is applied
673 before returning and that :const:`NaN` values are either signaled or
674 ignored (depending on the context and whether they are signaling or
677 .. method:: min_mag(other[, context])
679 Similar to the :meth:`.min` method, but the comparison is done using the
680 absolute values of the operands.
682 .. versionadded:: 2.6
684 .. method:: next_minus([context])
686 Return the largest number representable in the given context (or in the
687 current thread's context if no context is given) that is smaller than the
690 .. versionadded:: 2.6
692 .. method:: next_plus([context])
694 Return the smallest number representable in the given context (or in the
695 current thread's context if no context is given) that is larger than the
698 .. versionadded:: 2.6
700 .. method:: next_toward(other[, context])
702 If the two operands are unequal, return the number closest to the first
703 operand in the direction of the second operand. If both operands are
704 numerically equal, return a copy of the first operand with the sign set to
705 be the same as the sign of the second operand.
707 .. versionadded:: 2.6
709 .. method:: normalize([context])
711 Normalize the number by stripping the rightmost trailing zeros and
712 converting any result equal to :const:`Decimal('0')` to
713 :const:`Decimal('0e0')`. Used for producing canonical values for members
714 of an equivalence class. For example, ``Decimal('32.100')`` and
715 ``Decimal('0.321000e+2')`` both normalize to the equivalent value
718 .. method:: number_class([context])
720 Return a string describing the *class* of the operand. The returned value
721 is one of the following ten strings.
723 * ``"-Infinity"``, indicating that the operand is negative infinity.
724 * ``"-Normal"``, indicating that the operand is a negative normal number.
725 * ``"-Subnormal"``, indicating that the operand is negative and subnormal.
726 * ``"-Zero"``, indicating that the operand is a negative zero.
727 * ``"+Zero"``, indicating that the operand is a positive zero.
728 * ``"+Subnormal"``, indicating that the operand is positive and subnormal.
729 * ``"+Normal"``, indicating that the operand is a positive normal number.
730 * ``"+Infinity"``, indicating that the operand is positive infinity.
731 * ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number).
732 * ``"sNaN"``, indicating that the operand is a signaling NaN.
734 .. versionadded:: 2.6
736 .. method:: quantize(exp[, rounding[, context[, watchexp]]])
738 Return a value equal to the first operand after rounding and having the
739 exponent of the second operand.
741 >>> Decimal('1.41421356').quantize(Decimal('1.000'))
744 Unlike other operations, if the length of the coefficient after the
745 quantize operation would be greater than precision, then an
746 :const:`InvalidOperation` is signaled. This guarantees that, unless there
747 is an error condition, the quantized exponent is always equal to that of
748 the right-hand operand.
750 Also unlike other operations, quantize never signals Underflow, even if
751 the result is subnormal and inexact.
753 If the exponent of the second operand is larger than that of the first
754 then rounding may be necessary. In this case, the rounding mode is
755 determined by the ``rounding`` argument if given, else by the given
756 ``context`` argument; if neither argument is given the rounding mode of
757 the current thread's context is used.
759 If *watchexp* is set (default), then an error is returned whenever the
760 resulting exponent is greater than :attr:`Emax` or less than
765 Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal`
766 class does all its arithmetic. Included for compatibility with the
769 .. versionadded:: 2.6
771 .. method:: remainder_near(other[, context])
773 Compute the modulo as either a positive or negative value depending on
774 which is closest to zero. For instance, ``Decimal(10).remainder_near(6)``
775 returns ``Decimal('-2')`` which is closer to zero than ``Decimal('4')``.
777 If both are equally close, the one chosen will have the same sign as
780 .. method:: rotate(other[, context])
782 Return the result of rotating the digits of the first operand by an amount
783 specified by the second operand. The second operand must be an integer in
784 the range -precision through precision. The absolute value of the second
785 operand gives the number of places to rotate. If the second operand is
786 positive then rotation is to the left; otherwise rotation is to the right.
787 The coefficient of the first operand is padded on the left with zeros to
788 length precision if necessary. The sign and exponent of the first operand
791 .. versionadded:: 2.6
793 .. method:: same_quantum(other[, context])
795 Test whether self and other have the same exponent or whether both are
798 .. method:: scaleb(other[, context])
800 Return the first operand with exponent adjusted by the second.
801 Equivalently, return the first operand multiplied by ``10**other``. The
802 second operand must be an integer.
804 .. versionadded:: 2.6
806 .. method:: shift(other[, context])
808 Return the result of shifting the digits of the first operand by an amount
809 specified by the second operand. The second operand must be an integer in
810 the range -precision through precision. The absolute value of the second
811 operand gives the number of places to shift. If the second operand is
812 positive then the shift is to the left; otherwise the shift is to the
813 right. Digits shifted into the coefficient are zeros. The sign and
814 exponent of the first operand are unchanged.
816 .. versionadded:: 2.6
818 .. method:: sqrt([context])
820 Return the square root of the argument to full precision.
823 .. method:: to_eng_string([context])
825 Convert to an engineering-type string.
827 Engineering notation has an exponent which is a multiple of 3, so there
828 are up to 3 digits left of the decimal place. For example, converts
829 ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``
831 .. method:: to_integral([rounding[, context]])
833 Identical to the :meth:`to_integral_value` method. The ``to_integral``
834 name has been kept for compatibility with older versions.
836 .. method:: to_integral_exact([rounding[, context]])
838 Round to the nearest integer, signaling :const:`Inexact` or
839 :const:`Rounded` as appropriate if rounding occurs. The rounding mode is
840 determined by the ``rounding`` parameter if given, else by the given
841 ``context``. If neither parameter is given then the rounding mode of the
842 current context is used.
844 .. versionadded:: 2.6
846 .. method:: to_integral_value([rounding[, context]])
848 Round to the nearest integer without signaling :const:`Inexact` or
849 :const:`Rounded`. If given, applies *rounding*; otherwise, uses the
850 rounding method in either the supplied *context* or the current context.
852 .. versionchanged:: 2.6
853 renamed from ``to_integral`` to ``to_integral_value``. The old name
854 remains valid for compatibility.
856 .. _logical_operands_label:
861 The :meth:`logical_and`, :meth:`logical_invert`, :meth:`logical_or`,
862 and :meth:`logical_xor` methods expect their arguments to be *logical
863 operands*. A *logical operand* is a :class:`Decimal` instance whose
864 exponent and sign are both zero, and whose digits are all either
865 :const:`0` or :const:`1`.
867 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
875 Contexts are environments for arithmetic operations. They govern precision, set
876 rules for rounding, determine which signals are treated as exceptions, and limit
877 the range for exponents.
879 Each thread has its own current context which is accessed or changed using the
880 :func:`getcontext` and :func:`setcontext` functions:
883 .. function:: getcontext()
885 Return the current context for the active thread.
888 .. function:: setcontext(c)
890 Set the current context for the active thread to *c*.
892 Beginning with Python 2.5, you can also use the :keyword:`with` statement and
893 the :func:`localcontext` function to temporarily change the active context.
896 .. function:: localcontext([c])
898 Return a context manager that will set the current context for the active thread
899 to a copy of *c* on entry to the with-statement and restore the previous context
900 when exiting the with-statement. If no context is specified, a copy of the
901 current context is used.
903 .. versionadded:: 2.5
905 For example, the following code sets the current decimal precision to 42 places,
906 performs a calculation, and then automatically restores the previous context::
908 from decimal import localcontext
910 with localcontext() as ctx:
911 ctx.prec = 42 # Perform a high precision calculation
912 s = calculate_something()
913 s = +s # Round the final result back to the default precision
915 New contexts can also be created using the :class:`Context` constructor
916 described below. In addition, the module provides three pre-made contexts:
919 .. class:: BasicContext
921 This is a standard context defined by the General Decimal Arithmetic
922 Specification. Precision is set to nine. Rounding is set to
923 :const:`ROUND_HALF_UP`. All flags are cleared. All traps are enabled (treated
924 as exceptions) except :const:`Inexact`, :const:`Rounded`, and
927 Because many of the traps are enabled, this context is useful for debugging.
930 .. class:: ExtendedContext
932 This is a standard context defined by the General Decimal Arithmetic
933 Specification. Precision is set to nine. Rounding is set to
934 :const:`ROUND_HALF_EVEN`. All flags are cleared. No traps are enabled (so that
935 exceptions are not raised during computations).
937 Because the traps are disabled, this context is useful for applications that
938 prefer to have result value of :const:`NaN` or :const:`Infinity` instead of
939 raising exceptions. This allows an application to complete a run in the
940 presence of conditions that would otherwise halt the program.
943 .. class:: DefaultContext
945 This context is used by the :class:`Context` constructor as a prototype for new
946 contexts. Changing a field (such a precision) has the effect of changing the
947 default for new contexts creating by the :class:`Context` constructor.
949 This context is most useful in multi-threaded environments. Changing one of the
950 fields before threads are started has the effect of setting system-wide
951 defaults. Changing the fields after threads have started is not recommended as
952 it would require thread synchronization to prevent race conditions.
954 In single threaded environments, it is preferable to not use this context at
955 all. Instead, simply create contexts explicitly as described below.
957 The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled traps
958 for Overflow, InvalidOperation, and DivisionByZero.
960 In addition to the three supplied contexts, new contexts can be created with the
961 :class:`Context` constructor.
964 .. class:: Context(prec=None, rounding=None, traps=None, flags=None, Emin=None, Emax=None, capitals=1)
966 Creates a new context. If a field is not specified or is :const:`None`, the
967 default values are copied from the :const:`DefaultContext`. If the *flags*
968 field is not specified or is :const:`None`, all flags are cleared.
970 The *prec* field is a positive integer that sets the precision for arithmetic
971 operations in the context.
973 The *rounding* option is one of:
975 * :const:`ROUND_CEILING` (towards :const:`Infinity`),
976 * :const:`ROUND_DOWN` (towards zero),
977 * :const:`ROUND_FLOOR` (towards :const:`-Infinity`),
978 * :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero),
979 * :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer),
980 * :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or
981 * :const:`ROUND_UP` (away from zero).
982 * :const:`ROUND_05UP` (away from zero if last digit after rounding towards zero
983 would have been 0 or 5; otherwise towards zero)
985 The *traps* and *flags* fields list any signals to be set. Generally, new
986 contexts should only set traps and leave the flags clear.
988 The *Emin* and *Emax* fields are integers specifying the outer limits allowable
991 The *capitals* field is either :const:`0` or :const:`1` (the default). If set to
992 :const:`1`, exponents are printed with a capital :const:`E`; otherwise, a
993 lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`.
995 .. versionchanged:: 2.6
996 The :const:`ROUND_05UP` rounding mode was added.
998 The :class:`Context` class defines several general purpose methods as well as
999 a large number of methods for doing arithmetic directly in a given context.
1000 In addition, for each of the :class:`Decimal` methods described above (with
1001 the exception of the :meth:`adjusted` and :meth:`as_tuple` methods) there is
1002 a corresponding :class:`Context` method. For example, ``C.exp(x)`` is
1003 equivalent to ``x.exp(context=C)``.
1006 .. method:: clear_flags()
1008 Resets all of the flags to :const:`0`.
1012 Return a duplicate of the context.
1014 .. method:: copy_decimal(num)
1016 Return a copy of the Decimal instance num.
1018 .. method:: create_decimal(num)
1020 Creates a new Decimal instance from *num* but using *self* as
1021 context. Unlike the :class:`Decimal` constructor, the context precision,
1022 rounding method, flags, and traps are applied to the conversion.
1024 This is useful because constants are often given to a greater precision
1025 than is needed by the application. Another benefit is that rounding
1026 immediately eliminates unintended effects from digits beyond the current
1027 precision. In the following example, using unrounded inputs means that
1028 adding zero to a sum can change the result:
1030 .. doctest:: newcontext
1032 >>> getcontext().prec = 3
1033 >>> Decimal('3.4445') + Decimal('1.0023')
1035 >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
1038 This method implements the to-number operation of the IBM specification.
1039 If the argument is a string, no leading or trailing whitespace is
1042 .. method:: create_decimal_from_float(f)
1044 Creates a new Decimal instance from a float *f* but rounding using *self*
1045 as the context. Unlike the :meth:`Decimal.from_float` class method,
1046 the context precision, rounding method, flags, and traps are applied to
1051 >>> context = Context(prec=5, rounding=ROUND_DOWN)
1052 >>> context.create_decimal_from_float(math.pi)
1054 >>> context = Context(prec=5, traps=[Inexact])
1055 >>> context.create_decimal_from_float(math.pi)
1056 Traceback (most recent call last):
1060 .. versionadded:: 2.7
1064 Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent
1065 value for subnormal results. When underflow occurs, the exponent is set
1071 Returns a value equal to ``Emax - prec + 1``.
1073 The usual approach to working with decimals is to create :class:`Decimal`
1074 instances and then apply arithmetic operations which take place within the
1075 current context for the active thread. An alternative approach is to use
1076 context methods for calculating within a specific context. The methods are
1077 similar to those for the :class:`Decimal` class and are only briefly
1083 Returns the absolute value of *x*.
1086 .. method:: add(x, y)
1088 Return the sum of *x* and *y*.
1091 .. method:: canonical(x)
1093 Returns the same Decimal object *x*.
1096 .. method:: compare(x, y)
1098 Compares *x* and *y* numerically.
1101 .. method:: compare_signal(x, y)
1103 Compares the values of the two operands numerically.
1106 .. method:: compare_total(x, y)
1108 Compares two operands using their abstract representation.
1111 .. method:: compare_total_mag(x, y)
1113 Compares two operands using their abstract representation, ignoring sign.
1116 .. method:: copy_abs(x)
1118 Returns a copy of *x* with the sign set to 0.
1121 .. method:: copy_negate(x)
1123 Returns a copy of *x* with the sign inverted.
1126 .. method:: copy_sign(x, y)
1128 Copies the sign from *y* to *x*.
1131 .. method:: divide(x, y)
1133 Return *x* divided by *y*.
1136 .. method:: divide_int(x, y)
1138 Return *x* divided by *y*, truncated to an integer.
1141 .. method:: divmod(x, y)
1143 Divides two numbers and returns the integer part of the result.
1151 .. method:: fma(x, y, z)
1153 Returns *x* multiplied by *y*, plus *z*.
1156 .. method:: is_canonical(x)
1158 Returns True if *x* is canonical; otherwise returns False.
1161 .. method:: is_finite(x)
1163 Returns True if *x* is finite; otherwise returns False.
1166 .. method:: is_infinite(x)
1168 Returns True if *x* is infinite; otherwise returns False.
1171 .. method:: is_nan(x)
1173 Returns True if *x* is a qNaN or sNaN; otherwise returns False.
1176 .. method:: is_normal(x)
1178 Returns True if *x* is a normal number; otherwise returns False.
1181 .. method:: is_qnan(x)
1183 Returns True if *x* is a quiet NaN; otherwise returns False.
1186 .. method:: is_signed(x)
1188 Returns True if *x* is negative; otherwise returns False.
1191 .. method:: is_snan(x)
1193 Returns True if *x* is a signaling NaN; otherwise returns False.
1196 .. method:: is_subnormal(x)
1198 Returns True if *x* is subnormal; otherwise returns False.
1201 .. method:: is_zero(x)
1203 Returns True if *x* is a zero; otherwise returns False.
1208 Returns the natural (base e) logarithm of *x*.
1211 .. method:: log10(x)
1213 Returns the base 10 logarithm of *x*.
1218 Returns the exponent of the magnitude of the operand's MSD.
1221 .. method:: logical_and(x, y)
1223 Applies the logical operation *and* between each operand's digits.
1226 .. method:: logical_invert(x)
1228 Invert all the digits in *x*.
1231 .. method:: logical_or(x, y)
1233 Applies the logical operation *or* between each operand's digits.
1236 .. method:: logical_xor(x, y)
1238 Applies the logical operation *xor* between each operand's digits.
1241 .. method:: max(x, y)
1243 Compares two values numerically and returns the maximum.
1246 .. method:: max_mag(x, y)
1248 Compares the values numerically with their sign ignored.
1251 .. method:: min(x, y)
1253 Compares two values numerically and returns the minimum.
1256 .. method:: min_mag(x, y)
1258 Compares the values numerically with their sign ignored.
1261 .. method:: minus(x)
1263 Minus corresponds to the unary prefix minus operator in Python.
1266 .. method:: multiply(x, y)
1268 Return the product of *x* and *y*.
1271 .. method:: next_minus(x)
1273 Returns the largest representable number smaller than *x*.
1276 .. method:: next_plus(x)
1278 Returns the smallest representable number larger than *x*.
1281 .. method:: next_toward(x, y)
1283 Returns the number closest to *x*, in direction towards *y*.
1286 .. method:: normalize(x)
1288 Reduces *x* to its simplest form.
1291 .. method:: number_class(x)
1293 Returns an indication of the class of *x*.
1298 Plus corresponds to the unary prefix plus operator in Python. This
1299 operation applies the context precision and rounding, so it is *not* an
1303 .. method:: power(x, y[, modulo])
1305 Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given.
1307 With two arguments, compute ``x**y``. If ``x`` is negative then ``y``
1308 must be integral. The result will be inexact unless ``y`` is integral and
1309 the result is finite and can be expressed exactly in 'precision' digits.
1310 The result should always be correctly rounded, using the rounding mode of
1311 the current thread's context.
1313 With three arguments, compute ``(x**y) % modulo``. For the three argument
1314 form, the following restrictions on the arguments hold:
1316 - all three arguments must be integral
1317 - ``y`` must be nonnegative
1318 - at least one of ``x`` or ``y`` must be nonzero
1319 - ``modulo`` must be nonzero and have at most 'precision' digits
1321 The result of ``Context.power(x, y, modulo)`` is identical to the result
1322 that would be obtained by computing ``(x**y) % modulo`` with unbounded
1323 precision, but is computed more efficiently. It is always exact.
1325 .. versionchanged:: 2.6
1326 ``y`` may now be nonintegral in ``x**y``.
1327 Stricter requirements for the three-argument version.
1330 .. method:: quantize(x, y)
1332 Returns a value equal to *x* (rounded), having the exponent of *y*.
1337 Just returns 10, as this is Decimal, :)
1340 .. method:: remainder(x, y)
1342 Returns the remainder from integer division.
1344 The sign of the result, if non-zero, is the same as that of the original
1347 .. method:: remainder_near(x, y)
1349 Returns ``x - y * n``, where *n* is the integer nearest the exact value
1350 of ``x / y`` (if the result is 0 then its sign will be the sign of *x*).
1353 .. method:: rotate(x, y)
1355 Returns a rotated copy of *x*, *y* times.
1358 .. method:: same_quantum(x, y)
1360 Returns True if the two operands have the same exponent.
1363 .. method:: scaleb (x, y)
1365 Returns the first operand after adding the second value its exp.
1368 .. method:: shift(x, y)
1370 Returns a shifted copy of *x*, *y* times.
1375 Square root of a non-negative number to context precision.
1378 .. method:: subtract(x, y)
1380 Return the difference between *x* and *y*.
1383 .. method:: to_eng_string(x)
1385 Converts a number to a string, using scientific notation.
1388 .. method:: to_integral_exact(x)
1390 Rounds to an integer.
1393 .. method:: to_sci_string(x)
1395 Converts a number to a string using scientific notation.
1397 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1400 .. _decimal-signals:
1405 Signals represent conditions that arise during computation. Each corresponds to
1406 one context flag and one context trap enabler.
1408 The context flag is set whenever the condition is encountered. After the
1409 computation, flags may be checked for informational purposes (for instance, to
1410 determine whether a computation was exact). After checking the flags, be sure to
1411 clear all flags before starting the next computation.
1413 If the context's trap enabler is set for the signal, then the condition causes a
1414 Python exception to be raised. For example, if the :class:`DivisionByZero` trap
1415 is set, then a :exc:`DivisionByZero` exception is raised upon encountering the
1421 Altered an exponent to fit representation constraints.
1423 Typically, clamping occurs when an exponent falls outside the context's
1424 :attr:`Emin` and :attr:`Emax` limits. If possible, the exponent is reduced to
1425 fit by adding zeros to the coefficient.
1428 .. class:: DecimalException
1430 Base class for other signals and a subclass of :exc:`ArithmeticError`.
1433 .. class:: DivisionByZero
1435 Signals the division of a non-infinite number by zero.
1437 Can occur with division, modulo division, or when raising a number to a negative
1438 power. If this signal is not trapped, returns :const:`Infinity` or
1439 :const:`-Infinity` with the sign determined by the inputs to the calculation.
1444 Indicates that rounding occurred and the result is not exact.
1446 Signals when non-zero digits were discarded during rounding. The rounded result
1447 is returned. The signal flag or trap is used to detect when results are
1451 .. class:: InvalidOperation
1453 An invalid operation was performed.
1455 Indicates that an operation was requested that does not make sense. If not
1456 trapped, returns :const:`NaN`. Possible causes include::
1463 x._rescale( non-integer )
1474 Indicates the exponent is larger than :attr:`Emax` after rounding has
1475 occurred. If not trapped, the result depends on the rounding mode, either
1476 pulling inward to the largest representable finite number or rounding outward
1477 to :const:`Infinity`. In either case, :class:`Inexact` and :class:`Rounded`
1483 Rounding occurred though possibly no information was lost.
1485 Signaled whenever rounding discards digits; even if those digits are zero
1486 (such as rounding :const:`5.00` to :const:`5.0`). If not trapped, returns
1487 the result unchanged. This signal is used to detect loss of significant
1491 .. class:: Subnormal
1493 Exponent was lower than :attr:`Emin` prior to rounding.
1495 Occurs when an operation result is subnormal (the exponent is too small). If
1496 not trapped, returns the result unchanged.
1499 .. class:: Underflow
1501 Numerical underflow with result rounded to zero.
1503 Occurs when a subnormal result is pushed to zero by rounding. :class:`Inexact`
1504 and :class:`Subnormal` are also signaled.
1506 The following table summarizes the hierarchy of signals::
1508 exceptions.ArithmeticError(exceptions.StandardError)
1511 DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
1513 Overflow(Inexact, Rounded)
1514 Underflow(Inexact, Rounded, Subnormal)
1519 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1524 Floating Point Notes
1525 --------------------
1528 Mitigating round-off error with increased precision
1529 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1531 The use of decimal floating point eliminates decimal representation error
1532 (making it possible to represent :const:`0.1` exactly); however, some operations
1533 can still incur round-off error when non-zero digits exceed the fixed precision.
1535 The effects of round-off error can be amplified by the addition or subtraction
1536 of nearly offsetting quantities resulting in loss of significance. Knuth
1537 provides two instructive examples where rounded floating point arithmetic with
1538 insufficient precision causes the breakdown of the associative and distributive
1539 properties of addition:
1541 .. doctest:: newcontext
1543 # Examples from Seminumerical Algorithms, Section 4.2.2.
1544 >>> from decimal import Decimal, getcontext
1545 >>> getcontext().prec = 8
1547 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
1549 Decimal('9.5111111')
1553 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
1557 Decimal('0.0060000')
1559 The :mod:`decimal` module makes it possible to restore the identities by
1560 expanding the precision sufficiently to avoid loss of significance:
1562 .. doctest:: newcontext
1564 >>> getcontext().prec = 20
1565 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
1567 Decimal('9.51111111')
1569 Decimal('9.51111111')
1571 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
1573 Decimal('0.0060000')
1575 Decimal('0.0060000')
1581 The number system for the :mod:`decimal` module provides special values
1582 including :const:`NaN`, :const:`sNaN`, :const:`-Infinity`, :const:`Infinity`,
1583 and two zeros, :const:`+0` and :const:`-0`.
1585 Infinities can be constructed directly with: ``Decimal('Infinity')``. Also,
1586 they can arise from dividing by zero when the :exc:`DivisionByZero` signal is
1587 not trapped. Likewise, when the :exc:`Overflow` signal is not trapped, infinity
1588 can result from rounding beyond the limits of the largest representable number.
1590 The infinities are signed (affine) and can be used in arithmetic operations
1591 where they get treated as very large, indeterminate numbers. For instance,
1592 adding a constant to infinity gives another infinite result.
1594 Some operations are indeterminate and return :const:`NaN`, or if the
1595 :exc:`InvalidOperation` signal is trapped, raise an exception. For example,
1596 ``0/0`` returns :const:`NaN` which means "not a number". This variety of
1597 :const:`NaN` is quiet and, once created, will flow through other computations
1598 always resulting in another :const:`NaN`. This behavior can be useful for a
1599 series of computations that occasionally have missing inputs --- it allows the
1600 calculation to proceed while flagging specific results as invalid.
1602 A variant is :const:`sNaN` which signals rather than remaining quiet after every
1603 operation. This is a useful return value when an invalid result needs to
1604 interrupt a calculation for special handling.
1606 The behavior of Python's comparison operators can be a little surprising where a
1607 :const:`NaN` is involved. A test for equality where one of the operands is a
1608 quiet or signaling :const:`NaN` always returns :const:`False` (even when doing
1609 ``Decimal('NaN')==Decimal('NaN')``), while a test for inequality always returns
1610 :const:`True`. An attempt to compare two Decimals using any of the ``<``,
1611 ``<=``, ``>`` or ``>=`` operators will raise the :exc:`InvalidOperation` signal
1612 if either operand is a :const:`NaN`, and return :const:`False` if this signal is
1613 not trapped. Note that the General Decimal Arithmetic specification does not
1614 specify the behavior of direct comparisons; these rules for comparisons
1615 involving a :const:`NaN` were taken from the IEEE 854 standard (see Table 3 in
1616 section 5.7). To ensure strict standards-compliance, use the :meth:`compare`
1617 and :meth:`compare-signal` methods instead.
1619 The signed zeros can result from calculations that underflow. They keep the sign
1620 that would have resulted if the calculation had been carried out to greater
1621 precision. Since their magnitude is zero, both positive and negative zeros are
1622 treated as equal and their sign is informational.
1624 In addition to the two signed zeros which are distinct yet equal, there are
1625 various representations of zero with differing precisions yet equivalent in
1626 value. This takes a bit of getting used to. For an eye accustomed to
1627 normalized floating point representations, it is not immediately obvious that
1628 the following calculation returns a value equal to zero:
1630 >>> 1 / Decimal('Infinity')
1631 Decimal('0E-1000000026')
1633 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1636 .. _decimal-threads:
1638 Working with threads
1639 --------------------
1641 The :func:`getcontext` function accesses a different :class:`Context` object for
1642 each thread. Having separate thread contexts means that threads may make
1643 changes (such as ``getcontext.prec=10``) without interfering with other threads.
1645 Likewise, the :func:`setcontext` function automatically assigns its target to
1648 If :func:`setcontext` has not been called before :func:`getcontext`, then
1649 :func:`getcontext` will automatically create a new context for use in the
1652 The new context is copied from a prototype context called *DefaultContext*. To
1653 control the defaults so that each thread will use the same values throughout the
1654 application, directly modify the *DefaultContext* object. This should be done
1655 *before* any threads are started so that there won't be a race condition between
1656 threads calling :func:`getcontext`. For example::
1658 # Set applicationwide defaults for all threads about to be launched
1659 DefaultContext.prec = 12
1660 DefaultContext.rounding = ROUND_DOWN
1661 DefaultContext.traps = ExtendedContext.traps.copy()
1662 DefaultContext.traps[InvalidOperation] = 1
1663 setcontext(DefaultContext)
1665 # Afterwards, the threads can be started
1671 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1674 .. _decimal-recipes:
1679 Here are a few recipes that serve as utility functions and that demonstrate ways
1680 to work with the :class:`Decimal` class::
1682 def moneyfmt(value, places=2, curr='', sep=',', dp='.',
1683 pos='', neg='-', trailneg=''):
1684 """Convert Decimal to a money formatted string.
1686 places: required number of places after the decimal point
1687 curr: optional currency symbol before the sign (may be blank)
1688 sep: optional grouping separator (comma, period, space, or blank)
1689 dp: decimal point indicator (comma or period)
1690 only specify as blank when places is zero
1691 pos: optional sign for positive numbers: '+', space or blank
1692 neg: optional sign for negative numbers: '-', '(', space or blank
1693 trailneg:optional trailing minus indicator: '-', ')', space or blank
1695 >>> d = Decimal('-1234567.8901')
1696 >>> moneyfmt(d, curr='$')
1698 >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
1700 >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
1702 >>> moneyfmt(Decimal(123456789), sep=' ')
1704 >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
1708 q = Decimal(10) ** -places # 2 places --> '0.01'
1709 sign, digits, exp = value.quantize(q).as_tuple()
1711 digits = map(str, digits)
1712 build, next = result.append, digits.pop
1715 for i in range(places):
1716 build(next() if digits else '0')
1724 if i == 3 and digits:
1728 build(neg if sign else pos)
1729 return ''.join(reversed(result))
1732 """Compute Pi to the current precision.
1735 3.141592653589793238462643383
1738 getcontext().prec += 2 # extra digits for intermediate steps
1739 three = Decimal(3) # substitute "three=3.0" for regular floats
1740 lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
1747 getcontext().prec -= 2
1748 return +s # unary plus applies the new precision
1751 """Return e raised to the power of x. Result type matches input type.
1753 >>> print exp(Decimal(1))
1754 2.718281828459045235360287471
1755 >>> print exp(Decimal(2))
1756 7.389056098930650227230427461
1763 getcontext().prec += 2
1764 i, lasts, s, fact, num = 0, 0, 1, 1, 1
1771 getcontext().prec -= 2
1775 """Return the cosine of x as measured in radians.
1777 >>> print cos(Decimal('0.5'))
1778 0.8775825618903727161162815826
1781 >>> print cos(0.5+0j)
1785 getcontext().prec += 2
1786 i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
1793 s += num / fact * sign
1794 getcontext().prec -= 2
1798 """Return the sine of x as measured in radians.
1800 >>> print sin(Decimal('0.5'))
1801 0.4794255386042030002732879352
1804 >>> print sin(0.5+0j)
1808 getcontext().prec += 2
1809 i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
1816 s += num / fact * sign
1817 getcontext().prec -= 2
1821 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1829 Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to
1830 minimize typing when using the interactive interpreter?
1832 A. Some users abbreviate the constructor to just a single letter:
1834 >>> D = decimal.Decimal
1835 >>> D('1.23') + D('3.45')
1838 Q. In a fixed-point application with two decimal places, some inputs have many
1839 places and need to be rounded. Others are not supposed to have excess digits
1840 and need to be validated. What methods should be used?
1842 A. The :meth:`quantize` method rounds to a fixed number of decimal places. If
1843 the :const:`Inexact` trap is set, it is also useful for validation:
1845 >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
1847 >>> # Round to two places
1848 >>> Decimal('3.214').quantize(TWOPLACES)
1851 >>> # Validate that a number does not exceed two places
1852 >>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))
1855 >>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
1856 Traceback (most recent call last):
1860 Q. Once I have valid two place inputs, how do I maintain that invariant
1861 throughout an application?
1863 A. Some operations like addition, subtraction, and multiplication by an integer
1864 will automatically preserve fixed point. Others operations, like division and
1865 non-integer multiplication, will change the number of decimal places and need to
1866 be followed-up with a :meth:`quantize` step:
1868 >>> a = Decimal('102.72') # Initial fixed-point values
1869 >>> b = Decimal('3.17')
1870 >>> a + b # Addition preserves fixed-point
1874 >>> a * 42 # So does integer multiplication
1876 >>> (a * b).quantize(TWOPLACES) # Must quantize non-integer multiplication
1878 >>> (b / a).quantize(TWOPLACES) # And quantize division
1881 In developing fixed-point applications, it is convenient to define functions
1882 to handle the :meth:`quantize` step:
1884 >>> def mul(x, y, fp=TWOPLACES):
1885 ... return (x * y).quantize(fp)
1886 >>> def div(x, y, fp=TWOPLACES):
1887 ... return (x / y).quantize(fp)
1889 >>> mul(a, b) # Automatically preserve fixed-point
1894 Q. There are many ways to express the same value. The numbers :const:`200`,
1895 :const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at
1896 various precisions. Is there a way to transform them to a single recognizable
1899 A. The :meth:`normalize` method maps all equivalent values to a single
1902 >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
1903 >>> [v.normalize() for v in values]
1904 [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]
1906 Q. Some decimal values always print with exponential notation. Is there a way
1907 to get a non-exponential representation?
1909 A. For some values, exponential notation is the only way to express the number
1910 of significant places in the coefficient. For example, expressing
1911 :const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the
1912 original's two-place significance.
1914 If an application does not care about tracking significance, it is easy to
1915 remove the exponent and trailing zeros, losing significance, but keeping the
1918 def remove_exponent(d):
1919 '''Remove exponent and trailing zeros.
1921 >>> remove_exponent(Decimal('5E+3'))
1925 return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()
1927 Q. Is there a way to convert a regular float to a Decimal?
1929 A. Yes, the classmethod :meth:`from_float` makes an exact conversion.
1931 The regular decimal constructor does not do this by default because there is
1932 some question about whether it is advisable to mix binary and decimal floating
1933 point. Also, its use requires some care to avoid the representation issues
1934 associated with binary floating point:
1936 >>> Decimal.from_float(1.1)
1937 Decimal('1.100000000000000088817841970012523233890533447265625')
1939 Q. Within a complex calculation, how can I make sure that I haven't gotten a
1940 spurious result because of insufficient precision or rounding anomalies.
1942 A. The decimal module makes it easy to test results. A best practice is to
1943 re-run calculations using greater precision and with various rounding modes.
1944 Widely differing results indicate insufficient precision, rounding mode issues,
1945 ill-conditioned inputs, or a numerically unstable algorithm.
1947 Q. I noticed that context precision is applied to the results of operations but
1948 not to the inputs. Is there anything to watch out for when mixing values of
1949 different precisions?
1951 A. Yes. The principle is that all values are considered to be exact and so is
1952 the arithmetic on those values. Only the results are rounded. The advantage
1953 for inputs is that "what you type is what you get". A disadvantage is that the
1954 results can look odd if you forget that the inputs haven't been rounded:
1956 .. doctest:: newcontext
1958 >>> getcontext().prec = 3
1959 >>> Decimal('3.104') + Decimal('2.104')
1961 >>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
1964 The solution is either to increase precision or to force rounding of inputs
1965 using the unary plus operation:
1967 .. doctest:: newcontext
1969 >>> getcontext().prec = 3
1970 >>> +Decimal('1.23456789') # unary plus triggers rounding
1973 Alternatively, inputs can be rounded upon creation using the
1974 :meth:`Context.create_decimal` method:
1976 >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')