Contexts are environments for arithmetic operations. They govern precision, set rules for rounding, determine which signals are treated as exceptions, and limit the range for exponents.
Each thread has its own current context which is accessed or changed using the getcontext() and setcontext() functions:
) |
c) |
New contexts can formed using the Context constructor described below. In addition, the module provides three pre-made contexts:
Because many of the traps are enabled, this context is useful for debugging.
Because the trapped are disabled, this context is useful for applications that prefer to have result value of NaN or Infinity instead of raising exceptions. This allows an application to complete a run in the presence of conditions that would otherwise halt the program.
This context is most useful in multi-threaded environments. Changing one of the fields before threads are started has the effect of setting system-wide defaults. Changing the fields after threads have started is not recommended as it would require thread synchronization to prevent race conditions.
In single threaded environments, it is preferable to not use this context at all. Instead, simply create contexts explicitly as described below.
The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled traps for Overflow, InvalidOperation, and DivisionByZero.
In addition to the three supplied contexts, new contexts can be created with the Context constructor.
prec=None, rounding=None, traps=None, flags=None, Emin=None, Emax=None, capitals=1) |
The prec field is a positive integer that sets the precision for arithmetic operations in the context.
The rounding option is one of:
The traps and flags fields list any signals to be set. Generally, new contexts should only set traps and leave the flags clear.
The Emin and Emax fields are integers specifying the outer limits allowable for exponents.
The capitals field is either 0 or 1 (the default). If set to 1, exponents are printed with a capital E; otherwise, a lowercase e is used: Decimal('6.02e+23').
The Context class defines several general purpose methods as well as a large number of methods for doing arithmetic directly in a given context.
) |
) |
num) |
This is useful because constants are often given to a greater precision than is needed by the application. Another benefit is that rounding immediately eliminates unintended effects from digits beyond the current precision. In the following example, using unrounded inputs means that adding zero to a sum can change the result:
>>> getcontext().prec = 3 >>> Decimal("3.4445") + Decimal("1.0023") Decimal("4.45") >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023") Decimal("4.44")
) |
) |
The usual approach to working with decimals is to create Decimal instances and then apply arithmetic operations which take place within the current context for the active thread. An alternate approach is to use context methods for calculating within a specific context. The methods are similar to those for the Decimal class and are only briefly recounted here.
x) |
x, y) |
x, y) |
Like __cmp__() but returns a decimal instance:
a or b is a NaN ==> Decimal("NaN") a < b ==> Decimal("-1") a == b ==> Decimal("0") a > b ==> Decimal("1")
x, y) |
x, y) |
x, y) |
If they are numerically equal then the left-hand operand is chosen as the result.
x, y) |
If they are numerically equal then the left-hand operand is chosen as the result.
x) |
x, y) |
x) |
Essentially a plus operation with all trailing zeros removed from the result.
x) |
x, y[, modulo]) |
The right-hand operand must be a whole number whose integer part (after any exponent has been applied) has no more than 9 digits and whose fractional part (if any) is all zeros before any rounding. The operand may be positive, negative, or zero; if negative, the absolute value of the power is used, and the left-hand operand is inverted (divided into 1) before use.
If the increased precision needed for the intermediate calculations exceeds the capabilities of the implementation then an InvalidOperation condition is signaled.
If, when raising to a negative power, an underflow occurs during the division into 1, the operation is not halted at that point but continues.
x, y) |
Unlike other operations, if the length of the coefficient after the quantize operation would be greater than precision, then an InvalidOperation is signaled. This guarantees that, unless there is an error condition, the quantized exponent is always equal to that of the right-hand operand.
Also unlike other operations, quantize never signals Underflow, even if the result is subnormal and inexact.
x, y) |
The sign of the result, if non-zero, is the same as that of the original dividend.
x, y) |
Decimal("-2")
which is closer to zero than Decimal("4")
.
If both are equally close, the one chosen will have the same sign as self.
x, y) |
) |
x, y) |
) |
Engineering notation has an exponent which is a multiple of 3, so there
are up to 3 digits left of the decimal place. For example, converts
Decimal('123E+1')
to Decimal("1.23E+3")
x) |
) |
See About this document... for information on suggesting changes.