decimal.Context

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

Creates a new context. If a field is not specified or is None, the default values are copied from the DefaultContext. If the flags field is not specified or is None, all flags are cleared.

prec is an integer in the range [1, MAX_PREC] that sets the precision for arithmetic operations in the context.

The rounding option is one of the constants listed in the section Rounding Modes.

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. Emin must be in the range [MIN_EMIN, 0], Emax in the range [0, MAX_EMAX].

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 clamp field is either 0 (the default) or 1. If set to 1, the exponent e of a Decimal instance representable in this context is strictly limited to the range Emin - prec + 1 <= e <= Emax - prec + 1. If clamp is 0 then a weaker condition holds: the adjusted exponent of the Decimal instance is at most Emax. When clamp is 1, a large normal number will, where possible, have its exponent reduced and a corresponding number of zeros added to its coefficient, in order to fit the exponent constraints; this preserves the value of the number but loses information about significant trailing zeros. For example:

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

A clamp value of 1 allows compatibility with the fixed-width decimal interchange formats specified in IEEE 754.

The Context class defines several general purpose methods as well as a large number of methods for doing arithmetic directly in a given context. In addition, for each of the Decimal methods described above (with the exception of the adjusted() and as_tuple() methods) there is a corresponding Context method. For example, for a Context instance C and Decimal instance x, C.exp(x) is equivalent to x.exp(context=C). Each Context method accepts a Python integer (an instance of int) anywhere that a Decimal instance is accepted.

clear_flags()

Resets all of the flags to 0.

clear_traps()

Resets all of the traps to 0.

New in version 3.3.

copy()

Return a duplicate of the context.

copy_decimal(num)

Return a copy of the Decimal instance num.

create_decimal(num)

Creates a new Decimal instance from num but using self as context. Unlike the Decimal constructor, the context precision, rounding method, flags, and traps are applied to the conversion.

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

This method implements the to-number operation of the IBM specification. If the argument is a string, no leading or trailing whitespace is permitted.

create_decimal_from_float(f)

Creates a new Decimal instance from a float f but rounding using self as the context. Unlike the Decimal.from_float() class method, the context precision, rounding method, flags, and traps are applied to the conversion.

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

New in version 3.1.

Etiny()

Returns a value equal to Emin - prec + 1 which is the minimum exponent value for subnormal results. When underflow occurs, the exponent is set to Etiny.

Etop()

Returns a value equal to Emax - prec + 1.

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 alternative 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.

abs(x)

Returns the absolute value of x.

add(x, y)

Return the sum of x and y.

canonical(x)

Returns the same Decimal object x.

compare(x, y)

Compares x and y numerically.

compare_signal(x, y)

Compares the values of the two operands numerically.

compare_total(x, y)

Compares two operands using their abstract representation.

compare_total_mag(x, y)

Compares two operands using their abstract representation, ignoring sign.

copy_abs(x)

Returns a copy of x with the sign set to 0.

copy_negate(x)

Returns a copy of x with the sign inverted.

copy_sign(x, y)

Copies the sign from y to x.

divide(x, y)

Return x divided by y.

divide_int(x, y)

Return x divided by y, truncated to an integer.

divmod(x, y)

Divides two numbers and returns the integer part of the result.

exp(x)

Returns e ** x.

fma(x, y, z)

Returns x multiplied by y, plus z.

is_canonical(x)

Returns True if x is canonical; otherwise returns False.

is_finite(x)

Returns True if x is finite; otherwise returns False.

is_infinite(x)

Returns True if x is infinite; otherwise returns False.

is_nan(x)

Returns True if x is a qNaN or sNaN; otherwise returns False.

is_normal(x)

Returns True if x is a normal number; otherwise returns False.

is_qnan(x)

Returns True if x is a quiet NaN; otherwise returns False.

is_signed(x)

Returns True if x is negative; otherwise returns False.

is_snan(x)

Returns True if x is a signaling NaN; otherwise returns False.

is_subnormal(x)

Returns True if x is subnormal; otherwise returns False.

is_zero(x)

Returns True if x is a zero; otherwise returns False.

ln(x)

Returns the natural (base e) logarithm of x.

log10(x)

Returns the base 10 logarithm of x.

logb(x)

Returns the exponent of the magnitude of the operand’s MSD.

logical_and(x, y)

Applies the logical operation and between each operand’s digits.

logical_invert(x)

Invert all the digits in x.

logical_or(x, y)

Applies the logical operation or between each operand’s digits.

logical_xor(x, y)

Applies the logical operation xor between each operand’s digits.

max(x, y)

Compares two values numerically and returns the maximum.

max_mag(x, y)

Compares the values numerically with their sign ignored.

min(x, y)

Compares two values numerically and returns the minimum.

min_mag(x, y)

Compares the values numerically with their sign ignored.

minus(x)

Minus corresponds to the unary prefix minus operator in Python.

multiply(x, y)

Return the product of x and y.

next_minus(x)

Returns the largest representable number smaller than x.

next_plus(x)

Returns the smallest representable number larger than x.

next_toward(x, y)

Returns the number closest to x, in direction towards y.

normalize(x)

Reduces x to its simplest form.

number_class(x)

Returns an indication of the class of x.

plus(x)

Plus corresponds to the unary prefix plus operator in Python. This operation applies the context precision and rounding, so it is not an identity operation.

power(x, y, modulo=None)

Return x to the power of y, reduced modulo modulo if given.

With two arguments, compute x**y. If x is negative then y must be integral. The result will be inexact unless y is integral and the result is finite and can be expressed exactly in ‘precision’ digits. The rounding mode of the context is used. Results are always correctly-rounded in the Python version.

Changed in version 3.3: The C module computes power() in terms of the correctly-rounded exp() and ln() functions. The result is well-defined but only “almost always correctly-rounded”.

With three arguments, compute (x**y) % modulo. For the three argument form, the following restrictions on the arguments hold:

• all three arguments must be integral
• y must be nonnegative
• at least one of x or y must be nonzero
• modulo must be nonzero and have at most ‘precision’ digits

The value resulting from Context.power(x, y, modulo) is equal to the value that would be obtained by computing (x**y) % modulo with unbounded precision, but is computed more efficiently. The exponent of the result is zero, regardless of the exponents of x, y and modulo. The result is always exact.

quantize(x, y)

Returns a value equal to x (rounded), having the exponent of y.

radix()

Just returns 10, as this is Decimal, :)

remainder(x, y)

Returns the remainder from integer division.

The sign of the result, if non-zero, is the same as that of the original dividend.

remainder_near(x, y)

Returns x - y * n, where n is the integer nearest the exact value of x / y (if the result is 0 then its sign will be the sign of x).

rotate(x, y)

Returns a rotated copy of x, y times.

same_quantum(x, y)

Returns True if the two operands have the same exponent.

scaleb(x, y)

Returns the first operand after adding the second value its exp.

shift(x, y)

Returns a shifted copy of x, y times.

sqrt(x)

Square root of a non-negative number to context precision.

subtract(x, y)

Return the difference between x and y.

to_eng_string(x)

Convert to a string, using engineering notation if an exponent is needed.

Engineering notation has an exponent which is a multiple of 3. This can leave up to 3 digits to the left of the decimal place and may require the addition of either one or two trailing zeros.

to_integral_exact(x)

Rounds to an integer.

to_sci_string(x)

Converts a number to a string using scientific notation.