1:mod:`decimal` --- Decimal fixed point and floating point arithmetic 2==================================================================== 3 4.. module:: decimal 5 :synopsis: Implementation of the General Decimal Arithmetic Specification. 6 7.. moduleauthor:: Eric Price <eprice at tjhsst.edu> 8.. moduleauthor:: Facundo Batista <facundo at taniquetil.com.ar> 9.. moduleauthor:: Raymond Hettinger <python at rcn.com> 10.. moduleauthor:: Aahz <aahz at pobox.com> 11.. moduleauthor:: Tim Peters <tim.one at comcast.net> 12.. moduleauthor:: Stefan Krah <skrah at bytereef.org> 13.. sectionauthor:: Raymond D. Hettinger <python at rcn.com> 14 15**Source code:** :source:`Lib/decimal.py` 16 17.. import modules for testing inline doctests with the Sphinx doctest builder 18.. testsetup:: * 19 20 import decimal 21 import math 22 from decimal import * 23 # make sure each group gets a fresh context 24 setcontext(Context()) 25 26.. testcleanup:: * 27 28 # make sure other tests (outside this file) get a fresh context 29 setcontext(Context()) 30 31-------------- 32 33The :mod:`decimal` module provides support for fast correctly-rounded 34decimal floating point arithmetic. It offers several advantages over the 35:class:`float` datatype: 36 37* Decimal "is based on a floating-point model which was designed with people 38 in mind, and necessarily has a paramount guiding principle -- computers must 39 provide an arithmetic that works in the same way as the arithmetic that 40 people learn at school." -- excerpt from the decimal arithmetic specification. 41 42* Decimal numbers can be represented exactly. In contrast, numbers like 43 :const:`1.1` and :const:`2.2` do not have exact representations in binary 44 floating point. End users typically would not expect ``1.1 + 2.2`` to display 45 as :const:`3.3000000000000003` as it does with binary floating point. 46 47* The exactness carries over into arithmetic. In decimal floating point, ``0.1 48 + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating point, the result 49 is :const:`5.5511151231257827e-017`. While near to zero, the differences 50 prevent reliable equality testing and differences can accumulate. For this 51 reason, decimal is preferred in accounting applications which have strict 52 equality invariants. 53 54* The decimal module incorporates a notion of significant places so that ``1.30 55 + 1.20`` is :const:`2.50`. The trailing zero is kept to indicate significance. 56 This is the customary presentation for monetary applications. For 57 multiplication, the "schoolbook" approach uses all the figures in the 58 multiplicands. For instance, ``1.3 * 1.2`` gives :const:`1.56` while ``1.30 * 59 1.20`` gives :const:`1.5600`. 60 61* Unlike hardware based binary floating point, the decimal module has a user 62 alterable precision (defaulting to 28 places) which can be as large as needed for 63 a given problem: 64 65 >>> from decimal import * 66 >>> getcontext().prec = 6 67 >>> Decimal(1) / Decimal(7) 68 Decimal('0.142857') 69 >>> getcontext().prec = 28 70 >>> Decimal(1) / Decimal(7) 71 Decimal('0.1428571428571428571428571429') 72 73* Both binary and decimal floating point are implemented in terms of published 74 standards. While the built-in float type exposes only a modest portion of its 75 capabilities, the decimal module exposes all required parts of the standard. 76 When needed, the programmer has full control over rounding and signal handling. 77 This includes an option to enforce exact arithmetic by using exceptions 78 to block any inexact operations. 79 80* The decimal module was designed to support "without prejudice, both exact 81 unrounded decimal arithmetic (sometimes called fixed-point arithmetic) 82 and rounded floating-point arithmetic." -- excerpt from the decimal 83 arithmetic specification. 84 85The module design is centered around three concepts: the decimal number, the 86context for arithmetic, and signals. 87 88A decimal number is immutable. It has a sign, coefficient digits, and an 89exponent. To preserve significance, the coefficient digits do not truncate 90trailing zeros. Decimals also include special values such as 91:const:`Infinity`, :const:`-Infinity`, and :const:`NaN`. The standard also 92differentiates :const:`-0` from :const:`+0`. 93 94The context for arithmetic is an environment specifying precision, rounding 95rules, limits on exponents, flags indicating the results of operations, and trap 96enablers which determine whether signals are treated as exceptions. Rounding 97options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`, 98:const:`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`, 99:const:`ROUND_HALF_UP`, :const:`ROUND_UP`, and :const:`ROUND_05UP`. 100 101Signals are groups of exceptional conditions arising during the course of 102computation. Depending on the needs of the application, signals may be ignored, 103considered as informational, or treated as exceptions. The signals in the 104decimal module are: :const:`Clamped`, :const:`InvalidOperation`, 105:const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:`Subnormal`, 106:const:`Overflow`, :const:`Underflow` and :const:`FloatOperation`. 107 108For each signal there is a flag and a trap enabler. When a signal is 109encountered, its flag is set to one, then, if the trap enabler is 110set to one, an exception is raised. Flags are sticky, so the user needs to 111reset them before monitoring a calculation. 112 113 114.. seealso:: 115 116 * IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic 117 Specification <http://speleotrove.com/decimal/decarith.html>`_. 118 119.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 120 121 122.. _decimal-tutorial: 123 124Quick-start Tutorial 125-------------------- 126 127The usual start to using decimals is importing the module, viewing the current 128context with :func:`getcontext` and, if necessary, setting new values for 129precision, rounding, or enabled traps:: 130 131 >>> from decimal import * 132 >>> getcontext() 133 Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999, 134 capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero, 135 InvalidOperation]) 136 137 >>> getcontext().prec = 7 # Set a new precision 138 139Decimal instances can be constructed from integers, strings, floats, or tuples. 140Construction from an integer or a float performs an exact conversion of the 141value of that integer or float. Decimal numbers include special values such as 142:const:`NaN` which stands for "Not a number", positive and negative 143:const:`Infinity`, and :const:`-0`:: 144 145 >>> getcontext().prec = 28 146 >>> Decimal(10) 147 Decimal('10') 148 >>> Decimal('3.14') 149 Decimal('3.14') 150 >>> Decimal(3.14) 151 Decimal('3.140000000000000124344978758017532527446746826171875') 152 >>> Decimal((0, (3, 1, 4), -2)) 153 Decimal('3.14') 154 >>> Decimal(str(2.0 ** 0.5)) 155 Decimal('1.4142135623730951') 156 >>> Decimal(2) ** Decimal('0.5') 157 Decimal('1.414213562373095048801688724') 158 >>> Decimal('NaN') 159 Decimal('NaN') 160 >>> Decimal('-Infinity') 161 Decimal('-Infinity') 162 163If the :exc:`FloatOperation` signal is trapped, accidental mixing of 164decimals and floats in constructors or ordering comparisons raises 165an exception:: 166 167 >>> c = getcontext() 168 >>> c.traps[FloatOperation] = True 169 >>> Decimal(3.14) 170 Traceback (most recent call last): 171 File "<stdin>", line 1, in <module> 172 decimal.FloatOperation: [<class 'decimal.FloatOperation'>] 173 >>> Decimal('3.5') < 3.7 174 Traceback (most recent call last): 175 File "<stdin>", line 1, in <module> 176 decimal.FloatOperation: [<class 'decimal.FloatOperation'>] 177 >>> Decimal('3.5') == 3.5 178 True 179 180.. versionadded:: 3.3 181 182The significance of a new Decimal is determined solely by the number of digits 183input. Context precision and rounding only come into play during arithmetic 184operations. 185 186.. doctest:: newcontext 187 188 >>> getcontext().prec = 6 189 >>> Decimal('3.0') 190 Decimal('3.0') 191 >>> Decimal('3.1415926535') 192 Decimal('3.1415926535') 193 >>> Decimal('3.1415926535') + Decimal('2.7182818285') 194 Decimal('5.85987') 195 >>> getcontext().rounding = ROUND_UP 196 >>> Decimal('3.1415926535') + Decimal('2.7182818285') 197 Decimal('5.85988') 198 199If the internal limits of the C version are exceeded, constructing 200a decimal raises :class:`InvalidOperation`:: 201 202 >>> Decimal("1e9999999999999999999") 203 Traceback (most recent call last): 204 File "<stdin>", line 1, in <module> 205 decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>] 206 207.. versionchanged:: 3.3 208 209Decimals interact well with much of the rest of Python. Here is a small decimal 210floating point flying circus: 211 212.. doctest:: 213 :options: +NORMALIZE_WHITESPACE 214 215 >>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())) 216 >>> max(data) 217 Decimal('9.25') 218 >>> min(data) 219 Decimal('0.03') 220 >>> sorted(data) 221 [Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'), 222 Decimal('2.35'), Decimal('3.45'), Decimal('9.25')] 223 >>> sum(data) 224 Decimal('19.29') 225 >>> a,b,c = data[:3] 226 >>> str(a) 227 '1.34' 228 >>> float(a) 229 1.34 230 >>> round(a, 1) 231 Decimal('1.3') 232 >>> int(a) 233 1 234 >>> a * 5 235 Decimal('6.70') 236 >>> a * b 237 Decimal('2.5058') 238 >>> c % a 239 Decimal('0.77') 240 241And some mathematical functions are also available to Decimal: 242 243 >>> getcontext().prec = 28 244 >>> Decimal(2).sqrt() 245 Decimal('1.414213562373095048801688724') 246 >>> Decimal(1).exp() 247 Decimal('2.718281828459045235360287471') 248 >>> Decimal('10').ln() 249 Decimal('2.302585092994045684017991455') 250 >>> Decimal('10').log10() 251 Decimal('1') 252 253The :meth:`quantize` method rounds a number to a fixed exponent. This method is 254useful for monetary applications that often round results to a fixed number of 255places: 256 257 >>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN) 258 Decimal('7.32') 259 >>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP) 260 Decimal('8') 261 262As shown above, the :func:`getcontext` function accesses the current context and 263allows the settings to be changed. This approach meets the needs of most 264applications. 265 266For more advanced work, it may be useful to create alternate contexts using the 267Context() constructor. To make an alternate active, use the :func:`setcontext` 268function. 269 270In accordance with the standard, the :mod:`decimal` module provides two ready to 271use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The 272former is especially useful for debugging because many of the traps are 273enabled: 274 275.. doctest:: newcontext 276 :options: +NORMALIZE_WHITESPACE 277 278 >>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN) 279 >>> setcontext(myothercontext) 280 >>> Decimal(1) / Decimal(7) 281 Decimal('0.142857142857142857142857142857142857142857142857142857142857') 282 283 >>> ExtendedContext 284 Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999, 285 capitals=1, clamp=0, flags=[], traps=[]) 286 >>> setcontext(ExtendedContext) 287 >>> Decimal(1) / Decimal(7) 288 Decimal('0.142857143') 289 >>> Decimal(42) / Decimal(0) 290 Decimal('Infinity') 291 292 >>> setcontext(BasicContext) 293 >>> Decimal(42) / Decimal(0) 294 Traceback (most recent call last): 295 File "<pyshell#143>", line 1, in -toplevel- 296 Decimal(42) / Decimal(0) 297 DivisionByZero: x / 0 298 299Contexts also have signal flags for monitoring exceptional conditions 300encountered during computations. The flags remain set until explicitly cleared, 301so it is best to clear the flags before each set of monitored computations by 302using the :meth:`clear_flags` method. :: 303 304 >>> setcontext(ExtendedContext) 305 >>> getcontext().clear_flags() 306 >>> Decimal(355) / Decimal(113) 307 Decimal('3.14159292') 308 >>> getcontext() 309 Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999, 310 capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[]) 311 312The *flags* entry shows that the rational approximation to :const:`Pi` was 313rounded (digits beyond the context precision were thrown away) and that the 314result is inexact (some of the discarded digits were non-zero). 315 316Individual traps are set using the dictionary in the :attr:`traps` field of a 317context: 318 319.. doctest:: newcontext 320 321 >>> setcontext(ExtendedContext) 322 >>> Decimal(1) / Decimal(0) 323 Decimal('Infinity') 324 >>> getcontext().traps[DivisionByZero] = 1 325 >>> Decimal(1) / Decimal(0) 326 Traceback (most recent call last): 327 File "<pyshell#112>", line 1, in -toplevel- 328 Decimal(1) / Decimal(0) 329 DivisionByZero: x / 0 330 331Most programs adjust the current context only once, at the beginning of the 332program. And, in many applications, data is converted to :class:`Decimal` with 333a single cast inside a loop. With context set and decimals created, the bulk of 334the program manipulates the data no differently than with other Python numeric 335types. 336 337.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 338 339 340.. _decimal-decimal: 341 342Decimal objects 343--------------- 344 345 346.. class:: Decimal(value="0", context=None) 347 348 Construct a new :class:`Decimal` object based from *value*. 349 350 *value* can be an integer, string, tuple, :class:`float`, or another :class:`Decimal` 351 object. If no *value* is given, returns ``Decimal('0')``. If *value* is a 352 string, it should conform to the decimal numeric string syntax after leading 353 and trailing whitespace characters, as well as underscores throughout, are removed:: 354 355 sign ::= '+' | '-' 356 digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' 357 indicator ::= 'e' | 'E' 358 digits ::= digit [digit]... 359 decimal-part ::= digits '.' [digits] | ['.'] digits 360 exponent-part ::= indicator [sign] digits 361 infinity ::= 'Infinity' | 'Inf' 362 nan ::= 'NaN' [digits] | 'sNaN' [digits] 363 numeric-value ::= decimal-part [exponent-part] | infinity 364 numeric-string ::= [sign] numeric-value | [sign] nan 365 366 Other Unicode decimal digits are also permitted where ``digit`` 367 appears above. These include decimal digits from various other 368 alphabets (for example, Arabic-Indic and Devanāgarī digits) along 369 with the fullwidth digits ``'\uff10'`` through ``'\uff19'``. 370 371 If *value* is a :class:`tuple`, it should have three components, a sign 372 (:const:`0` for positive or :const:`1` for negative), a :class:`tuple` of 373 digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))`` 374 returns ``Decimal('1.414')``. 375 376 If *value* is a :class:`float`, the binary floating point value is losslessly 377 converted to its exact decimal equivalent. This conversion can often require 378 53 or more digits of precision. For example, ``Decimal(float('1.1'))`` 379 converts to 380 ``Decimal('1.100000000000000088817841970012523233890533447265625')``. 381 382 The *context* precision does not affect how many digits are stored. That is 383 determined exclusively by the number of digits in *value*. For example, 384 ``Decimal('3.00000')`` records all five zeros even if the context precision is 385 only three. 386 387 The purpose of the *context* argument is determining what to do if *value* is a 388 malformed string. If the context traps :const:`InvalidOperation`, an exception 389 is raised; otherwise, the constructor returns a new Decimal with the value of 390 :const:`NaN`. 391 392 Once constructed, :class:`Decimal` objects are immutable. 393 394 .. versionchanged:: 3.2 395 The argument to the constructor is now permitted to be a :class:`float` 396 instance. 397 398 .. versionchanged:: 3.3 399 :class:`float` arguments raise an exception if the :exc:`FloatOperation` 400 trap is set. By default the trap is off. 401 402 .. versionchanged:: 3.6 403 Underscores are allowed for grouping, as with integral and floating-point 404 literals in code. 405 406 Decimal floating point objects share many properties with the other built-in 407 numeric types such as :class:`float` and :class:`int`. All of the usual math 408 operations and special methods apply. Likewise, decimal objects can be 409 copied, pickled, printed, used as dictionary keys, used as set elements, 410 compared, sorted, and coerced to another type (such as :class:`float` or 411 :class:`int`). 412 413 There are some small differences between arithmetic on Decimal objects and 414 arithmetic on integers and floats. When the remainder operator ``%`` is 415 applied to Decimal objects, the sign of the result is the sign of the 416 *dividend* rather than the sign of the divisor:: 417 418 >>> (-7) % 4 419 1 420 >>> Decimal(-7) % Decimal(4) 421 Decimal('-3') 422 423 The integer division operator ``//`` behaves analogously, returning the 424 integer part of the true quotient (truncating towards zero) rather than its 425 floor, so as to preserve the usual identity ``x == (x // y) * y + x % y``:: 426 427 >>> -7 // 4 428 -2 429 >>> Decimal(-7) // Decimal(4) 430 Decimal('-1') 431 432 The ``%`` and ``//`` operators implement the ``remainder`` and 433 ``divide-integer`` operations (respectively) as described in the 434 specification. 435 436 Decimal objects cannot generally be combined with floats or 437 instances of :class:`fractions.Fraction` in arithmetic operations: 438 an attempt to add a :class:`Decimal` to a :class:`float`, for 439 example, will raise a :exc:`TypeError`. However, it is possible to 440 use Python's comparison operators to compare a :class:`Decimal` 441 instance ``x`` with another number ``y``. This avoids confusing results 442 when doing equality comparisons between numbers of different types. 443 444 .. versionchanged:: 3.2 445 Mixed-type comparisons between :class:`Decimal` instances and other 446 numeric types are now fully supported. 447 448 In addition to the standard numeric properties, decimal floating point 449 objects also have a number of specialized methods: 450 451 452 .. method:: adjusted() 453 454 Return the adjusted exponent after shifting out the coefficient's 455 rightmost digits until only the lead digit remains: 456 ``Decimal('321e+5').adjusted()`` returns seven. Used for determining the 457 position of the most significant digit with respect to the decimal point. 458 459 .. method:: as_integer_ratio() 460 461 Return a pair ``(n, d)`` of integers that represent the given 462 :class:`Decimal` instance as a fraction, in lowest terms and 463 with a positive denominator:: 464 465 >>> Decimal('-3.14').as_integer_ratio() 466 (-157, 50) 467 468 The conversion is exact. Raise OverflowError on infinities and ValueError 469 on NaNs. 470 471 .. versionadded:: 3.6 472 473 .. method:: as_tuple() 474 475 Return a :term:`named tuple` representation of the number: 476 ``DecimalTuple(sign, digits, exponent)``. 477 478 479 .. method:: canonical() 480 481 Return the canonical encoding of the argument. Currently, the encoding of 482 a :class:`Decimal` instance is always canonical, so this operation returns 483 its argument unchanged. 484 485 .. method:: compare(other, context=None) 486 487 Compare the values of two Decimal instances. :meth:`compare` returns a 488 Decimal instance, and if either operand is a NaN then the result is a 489 NaN:: 490 491 a or b is a NaN ==> Decimal('NaN') 492 a < b ==> Decimal('-1') 493 a == b ==> Decimal('0') 494 a > b ==> Decimal('1') 495 496 .. method:: compare_signal(other, context=None) 497 498 This operation is identical to the :meth:`compare` method, except that all 499 NaNs signal. That is, if neither operand is a signaling NaN then any 500 quiet NaN operand is treated as though it were a signaling NaN. 501 502 .. method:: compare_total(other, context=None) 503 504 Compare two operands using their abstract representation rather than their 505 numerical value. Similar to the :meth:`compare` method, but the result 506 gives a total ordering on :class:`Decimal` instances. Two 507 :class:`Decimal` instances with the same numeric value but different 508 representations compare unequal in this ordering: 509 510 >>> Decimal('12.0').compare_total(Decimal('12')) 511 Decimal('-1') 512 513 Quiet and signaling NaNs are also included in the total ordering. The 514 result of this function is ``Decimal('0')`` if both operands have the same 515 representation, ``Decimal('-1')`` if the first operand is lower in the 516 total order than the second, and ``Decimal('1')`` if the first operand is 517 higher in the total order than the second operand. See the specification 518 for details of the total order. 519 520 This operation is unaffected by context and is quiet: no flags are changed 521 and no rounding is performed. As an exception, the C version may raise 522 InvalidOperation if the second operand cannot be converted exactly. 523 524 .. method:: compare_total_mag(other, context=None) 525 526 Compare two operands using their abstract representation rather than their 527 value as in :meth:`compare_total`, but ignoring the sign of each operand. 528 ``x.compare_total_mag(y)`` is equivalent to 529 ``x.copy_abs().compare_total(y.copy_abs())``. 530 531 This operation is unaffected by context and is quiet: no flags are changed 532 and no rounding is performed. As an exception, the C version may raise 533 InvalidOperation if the second operand cannot be converted exactly. 534 535 .. method:: conjugate() 536 537 Just returns self, this method is only to comply with the Decimal 538 Specification. 539 540 .. method:: copy_abs() 541 542 Return the absolute value of the argument. This operation is unaffected 543 by the context and is quiet: no flags are changed and no rounding is 544 performed. 545 546 .. method:: copy_negate() 547 548 Return the negation of the argument. This operation is unaffected by the 549 context and is quiet: no flags are changed and no rounding is performed. 550 551 .. method:: copy_sign(other, context=None) 552 553 Return a copy of the first operand with the sign set to be the same as the 554 sign of the second operand. For example: 555 556 >>> Decimal('2.3').copy_sign(Decimal('-1.5')) 557 Decimal('-2.3') 558 559 This operation is unaffected by context and is quiet: no flags are changed 560 and no rounding is performed. As an exception, the C version may raise 561 InvalidOperation if the second operand cannot be converted exactly. 562 563 .. method:: exp(context=None) 564 565 Return the value of the (natural) exponential function ``e**x`` at the 566 given number. The result is correctly rounded using the 567 :const:`ROUND_HALF_EVEN` rounding mode. 568 569 >>> Decimal(1).exp() 570 Decimal('2.718281828459045235360287471') 571 >>> Decimal(321).exp() 572 Decimal('2.561702493119680037517373933E+139') 573 574 .. method:: from_float(f) 575 576 Classmethod that converts a float to a decimal number, exactly. 577 578 Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`. 579 Since 0.1 is not exactly representable in binary floating point, the 580 value is stored as the nearest representable value which is 581 `0x1.999999999999ap-4`. That equivalent value in decimal is 582 `0.1000000000000000055511151231257827021181583404541015625`. 583 584 .. note:: From Python 3.2 onwards, a :class:`Decimal` instance 585 can also be constructed directly from a :class:`float`. 586 587 .. doctest:: 588 589 >>> Decimal.from_float(0.1) 590 Decimal('0.1000000000000000055511151231257827021181583404541015625') 591 >>> Decimal.from_float(float('nan')) 592 Decimal('NaN') 593 >>> Decimal.from_float(float('inf')) 594 Decimal('Infinity') 595 >>> Decimal.from_float(float('-inf')) 596 Decimal('-Infinity') 597 598 .. versionadded:: 3.1 599 600 .. method:: fma(other, third, context=None) 601 602 Fused multiply-add. Return self*other+third with no rounding of the 603 intermediate product self*other. 604 605 >>> Decimal(2).fma(3, 5) 606 Decimal('11') 607 608 .. method:: is_canonical() 609 610 Return :const:`True` if the argument is canonical and :const:`False` 611 otherwise. Currently, a :class:`Decimal` instance is always canonical, so 612 this operation always returns :const:`True`. 613 614 .. method:: is_finite() 615 616 Return :const:`True` if the argument is a finite number, and 617 :const:`False` if the argument is an infinity or a NaN. 618 619 .. method:: is_infinite() 620 621 Return :const:`True` if the argument is either positive or negative 622 infinity and :const:`False` otherwise. 623 624 .. method:: is_nan() 625 626 Return :const:`True` if the argument is a (quiet or signaling) NaN and 627 :const:`False` otherwise. 628 629 .. method:: is_normal(context=None) 630 631 Return :const:`True` if the argument is a *normal* finite number. Return 632 :const:`False` if the argument is zero, subnormal, infinite or a NaN. 633 634 .. method:: is_qnan() 635 636 Return :const:`True` if the argument is a quiet NaN, and 637 :const:`False` otherwise. 638 639 .. method:: is_signed() 640 641 Return :const:`True` if the argument has a negative sign and 642 :const:`False` otherwise. Note that zeros and NaNs can both carry signs. 643 644 .. method:: is_snan() 645 646 Return :const:`True` if the argument is a signaling NaN and :const:`False` 647 otherwise. 648 649 .. method:: is_subnormal(context=None) 650 651 Return :const:`True` if the argument is subnormal, and :const:`False` 652 otherwise. 653 654 .. method:: is_zero() 655 656 Return :const:`True` if the argument is a (positive or negative) zero and 657 :const:`False` otherwise. 658 659 .. method:: ln(context=None) 660 661 Return the natural (base e) logarithm of the operand. The result is 662 correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode. 663 664 .. method:: log10(context=None) 665 666 Return the base ten logarithm of the operand. The result is correctly 667 rounded using the :const:`ROUND_HALF_EVEN` rounding mode. 668 669 .. method:: logb(context=None) 670 671 For a nonzero number, return the adjusted exponent of its operand as a 672 :class:`Decimal` instance. If the operand is a zero then 673 ``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag 674 is raised. If the operand is an infinity then ``Decimal('Infinity')`` is 675 returned. 676 677 .. method:: logical_and(other, context=None) 678 679 :meth:`logical_and` is a logical operation which takes two *logical 680 operands* (see :ref:`logical_operands_label`). The result is the 681 digit-wise ``and`` of the two operands. 682 683 .. method:: logical_invert(context=None) 684 685 :meth:`logical_invert` is a logical operation. The 686 result is the digit-wise inversion of the operand. 687 688 .. method:: logical_or(other, context=None) 689 690 :meth:`logical_or` is a logical operation which takes two *logical 691 operands* (see :ref:`logical_operands_label`). The result is the 692 digit-wise ``or`` of the two operands. 693 694 .. method:: logical_xor(other, context=None) 695 696 :meth:`logical_xor` is a logical operation which takes two *logical 697 operands* (see :ref:`logical_operands_label`). The result is the 698 digit-wise exclusive or of the two operands. 699 700 .. method:: max(other, context=None) 701 702 Like ``max(self, other)`` except that the context rounding rule is applied 703 before returning and that :const:`NaN` values are either signaled or 704 ignored (depending on the context and whether they are signaling or 705 quiet). 706 707 .. method:: max_mag(other, context=None) 708 709 Similar to the :meth:`.max` method, but the comparison is done using the 710 absolute values of the operands. 711 712 .. method:: min(other, context=None) 713 714 Like ``min(self, other)`` except that the context rounding rule is applied 715 before returning and that :const:`NaN` values are either signaled or 716 ignored (depending on the context and whether they are signaling or 717 quiet). 718 719 .. method:: min_mag(other, context=None) 720 721 Similar to the :meth:`.min` method, but the comparison is done using the 722 absolute values of the operands. 723 724 .. method:: next_minus(context=None) 725 726 Return the largest number representable in the given context (or in the 727 current thread's context if no context is given) that is smaller than the 728 given operand. 729 730 .. method:: next_plus(context=None) 731 732 Return the smallest number representable in the given context (or in the 733 current thread's context if no context is given) that is larger than the 734 given operand. 735 736 .. method:: next_toward(other, context=None) 737 738 If the two operands are unequal, return the number closest to the first 739 operand in the direction of the second operand. If both operands are 740 numerically equal, return a copy of the first operand with the sign set to 741 be the same as the sign of the second operand. 742 743 .. method:: normalize(context=None) 744 745 Normalize the number by stripping the rightmost trailing zeros and 746 converting any result equal to :const:`Decimal('0')` to 747 :const:`Decimal('0e0')`. Used for producing canonical values for attributes 748 of an equivalence class. For example, ``Decimal('32.100')`` and 749 ``Decimal('0.321000e+2')`` both normalize to the equivalent value 750 ``Decimal('32.1')``. 751 752 .. method:: number_class(context=None) 753 754 Return a string describing the *class* of the operand. The returned value 755 is one of the following ten strings. 756 757 * ``"-Infinity"``, indicating that the operand is negative infinity. 758 * ``"-Normal"``, indicating that the operand is a negative normal number. 759 * ``"-Subnormal"``, indicating that the operand is negative and subnormal. 760 * ``"-Zero"``, indicating that the operand is a negative zero. 761 * ``"+Zero"``, indicating that the operand is a positive zero. 762 * ``"+Subnormal"``, indicating that the operand is positive and subnormal. 763 * ``"+Normal"``, indicating that the operand is a positive normal number. 764 * ``"+Infinity"``, indicating that the operand is positive infinity. 765 * ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number). 766 * ``"sNaN"``, indicating that the operand is a signaling NaN. 767 768 .. method:: quantize(exp, rounding=None, context=None) 769 770 Return a value equal to the first operand after rounding and having the 771 exponent of the second operand. 772 773 >>> Decimal('1.41421356').quantize(Decimal('1.000')) 774 Decimal('1.414') 775 776 Unlike other operations, if the length of the coefficient after the 777 quantize operation would be greater than precision, then an 778 :const:`InvalidOperation` is signaled. This guarantees that, unless there 779 is an error condition, the quantized exponent is always equal to that of 780 the right-hand operand. 781 782 Also unlike other operations, quantize never signals Underflow, even if 783 the result is subnormal and inexact. 784 785 If the exponent of the second operand is larger than that of the first 786 then rounding may be necessary. In this case, the rounding mode is 787 determined by the ``rounding`` argument if given, else by the given 788 ``context`` argument; if neither argument is given the rounding mode of 789 the current thread's context is used. 790 791 An error is returned whenever the resulting exponent is greater than 792 :attr:`Emax` or less than :attr:`Etiny`. 793 794 .. method:: radix() 795 796 Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal` 797 class does all its arithmetic. Included for compatibility with the 798 specification. 799 800 .. method:: remainder_near(other, context=None) 801 802 Return the remainder from dividing *self* by *other*. This differs from 803 ``self % other`` in that the sign of the remainder is chosen so as to 804 minimize its absolute value. More precisely, the return value is 805 ``self - n * other`` where ``n`` is the integer nearest to the exact 806 value of ``self / other``, and if two integers are equally near then the 807 even one is chosen. 808 809 If the result is zero then its sign will be the sign of *self*. 810 811 >>> Decimal(18).remainder_near(Decimal(10)) 812 Decimal('-2') 813 >>> Decimal(25).remainder_near(Decimal(10)) 814 Decimal('5') 815 >>> Decimal(35).remainder_near(Decimal(10)) 816 Decimal('-5') 817 818 .. method:: rotate(other, context=None) 819 820 Return the result of rotating the digits of the first operand by an amount 821 specified by the second operand. The second operand must be an integer in 822 the range -precision through precision. The absolute value of the second 823 operand gives the number of places to rotate. If the second operand is 824 positive then rotation is to the left; otherwise rotation is to the right. 825 The coefficient of the first operand is padded on the left with zeros to 826 length precision if necessary. The sign and exponent of the first operand 827 are unchanged. 828 829 .. method:: same_quantum(other, context=None) 830 831 Test whether self and other have the same exponent or whether both are 832 :const:`NaN`. 833 834 This operation is unaffected by context and is quiet: no flags are changed 835 and no rounding is performed. As an exception, the C version may raise 836 InvalidOperation if the second operand cannot be converted exactly. 837 838 .. method:: scaleb(other, context=None) 839 840 Return the first operand with exponent adjusted by the second. 841 Equivalently, return the first operand multiplied by ``10**other``. The 842 second operand must be an integer. 843 844 .. method:: shift(other, context=None) 845 846 Return the result of shifting the digits of the first operand by an amount 847 specified by the second operand. The second operand must be an integer in 848 the range -precision through precision. The absolute value of the second 849 operand gives the number of places to shift. If the second operand is 850 positive then the shift is to the left; otherwise the shift is to the 851 right. Digits shifted into the coefficient are zeros. The sign and 852 exponent of the first operand are unchanged. 853 854 .. method:: sqrt(context=None) 855 856 Return the square root of the argument to full precision. 857 858 859 .. method:: to_eng_string(context=None) 860 861 Convert to a string, using engineering notation if an exponent is needed. 862 863 Engineering notation has an exponent which is a multiple of 3. This 864 can leave up to 3 digits to the left of the decimal place and may 865 require the addition of either one or two trailing zeros. 866 867 For example, this converts ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``. 868 869 .. method:: to_integral(rounding=None, context=None) 870 871 Identical to the :meth:`to_integral_value` method. The ``to_integral`` 872 name has been kept for compatibility with older versions. 873 874 .. method:: to_integral_exact(rounding=None, context=None) 875 876 Round to the nearest integer, signaling :const:`Inexact` or 877 :const:`Rounded` as appropriate if rounding occurs. The rounding mode is 878 determined by the ``rounding`` parameter if given, else by the given 879 ``context``. If neither parameter is given then the rounding mode of the 880 current context is used. 881 882 .. method:: to_integral_value(rounding=None, context=None) 883 884 Round to the nearest integer without signaling :const:`Inexact` or 885 :const:`Rounded`. If given, applies *rounding*; otherwise, uses the 886 rounding method in either the supplied *context* or the current context. 887 888 889.. _logical_operands_label: 890 891Logical operands 892^^^^^^^^^^^^^^^^ 893 894The :meth:`logical_and`, :meth:`logical_invert`, :meth:`logical_or`, 895and :meth:`logical_xor` methods expect their arguments to be *logical 896operands*. A *logical operand* is a :class:`Decimal` instance whose 897exponent and sign are both zero, and whose digits are all either 898:const:`0` or :const:`1`. 899 900.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 901 902 903.. _decimal-context: 904 905Context objects 906--------------- 907 908Contexts are environments for arithmetic operations. They govern precision, set 909rules for rounding, determine which signals are treated as exceptions, and limit 910the range for exponents. 911 912Each thread has its own current context which is accessed or changed using the 913:func:`getcontext` and :func:`setcontext` functions: 914 915 916.. function:: getcontext() 917 918 Return the current context for the active thread. 919 920 921.. function:: setcontext(c) 922 923 Set the current context for the active thread to *c*. 924 925You can also use the :keyword:`with` statement and the :func:`localcontext` 926function to temporarily change the active context. 927 928.. function:: localcontext(ctx=None) 929 930 Return a context manager that will set the current context for the active thread 931 to a copy of *ctx* on entry to the with-statement and restore the previous context 932 when exiting the with-statement. If no context is specified, a copy of the 933 current context is used. 934 935 For example, the following code sets the current decimal precision to 42 places, 936 performs a calculation, and then automatically restores the previous context:: 937 938 from decimal import localcontext 939 940 with localcontext() as ctx: 941 ctx.prec = 42 # Perform a high precision calculation 942 s = calculate_something() 943 s = +s # Round the final result back to the default precision 944 945New contexts can also be created using the :class:`Context` constructor 946described below. In addition, the module provides three pre-made contexts: 947 948 949.. class:: BasicContext 950 951 This is a standard context defined by the General Decimal Arithmetic 952 Specification. Precision is set to nine. Rounding is set to 953 :const:`ROUND_HALF_UP`. All flags are cleared. All traps are enabled (treated 954 as exceptions) except :const:`Inexact`, :const:`Rounded`, and 955 :const:`Subnormal`. 956 957 Because many of the traps are enabled, this context is useful for debugging. 958 959 960.. class:: ExtendedContext 961 962 This is a standard context defined by the General Decimal Arithmetic 963 Specification. Precision is set to nine. Rounding is set to 964 :const:`ROUND_HALF_EVEN`. All flags are cleared. No traps are enabled (so that 965 exceptions are not raised during computations). 966 967 Because the traps are disabled, this context is useful for applications that 968 prefer to have result value of :const:`NaN` or :const:`Infinity` instead of 969 raising exceptions. This allows an application to complete a run in the 970 presence of conditions that would otherwise halt the program. 971 972 973.. class:: DefaultContext 974 975 This context is used by the :class:`Context` constructor as a prototype for new 976 contexts. Changing a field (such a precision) has the effect of changing the 977 default for new contexts created by the :class:`Context` constructor. 978 979 This context is most useful in multi-threaded environments. Changing one of the 980 fields before threads are started has the effect of setting system-wide 981 defaults. Changing the fields after threads have started is not recommended as 982 it would require thread synchronization to prevent race conditions. 983 984 In single threaded environments, it is preferable to not use this context at 985 all. Instead, simply create contexts explicitly as described below. 986 987 The default values are :attr:`prec`\ =\ :const:`28`, 988 :attr:`rounding`\ =\ :const:`ROUND_HALF_EVEN`, 989 and enabled traps for :class:`Overflow`, :class:`InvalidOperation`, and 990 :class:`DivisionByZero`. 991 992In addition to the three supplied contexts, new contexts can be created with the 993:class:`Context` constructor. 994 995 996.. class:: Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None) 997 998 Creates a new context. If a field is not specified or is :const:`None`, the 999 default values are copied from the :const:`DefaultContext`. If the *flags* 1000 field is not specified or is :const:`None`, all flags are cleared. 1001 1002 *prec* is an integer in the range [:const:`1`, :const:`MAX_PREC`] that sets 1003 the precision for arithmetic operations in the context. 1004 1005 The *rounding* option is one of the constants listed in the section 1006 `Rounding Modes`_. 1007 1008 The *traps* and *flags* fields list any signals to be set. Generally, new 1009 contexts should only set traps and leave the flags clear. 1010 1011 The *Emin* and *Emax* fields are integers specifying the outer limits allowable 1012 for exponents. *Emin* must be in the range [:const:`MIN_EMIN`, :const:`0`], 1013 *Emax* in the range [:const:`0`, :const:`MAX_EMAX`]. 1014 1015 The *capitals* field is either :const:`0` or :const:`1` (the default). If set to 1016 :const:`1`, exponents are printed with a capital :const:`E`; otherwise, a 1017 lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`. 1018 1019 The *clamp* field is either :const:`0` (the default) or :const:`1`. 1020 If set to :const:`1`, the exponent ``e`` of a :class:`Decimal` 1021 instance representable in this context is strictly limited to the 1022 range ``Emin - prec + 1 <= e <= Emax - prec + 1``. If *clamp* is 1023 :const:`0` then a weaker condition holds: the adjusted exponent of 1024 the :class:`Decimal` instance is at most ``Emax``. When *clamp* is 1025 :const:`1`, a large normal number will, where possible, have its 1026 exponent reduced and a corresponding number of zeros added to its 1027 coefficient, in order to fit the exponent constraints; this 1028 preserves the value of the number but loses information about 1029 significant trailing zeros. For example:: 1030 1031 >>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999') 1032 Decimal('1.23000E+999') 1033 1034 A *clamp* value of :const:`1` allows compatibility with the 1035 fixed-width decimal interchange formats specified in IEEE 754. 1036 1037 The :class:`Context` class defines several general purpose methods as well as 1038 a large number of methods for doing arithmetic directly in a given context. 1039 In addition, for each of the :class:`Decimal` methods described above (with 1040 the exception of the :meth:`adjusted` and :meth:`as_tuple` methods) there is 1041 a corresponding :class:`Context` method. For example, for a :class:`Context` 1042 instance ``C`` and :class:`Decimal` instance ``x``, ``C.exp(x)`` is 1043 equivalent to ``x.exp(context=C)``. Each :class:`Context` method accepts a 1044 Python integer (an instance of :class:`int`) anywhere that a 1045 Decimal instance is accepted. 1046 1047 1048 .. method:: clear_flags() 1049 1050 Resets all of the flags to :const:`0`. 1051 1052 .. method:: clear_traps() 1053 1054 Resets all of the traps to :const:`0`. 1055 1056 .. versionadded:: 3.3 1057 1058 .. method:: copy() 1059 1060 Return a duplicate of the context. 1061 1062 .. method:: copy_decimal(num) 1063 1064 Return a copy of the Decimal instance num. 1065 1066 .. method:: create_decimal(num) 1067 1068 Creates a new Decimal instance from *num* but using *self* as 1069 context. Unlike the :class:`Decimal` constructor, the context precision, 1070 rounding method, flags, and traps are applied to the conversion. 1071 1072 This is useful because constants are often given to a greater precision 1073 than is needed by the application. Another benefit is that rounding 1074 immediately eliminates unintended effects from digits beyond the current 1075 precision. In the following example, using unrounded inputs means that 1076 adding zero to a sum can change the result: 1077 1078 .. doctest:: newcontext 1079 1080 >>> getcontext().prec = 3 1081 >>> Decimal('3.4445') + Decimal('1.0023') 1082 Decimal('4.45') 1083 >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023') 1084 Decimal('4.44') 1085 1086 This method implements the to-number operation of the IBM specification. 1087 If the argument is a string, no leading or trailing whitespace or 1088 underscores are permitted. 1089 1090 .. method:: create_decimal_from_float(f) 1091 1092 Creates a new Decimal instance from a float *f* but rounding using *self* 1093 as the context. Unlike the :meth:`Decimal.from_float` class method, 1094 the context precision, rounding method, flags, and traps are applied to 1095 the conversion. 1096 1097 .. doctest:: 1098 1099 >>> context = Context(prec=5, rounding=ROUND_DOWN) 1100 >>> context.create_decimal_from_float(math.pi) 1101 Decimal('3.1415') 1102 >>> context = Context(prec=5, traps=[Inexact]) 1103 >>> context.create_decimal_from_float(math.pi) 1104 Traceback (most recent call last): 1105 ... 1106 decimal.Inexact: None 1107 1108 .. versionadded:: 3.1 1109 1110 .. method:: Etiny() 1111 1112 Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent 1113 value for subnormal results. When underflow occurs, the exponent is set 1114 to :const:`Etiny`. 1115 1116 .. method:: Etop() 1117 1118 Returns a value equal to ``Emax - prec + 1``. 1119 1120 The usual approach to working with decimals is to create :class:`Decimal` 1121 instances and then apply arithmetic operations which take place within the 1122 current context for the active thread. An alternative approach is to use 1123 context methods for calculating within a specific context. The methods are 1124 similar to those for the :class:`Decimal` class and are only briefly 1125 recounted here. 1126 1127 1128 .. method:: abs(x) 1129 1130 Returns the absolute value of *x*. 1131 1132 1133 .. method:: add(x, y) 1134 1135 Return the sum of *x* and *y*. 1136 1137 1138 .. method:: canonical(x) 1139 1140 Returns the same Decimal object *x*. 1141 1142 1143 .. method:: compare(x, y) 1144 1145 Compares *x* and *y* numerically. 1146 1147 1148 .. method:: compare_signal(x, y) 1149 1150 Compares the values of the two operands numerically. 1151 1152 1153 .. method:: compare_total(x, y) 1154 1155 Compares two operands using their abstract representation. 1156 1157 1158 .. method:: compare_total_mag(x, y) 1159 1160 Compares two operands using their abstract representation, ignoring sign. 1161 1162 1163 .. method:: copy_abs(x) 1164 1165 Returns a copy of *x* with the sign set to 0. 1166 1167 1168 .. method:: copy_negate(x) 1169 1170 Returns a copy of *x* with the sign inverted. 1171 1172 1173 .. method:: copy_sign(x, y) 1174 1175 Copies the sign from *y* to *x*. 1176 1177 1178 .. method:: divide(x, y) 1179 1180 Return *x* divided by *y*. 1181 1182 1183 .. method:: divide_int(x, y) 1184 1185 Return *x* divided by *y*, truncated to an integer. 1186 1187 1188 .. method:: divmod(x, y) 1189 1190 Divides two numbers and returns the integer part of the result. 1191 1192 1193 .. method:: exp(x) 1194 1195 Returns `e ** x`. 1196 1197 1198 .. method:: fma(x, y, z) 1199 1200 Returns *x* multiplied by *y*, plus *z*. 1201 1202 1203 .. method:: is_canonical(x) 1204 1205 Returns ``True`` if *x* is canonical; otherwise returns ``False``. 1206 1207 1208 .. method:: is_finite(x) 1209 1210 Returns ``True`` if *x* is finite; otherwise returns ``False``. 1211 1212 1213 .. method:: is_infinite(x) 1214 1215 Returns ``True`` if *x* is infinite; otherwise returns ``False``. 1216 1217 1218 .. method:: is_nan(x) 1219 1220 Returns ``True`` if *x* is a qNaN or sNaN; otherwise returns ``False``. 1221 1222 1223 .. method:: is_normal(x) 1224 1225 Returns ``True`` if *x* is a normal number; otherwise returns ``False``. 1226 1227 1228 .. method:: is_qnan(x) 1229 1230 Returns ``True`` if *x* is a quiet NaN; otherwise returns ``False``. 1231 1232 1233 .. method:: is_signed(x) 1234 1235 Returns ``True`` if *x* is negative; otherwise returns ``False``. 1236 1237 1238 .. method:: is_snan(x) 1239 1240 Returns ``True`` if *x* is a signaling NaN; otherwise returns ``False``. 1241 1242 1243 .. method:: is_subnormal(x) 1244 1245 Returns ``True`` if *x* is subnormal; otherwise returns ``False``. 1246 1247 1248 .. method:: is_zero(x) 1249 1250 Returns ``True`` if *x* is a zero; otherwise returns ``False``. 1251 1252 1253 .. method:: ln(x) 1254 1255 Returns the natural (base e) logarithm of *x*. 1256 1257 1258 .. method:: log10(x) 1259 1260 Returns the base 10 logarithm of *x*. 1261 1262 1263 .. method:: logb(x) 1264 1265 Returns the exponent of the magnitude of the operand's MSD. 1266 1267 1268 .. method:: logical_and(x, y) 1269 1270 Applies the logical operation *and* between each operand's digits. 1271 1272 1273 .. method:: logical_invert(x) 1274 1275 Invert all the digits in *x*. 1276 1277 1278 .. method:: logical_or(x, y) 1279 1280 Applies the logical operation *or* between each operand's digits. 1281 1282 1283 .. method:: logical_xor(x, y) 1284 1285 Applies the logical operation *xor* between each operand's digits. 1286 1287 1288 .. method:: max(x, y) 1289 1290 Compares two values numerically and returns the maximum. 1291 1292 1293 .. method:: max_mag(x, y) 1294 1295 Compares the values numerically with their sign ignored. 1296 1297 1298 .. method:: min(x, y) 1299 1300 Compares two values numerically and returns the minimum. 1301 1302 1303 .. method:: min_mag(x, y) 1304 1305 Compares the values numerically with their sign ignored. 1306 1307 1308 .. method:: minus(x) 1309 1310 Minus corresponds to the unary prefix minus operator in Python. 1311 1312 1313 .. method:: multiply(x, y) 1314 1315 Return the product of *x* and *y*. 1316 1317 1318 .. method:: next_minus(x) 1319 1320 Returns the largest representable number smaller than *x*. 1321 1322 1323 .. method:: next_plus(x) 1324 1325 Returns the smallest representable number larger than *x*. 1326 1327 1328 .. method:: next_toward(x, y) 1329 1330 Returns the number closest to *x*, in direction towards *y*. 1331 1332 1333 .. method:: normalize(x) 1334 1335 Reduces *x* to its simplest form. 1336 1337 1338 .. method:: number_class(x) 1339 1340 Returns an indication of the class of *x*. 1341 1342 1343 .. method:: plus(x) 1344 1345 Plus corresponds to the unary prefix plus operator in Python. This 1346 operation applies the context precision and rounding, so it is *not* an 1347 identity operation. 1348 1349 1350 .. method:: power(x, y, modulo=None) 1351 1352 Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given. 1353 1354 With two arguments, compute ``x**y``. If ``x`` is negative then ``y`` 1355 must be integral. The result will be inexact unless ``y`` is integral and 1356 the result is finite and can be expressed exactly in 'precision' digits. 1357 The rounding mode of the context is used. Results are always correctly-rounded 1358 in the Python version. 1359 1360 ``Decimal(0) ** Decimal(0)`` results in ``InvalidOperation``, and if ``InvalidOperation`` 1361 is not trapped, then results in ``Decimal('NaN')``. 1362 1363 .. versionchanged:: 3.3 1364 The C module computes :meth:`power` in terms of the correctly-rounded 1365 :meth:`exp` and :meth:`ln` functions. The result is well-defined but 1366 only "almost always correctly-rounded". 1367 1368 With three arguments, compute ``(x**y) % modulo``. For the three argument 1369 form, the following restrictions on the arguments hold: 1370 1371 - all three arguments must be integral 1372 - ``y`` must be nonnegative 1373 - at least one of ``x`` or ``y`` must be nonzero 1374 - ``modulo`` must be nonzero and have at most 'precision' digits 1375 1376 The value resulting from ``Context.power(x, y, modulo)`` is 1377 equal to the value that would be obtained by computing ``(x**y) 1378 % modulo`` with unbounded precision, but is computed more 1379 efficiently. The exponent of the result is zero, regardless of 1380 the exponents of ``x``, ``y`` and ``modulo``. The result is 1381 always exact. 1382 1383 1384 .. method:: quantize(x, y) 1385 1386 Returns a value equal to *x* (rounded), having the exponent of *y*. 1387 1388 1389 .. method:: radix() 1390 1391 Just returns 10, as this is Decimal, :) 1392 1393 1394 .. method:: remainder(x, y) 1395 1396 Returns the remainder from integer division. 1397 1398 The sign of the result, if non-zero, is the same as that of the original 1399 dividend. 1400 1401 1402 .. method:: remainder_near(x, y) 1403 1404 Returns ``x - y * n``, where *n* is the integer nearest the exact value 1405 of ``x / y`` (if the result is 0 then its sign will be the sign of *x*). 1406 1407 1408 .. method:: rotate(x, y) 1409 1410 Returns a rotated copy of *x*, *y* times. 1411 1412 1413 .. method:: same_quantum(x, y) 1414 1415 Returns ``True`` if the two operands have the same exponent. 1416 1417 1418 .. method:: scaleb (x, y) 1419 1420 Returns the first operand after adding the second value its exp. 1421 1422 1423 .. method:: shift(x, y) 1424 1425 Returns a shifted copy of *x*, *y* times. 1426 1427 1428 .. method:: sqrt(x) 1429 1430 Square root of a non-negative number to context precision. 1431 1432 1433 .. method:: subtract(x, y) 1434 1435 Return the difference between *x* and *y*. 1436 1437 1438 .. method:: to_eng_string(x) 1439 1440 Convert to a string, using engineering notation if an exponent is needed. 1441 1442 Engineering notation has an exponent which is a multiple of 3. This 1443 can leave up to 3 digits to the left of the decimal place and may 1444 require the addition of either one or two trailing zeros. 1445 1446 1447 .. method:: to_integral_exact(x) 1448 1449 Rounds to an integer. 1450 1451 1452 .. method:: to_sci_string(x) 1453 1454 Converts a number to a string using scientific notation. 1455 1456.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1457 1458.. _decimal-rounding-modes: 1459 1460Constants 1461--------- 1462 1463The constants in this section are only relevant for the C module. They 1464are also included in the pure Python version for compatibility. 1465 1466+---------------------+---------------------+-------------------------------+ 1467| | 32-bit | 64-bit | 1468+=====================+=====================+===============================+ 1469| .. data:: MAX_PREC | :const:`425000000` | :const:`999999999999999999` | 1470+---------------------+---------------------+-------------------------------+ 1471| .. data:: MAX_EMAX | :const:`425000000` | :const:`999999999999999999` | 1472+---------------------+---------------------+-------------------------------+ 1473| .. data:: MIN_EMIN | :const:`-425000000` | :const:`-999999999999999999` | 1474+---------------------+---------------------+-------------------------------+ 1475| .. data:: MIN_ETINY | :const:`-849999999` | :const:`-1999999999999999997` | 1476+---------------------+---------------------+-------------------------------+ 1477 1478 1479.. data:: HAVE_THREADS 1480 1481 The value is ``True``. Deprecated, because Python now always has threads. 1482 1483.. deprecated:: 3.9 1484 1485.. data:: HAVE_CONTEXTVAR 1486 1487 The default value is ``True``. If Python is compiled ``--without-decimal-contextvar``, 1488 the C version uses a thread-local rather than a coroutine-local context and the value 1489 is ``False``. This is slightly faster in some nested context scenarios. 1490 1491.. versionadded:: 3.9 backported to 3.7 and 3.8. 1492 1493 1494Rounding modes 1495-------------- 1496 1497.. data:: ROUND_CEILING 1498 1499 Round towards :const:`Infinity`. 1500 1501.. data:: ROUND_DOWN 1502 1503 Round towards zero. 1504 1505.. data:: ROUND_FLOOR 1506 1507 Round towards :const:`-Infinity`. 1508 1509.. data:: ROUND_HALF_DOWN 1510 1511 Round to nearest with ties going towards zero. 1512 1513.. data:: ROUND_HALF_EVEN 1514 1515 Round to nearest with ties going to nearest even integer. 1516 1517.. data:: ROUND_HALF_UP 1518 1519 Round to nearest with ties going away from zero. 1520 1521.. data:: ROUND_UP 1522 1523 Round away from zero. 1524 1525.. data:: ROUND_05UP 1526 1527 Round away from zero if last digit after rounding towards zero would have 1528 been 0 or 5; otherwise round towards zero. 1529 1530 1531.. _decimal-signals: 1532 1533Signals 1534------- 1535 1536Signals represent conditions that arise during computation. Each corresponds to 1537one context flag and one context trap enabler. 1538 1539The context flag is set whenever the condition is encountered. After the 1540computation, flags may be checked for informational purposes (for instance, to 1541determine whether a computation was exact). After checking the flags, be sure to 1542clear all flags before starting the next computation. 1543 1544If the context's trap enabler is set for the signal, then the condition causes a 1545Python exception to be raised. For example, if the :class:`DivisionByZero` trap 1546is set, then a :exc:`DivisionByZero` exception is raised upon encountering the 1547condition. 1548 1549 1550.. class:: Clamped 1551 1552 Altered an exponent to fit representation constraints. 1553 1554 Typically, clamping occurs when an exponent falls outside the context's 1555 :attr:`Emin` and :attr:`Emax` limits. If possible, the exponent is reduced to 1556 fit by adding zeros to the coefficient. 1557 1558 1559.. class:: DecimalException 1560 1561 Base class for other signals and a subclass of :exc:`ArithmeticError`. 1562 1563 1564.. class:: DivisionByZero 1565 1566 Signals the division of a non-infinite number by zero. 1567 1568 Can occur with division, modulo division, or when raising a number to a negative 1569 power. If this signal is not trapped, returns :const:`Infinity` or 1570 :const:`-Infinity` with the sign determined by the inputs to the calculation. 1571 1572 1573.. class:: Inexact 1574 1575 Indicates that rounding occurred and the result is not exact. 1576 1577 Signals when non-zero digits were discarded during rounding. The rounded result 1578 is returned. The signal flag or trap is used to detect when results are 1579 inexact. 1580 1581 1582.. class:: InvalidOperation 1583 1584 An invalid operation was performed. 1585 1586 Indicates that an operation was requested that does not make sense. If not 1587 trapped, returns :const:`NaN`. Possible causes include:: 1588 1589 Infinity - Infinity 1590 0 * Infinity 1591 Infinity / Infinity 1592 x % 0 1593 Infinity % x 1594 sqrt(-x) and x > 0 1595 0 ** 0 1596 x ** (non-integer) 1597 x ** Infinity 1598 1599 1600.. class:: Overflow 1601 1602 Numerical overflow. 1603 1604 Indicates the exponent is larger than :attr:`Emax` after rounding has 1605 occurred. If not trapped, the result depends on the rounding mode, either 1606 pulling inward to the largest representable finite number or rounding outward 1607 to :const:`Infinity`. In either case, :class:`Inexact` and :class:`Rounded` 1608 are also signaled. 1609 1610 1611.. class:: Rounded 1612 1613 Rounding occurred though possibly no information was lost. 1614 1615 Signaled whenever rounding discards digits; even if those digits are zero 1616 (such as rounding :const:`5.00` to :const:`5.0`). If not trapped, returns 1617 the result unchanged. This signal is used to detect loss of significant 1618 digits. 1619 1620 1621.. class:: Subnormal 1622 1623 Exponent was lower than :attr:`Emin` prior to rounding. 1624 1625 Occurs when an operation result is subnormal (the exponent is too small). If 1626 not trapped, returns the result unchanged. 1627 1628 1629.. class:: Underflow 1630 1631 Numerical underflow with result rounded to zero. 1632 1633 Occurs when a subnormal result is pushed to zero by rounding. :class:`Inexact` 1634 and :class:`Subnormal` are also signaled. 1635 1636 1637.. class:: FloatOperation 1638 1639 Enable stricter semantics for mixing floats and Decimals. 1640 1641 If the signal is not trapped (default), mixing floats and Decimals is 1642 permitted in the :class:`~decimal.Decimal` constructor, 1643 :meth:`~decimal.Context.create_decimal` and all comparison operators. 1644 Both conversion and comparisons are exact. Any occurrence of a mixed 1645 operation is silently recorded by setting :exc:`FloatOperation` in the 1646 context flags. Explicit conversions with :meth:`~decimal.Decimal.from_float` 1647 or :meth:`~decimal.Context.create_decimal_from_float` do not set the flag. 1648 1649 Otherwise (the signal is trapped), only equality comparisons and explicit 1650 conversions are silent. All other mixed operations raise :exc:`FloatOperation`. 1651 1652 1653The following table summarizes the hierarchy of signals:: 1654 1655 exceptions.ArithmeticError(exceptions.Exception) 1656 DecimalException 1657 Clamped 1658 DivisionByZero(DecimalException, exceptions.ZeroDivisionError) 1659 Inexact 1660 Overflow(Inexact, Rounded) 1661 Underflow(Inexact, Rounded, Subnormal) 1662 InvalidOperation 1663 Rounded 1664 Subnormal 1665 FloatOperation(DecimalException, exceptions.TypeError) 1666 1667.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1668 1669 1670 1671.. _decimal-notes: 1672 1673Floating Point Notes 1674-------------------- 1675 1676 1677Mitigating round-off error with increased precision 1678^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1679 1680The use of decimal floating point eliminates decimal representation error 1681(making it possible to represent :const:`0.1` exactly); however, some operations 1682can still incur round-off error when non-zero digits exceed the fixed precision. 1683 1684The effects of round-off error can be amplified by the addition or subtraction 1685of nearly offsetting quantities resulting in loss of significance. Knuth 1686provides two instructive examples where rounded floating point arithmetic with 1687insufficient precision causes the breakdown of the associative and distributive 1688properties of addition: 1689 1690.. doctest:: newcontext 1691 1692 # Examples from Seminumerical Algorithms, Section 4.2.2. 1693 >>> from decimal import Decimal, getcontext 1694 >>> getcontext().prec = 8 1695 1696 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111') 1697 >>> (u + v) + w 1698 Decimal('9.5111111') 1699 >>> u + (v + w) 1700 Decimal('10') 1701 1702 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003') 1703 >>> (u*v) + (u*w) 1704 Decimal('0.01') 1705 >>> u * (v+w) 1706 Decimal('0.0060000') 1707 1708The :mod:`decimal` module makes it possible to restore the identities by 1709expanding the precision sufficiently to avoid loss of significance: 1710 1711.. doctest:: newcontext 1712 1713 >>> getcontext().prec = 20 1714 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111') 1715 >>> (u + v) + w 1716 Decimal('9.51111111') 1717 >>> u + (v + w) 1718 Decimal('9.51111111') 1719 >>> 1720 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003') 1721 >>> (u*v) + (u*w) 1722 Decimal('0.0060000') 1723 >>> u * (v+w) 1724 Decimal('0.0060000') 1725 1726 1727Special values 1728^^^^^^^^^^^^^^ 1729 1730The number system for the :mod:`decimal` module provides special values 1731including :const:`NaN`, :const:`sNaN`, :const:`-Infinity`, :const:`Infinity`, 1732and two zeros, :const:`+0` and :const:`-0`. 1733 1734Infinities can be constructed directly with: ``Decimal('Infinity')``. Also, 1735they can arise from dividing by zero when the :exc:`DivisionByZero` signal is 1736not trapped. Likewise, when the :exc:`Overflow` signal is not trapped, infinity 1737can result from rounding beyond the limits of the largest representable number. 1738 1739The infinities are signed (affine) and can be used in arithmetic operations 1740where they get treated as very large, indeterminate numbers. For instance, 1741adding a constant to infinity gives another infinite result. 1742 1743Some operations are indeterminate and return :const:`NaN`, or if the 1744:exc:`InvalidOperation` signal is trapped, raise an exception. For example, 1745``0/0`` returns :const:`NaN` which means "not a number". This variety of 1746:const:`NaN` is quiet and, once created, will flow through other computations 1747always resulting in another :const:`NaN`. This behavior can be useful for a 1748series of computations that occasionally have missing inputs --- it allows the 1749calculation to proceed while flagging specific results as invalid. 1750 1751A variant is :const:`sNaN` which signals rather than remaining quiet after every 1752operation. This is a useful return value when an invalid result needs to 1753interrupt a calculation for special handling. 1754 1755The behavior of Python's comparison operators can be a little surprising where a 1756:const:`NaN` is involved. A test for equality where one of the operands is a 1757quiet or signaling :const:`NaN` always returns :const:`False` (even when doing 1758``Decimal('NaN')==Decimal('NaN')``), while a test for inequality always returns 1759:const:`True`. An attempt to compare two Decimals using any of the ``<``, 1760``<=``, ``>`` or ``>=`` operators will raise the :exc:`InvalidOperation` signal 1761if either operand is a :const:`NaN`, and return :const:`False` if this signal is 1762not trapped. Note that the General Decimal Arithmetic specification does not 1763specify the behavior of direct comparisons; these rules for comparisons 1764involving a :const:`NaN` were taken from the IEEE 854 standard (see Table 3 in 1765section 5.7). To ensure strict standards-compliance, use the :meth:`compare` 1766and :meth:`compare-signal` methods instead. 1767 1768The signed zeros can result from calculations that underflow. They keep the sign 1769that would have resulted if the calculation had been carried out to greater 1770precision. Since their magnitude is zero, both positive and negative zeros are 1771treated as equal and their sign is informational. 1772 1773In addition to the two signed zeros which are distinct yet equal, there are 1774various representations of zero with differing precisions yet equivalent in 1775value. This takes a bit of getting used to. For an eye accustomed to 1776normalized floating point representations, it is not immediately obvious that 1777the following calculation returns a value equal to zero: 1778 1779 >>> 1 / Decimal('Infinity') 1780 Decimal('0E-1000026') 1781 1782.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1783 1784 1785.. _decimal-threads: 1786 1787Working with threads 1788-------------------- 1789 1790The :func:`getcontext` function accesses a different :class:`Context` object for 1791each thread. Having separate thread contexts means that threads may make 1792changes (such as ``getcontext().prec=10``) without interfering with other threads. 1793 1794Likewise, the :func:`setcontext` function automatically assigns its target to 1795the current thread. 1796 1797If :func:`setcontext` has not been called before :func:`getcontext`, then 1798:func:`getcontext` will automatically create a new context for use in the 1799current thread. 1800 1801The new context is copied from a prototype context called *DefaultContext*. To 1802control the defaults so that each thread will use the same values throughout the 1803application, directly modify the *DefaultContext* object. This should be done 1804*before* any threads are started so that there won't be a race condition between 1805threads calling :func:`getcontext`. For example:: 1806 1807 # Set applicationwide defaults for all threads about to be launched 1808 DefaultContext.prec = 12 1809 DefaultContext.rounding = ROUND_DOWN 1810 DefaultContext.traps = ExtendedContext.traps.copy() 1811 DefaultContext.traps[InvalidOperation] = 1 1812 setcontext(DefaultContext) 1813 1814 # Afterwards, the threads can be started 1815 t1.start() 1816 t2.start() 1817 t3.start() 1818 . . . 1819 1820.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1821 1822 1823.. _decimal-recipes: 1824 1825Recipes 1826------- 1827 1828Here are a few recipes that serve as utility functions and that demonstrate ways 1829to work with the :class:`Decimal` class:: 1830 1831 def moneyfmt(value, places=2, curr='', sep=',', dp='.', 1832 pos='', neg='-', trailneg=''): 1833 """Convert Decimal to a money formatted string. 1834 1835 places: required number of places after the decimal point 1836 curr: optional currency symbol before the sign (may be blank) 1837 sep: optional grouping separator (comma, period, space, or blank) 1838 dp: decimal point indicator (comma or period) 1839 only specify as blank when places is zero 1840 pos: optional sign for positive numbers: '+', space or blank 1841 neg: optional sign for negative numbers: '-', '(', space or blank 1842 trailneg:optional trailing minus indicator: '-', ')', space or blank 1843 1844 >>> d = Decimal('-1234567.8901') 1845 >>> moneyfmt(d, curr='$') 1846 '-$1,234,567.89' 1847 >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-') 1848 '1.234.568-' 1849 >>> moneyfmt(d, curr='$', neg='(', trailneg=')') 1850 '($1,234,567.89)' 1851 >>> moneyfmt(Decimal(123456789), sep=' ') 1852 '123 456 789.00' 1853 >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>') 1854 '<0.02>' 1855 1856 """ 1857 q = Decimal(10) ** -places # 2 places --> '0.01' 1858 sign, digits, exp = value.quantize(q).as_tuple() 1859 result = [] 1860 digits = list(map(str, digits)) 1861 build, next = result.append, digits.pop 1862 if sign: 1863 build(trailneg) 1864 for i in range(places): 1865 build(next() if digits else '0') 1866 if places: 1867 build(dp) 1868 if not digits: 1869 build('0') 1870 i = 0 1871 while digits: 1872 build(next()) 1873 i += 1 1874 if i == 3 and digits: 1875 i = 0 1876 build(sep) 1877 build(curr) 1878 build(neg if sign else pos) 1879 return ''.join(reversed(result)) 1880 1881 def pi(): 1882 """Compute Pi to the current precision. 1883 1884 >>> print(pi()) 1885 3.141592653589793238462643383 1886 1887 """ 1888 getcontext().prec += 2 # extra digits for intermediate steps 1889 three = Decimal(3) # substitute "three=3.0" for regular floats 1890 lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24 1891 while s != lasts: 1892 lasts = s 1893 n, na = n+na, na+8 1894 d, da = d+da, da+32 1895 t = (t * n) / d 1896 s += t 1897 getcontext().prec -= 2 1898 return +s # unary plus applies the new precision 1899 1900 def exp(x): 1901 """Return e raised to the power of x. Result type matches input type. 1902 1903 >>> print(exp(Decimal(1))) 1904 2.718281828459045235360287471 1905 >>> print(exp(Decimal(2))) 1906 7.389056098930650227230427461 1907 >>> print(exp(2.0)) 1908 7.38905609893 1909 >>> print(exp(2+0j)) 1910 (7.38905609893+0j) 1911 1912 """ 1913 getcontext().prec += 2 1914 i, lasts, s, fact, num = 0, 0, 1, 1, 1 1915 while s != lasts: 1916 lasts = s 1917 i += 1 1918 fact *= i 1919 num *= x 1920 s += num / fact 1921 getcontext().prec -= 2 1922 return +s 1923 1924 def cos(x): 1925 """Return the cosine of x as measured in radians. 1926 1927 The Taylor series approximation works best for a small value of x. 1928 For larger values, first compute x = x % (2 * pi). 1929 1930 >>> print(cos(Decimal('0.5'))) 1931 0.8775825618903727161162815826 1932 >>> print(cos(0.5)) 1933 0.87758256189 1934 >>> print(cos(0.5+0j)) 1935 (0.87758256189+0j) 1936 1937 """ 1938 getcontext().prec += 2 1939 i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1 1940 while s != lasts: 1941 lasts = s 1942 i += 2 1943 fact *= i * (i-1) 1944 num *= x * x 1945 sign *= -1 1946 s += num / fact * sign 1947 getcontext().prec -= 2 1948 return +s 1949 1950 def sin(x): 1951 """Return the sine of x as measured in radians. 1952 1953 The Taylor series approximation works best for a small value of x. 1954 For larger values, first compute x = x % (2 * pi). 1955 1956 >>> print(sin(Decimal('0.5'))) 1957 0.4794255386042030002732879352 1958 >>> print(sin(0.5)) 1959 0.479425538604 1960 >>> print(sin(0.5+0j)) 1961 (0.479425538604+0j) 1962 1963 """ 1964 getcontext().prec += 2 1965 i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1 1966 while s != lasts: 1967 lasts = s 1968 i += 2 1969 fact *= i * (i-1) 1970 num *= x * x 1971 sign *= -1 1972 s += num / fact * sign 1973 getcontext().prec -= 2 1974 return +s 1975 1976 1977.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1978 1979 1980.. _decimal-faq: 1981 1982Decimal FAQ 1983----------- 1984 1985Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to 1986minimize typing when using the interactive interpreter? 1987 1988A. Some users abbreviate the constructor to just a single letter: 1989 1990 >>> D = decimal.Decimal 1991 >>> D('1.23') + D('3.45') 1992 Decimal('4.68') 1993 1994Q. In a fixed-point application with two decimal places, some inputs have many 1995places and need to be rounded. Others are not supposed to have excess digits 1996and need to be validated. What methods should be used? 1997 1998A. The :meth:`quantize` method rounds to a fixed number of decimal places. If 1999the :const:`Inexact` trap is set, it is also useful for validation: 2000 2001 >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01') 2002 2003 >>> # Round to two places 2004 >>> Decimal('3.214').quantize(TWOPLACES) 2005 Decimal('3.21') 2006 2007 >>> # Validate that a number does not exceed two places 2008 >>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact])) 2009 Decimal('3.21') 2010 2011 >>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact])) 2012 Traceback (most recent call last): 2013 ... 2014 Inexact: None 2015 2016Q. Once I have valid two place inputs, how do I maintain that invariant 2017throughout an application? 2018 2019A. Some operations like addition, subtraction, and multiplication by an integer 2020will automatically preserve fixed point. Others operations, like division and 2021non-integer multiplication, will change the number of decimal places and need to 2022be followed-up with a :meth:`quantize` step: 2023 2024 >>> a = Decimal('102.72') # Initial fixed-point values 2025 >>> b = Decimal('3.17') 2026 >>> a + b # Addition preserves fixed-point 2027 Decimal('105.89') 2028 >>> a - b 2029 Decimal('99.55') 2030 >>> a * 42 # So does integer multiplication 2031 Decimal('4314.24') 2032 >>> (a * b).quantize(TWOPLACES) # Must quantize non-integer multiplication 2033 Decimal('325.62') 2034 >>> (b / a).quantize(TWOPLACES) # And quantize division 2035 Decimal('0.03') 2036 2037In developing fixed-point applications, it is convenient to define functions 2038to handle the :meth:`quantize` step: 2039 2040 >>> def mul(x, y, fp=TWOPLACES): 2041 ... return (x * y).quantize(fp) 2042 >>> def div(x, y, fp=TWOPLACES): 2043 ... return (x / y).quantize(fp) 2044 2045 >>> mul(a, b) # Automatically preserve fixed-point 2046 Decimal('325.62') 2047 >>> div(b, a) 2048 Decimal('0.03') 2049 2050Q. There are many ways to express the same value. The numbers :const:`200`, 2051:const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at 2052various precisions. Is there a way to transform them to a single recognizable 2053canonical value? 2054 2055A. The :meth:`normalize` method maps all equivalent values to a single 2056representative: 2057 2058 >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split()) 2059 >>> [v.normalize() for v in values] 2060 [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')] 2061 2062Q. Some decimal values always print with exponential notation. Is there a way 2063to get a non-exponential representation? 2064 2065A. For some values, exponential notation is the only way to express the number 2066of significant places in the coefficient. For example, expressing 2067:const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the 2068original's two-place significance. 2069 2070If an application does not care about tracking significance, it is easy to 2071remove the exponent and trailing zeroes, losing significance, but keeping the 2072value unchanged: 2073 2074 >>> def remove_exponent(d): 2075 ... return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize() 2076 2077 >>> remove_exponent(Decimal('5E+3')) 2078 Decimal('5000') 2079 2080Q. Is there a way to convert a regular float to a :class:`Decimal`? 2081 2082A. Yes, any binary floating point number can be exactly expressed as a 2083Decimal though an exact conversion may take more precision than intuition would 2084suggest: 2085 2086.. doctest:: 2087 2088 >>> Decimal(math.pi) 2089 Decimal('3.141592653589793115997963468544185161590576171875') 2090 2091Q. Within a complex calculation, how can I make sure that I haven't gotten a 2092spurious result because of insufficient precision or rounding anomalies. 2093 2094A. The decimal module makes it easy to test results. A best practice is to 2095re-run calculations using greater precision and with various rounding modes. 2096Widely differing results indicate insufficient precision, rounding mode issues, 2097ill-conditioned inputs, or a numerically unstable algorithm. 2098 2099Q. I noticed that context precision is applied to the results of operations but 2100not to the inputs. Is there anything to watch out for when mixing values of 2101different precisions? 2102 2103A. Yes. The principle is that all values are considered to be exact and so is 2104the arithmetic on those values. Only the results are rounded. The advantage 2105for inputs is that "what you type is what you get". A disadvantage is that the 2106results can look odd if you forget that the inputs haven't been rounded: 2107 2108.. doctest:: newcontext 2109 2110 >>> getcontext().prec = 3 2111 >>> Decimal('3.104') + Decimal('2.104') 2112 Decimal('5.21') 2113 >>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104') 2114 Decimal('5.20') 2115 2116The solution is either to increase precision or to force rounding of inputs 2117using the unary plus operation: 2118 2119.. doctest:: newcontext 2120 2121 >>> getcontext().prec = 3 2122 >>> +Decimal('1.23456789') # unary plus triggers rounding 2123 Decimal('1.23') 2124 2125Alternatively, inputs can be rounded upon creation using the 2126:meth:`Context.create_decimal` method: 2127 2128 >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678') 2129 Decimal('1.2345') 2130 2131Q. Is the CPython implementation fast for large numbers? 2132 2133A. Yes. In the CPython and PyPy3 implementations, the C/CFFI versions of 2134the decimal module integrate the high speed `libmpdec 2135<https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html>`_ library for 2136arbitrary precision correctly-rounded decimal floating point arithmetic [#]_. 2137``libmpdec`` uses `Karatsuba multiplication 2138<https://en.wikipedia.org/wiki/Karatsuba_algorithm>`_ 2139for medium-sized numbers and the `Number Theoretic Transform 2140<https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform>`_ 2141for very large numbers. 2142 2143The context must be adapted for exact arbitrary precision arithmetic. :attr:`Emin` 2144and :attr:`Emax` should always be set to the maximum values, :attr:`clamp` 2145should always be 0 (the default). Setting :attr:`prec` requires some care. 2146 2147The easiest approach for trying out bignum arithmetic is to use the maximum 2148value for :attr:`prec` as well [#]_:: 2149 2150 >>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN)) 2151 >>> x = Decimal(2) ** 256 2152 >>> x / 128 2153 Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312') 2154 2155 2156For inexact results, :attr:`MAX_PREC` is far too large on 64-bit platforms and 2157the available memory will be insufficient:: 2158 2159 >>> Decimal(1) / 3 2160 Traceback (most recent call last): 2161 File "<stdin>", line 1, in <module> 2162 MemoryError 2163 2164On systems with overallocation (e.g. Linux), a more sophisticated approach is to 2165adjust :attr:`prec` to the amount of available RAM. Suppose that you have 8GB of 2166RAM and expect 10 simultaneous operands using a maximum of 500MB each:: 2167 2168 >>> import sys 2169 >>> 2170 >>> # Maximum number of digits for a single operand using 500MB in 8-byte words 2171 >>> # with 19 digits per word (4-byte and 9 digits for the 32-bit build): 2172 >>> maxdigits = 19 * ((500 * 1024**2) // 8) 2173 >>> 2174 >>> # Check that this works: 2175 >>> c = Context(prec=maxdigits, Emax=MAX_EMAX, Emin=MIN_EMIN) 2176 >>> c.traps[Inexact] = True 2177 >>> setcontext(c) 2178 >>> 2179 >>> # Fill the available precision with nines: 2180 >>> x = Decimal(0).logical_invert() * 9 2181 >>> sys.getsizeof(x) 2182 524288112 2183 >>> x + 2 2184 Traceback (most recent call last): 2185 File "<stdin>", line 1, in <module> 2186 decimal.Inexact: [<class 'decimal.Inexact'>] 2187 2188In general (and especially on systems without overallocation), it is recommended 2189to estimate even tighter bounds and set the :attr:`Inexact` trap if all calculations 2190are expected to be exact. 2191 2192 2193.. [#] 2194 .. versionadded:: 3.3 2195 2196.. [#] 2197 .. versionchanged:: 3.9 2198 This approach now works for all exact results except for non-integer powers. 2199