Quick-start Tutorial¶

The usual start to using decimals is importing the module, viewing the currentcontext withgetcontext() and, if necessary, setting new values forprecision, rounding, or enabled traps:

>>>fromdecimalimport*>>>getcontext()Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,        capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,        InvalidOperation])>>>getcontext().prec=7# Set a new precision

Decimal instances can be constructed from integers, strings, floats, or tuples.Construction from an integer or a float performs an exact conversion of thevalue of that integer or float. Decimal numbers include special values such asNaN which stands for "Not a number", positive and negativeInfinity, and-0:

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

If theFloatOperation signal is trapped, accidental mixing ofdecimals and floats in constructors or ordering comparisons raisesan exception:

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

The significance of a new Decimal is determined solely by the number of digitsinput. Context precision and rounding only come into play during arithmeticoperations.

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

If the internal limits of the C version are exceeded, constructinga decimal raisesInvalidOperation:

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

Decimals interact well with much of the rest of Python. Here is a small decimalfloating-point flying circus:

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

And some mathematical functions are also available to Decimal:

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

Thequantize() method rounds a number to a fixed exponent. This method isuseful for monetary applications that often round results to a fixed number ofplaces:

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

As shown above, thegetcontext() function accesses the current context andallows the settings to be changed. This approach meets the needs of mostapplications.

For more advanced work, it may be useful to create alternate contexts using theContext() constructor. To make an alternate active, use thesetcontext()function.

In accordance with the standard, thedecimal module provides two ready touse standard contexts,BasicContext andExtendedContext. Theformer is especially useful for debugging because many of the traps areenabled:

>>>myothercontext=Context(prec=60,rounding=ROUND_HALF_DOWN)>>>setcontext(myothercontext)>>>Decimal(1)/Decimal(7)Decimal('0.142857142857142857142857142857142857142857142857142857142857')>>>ExtendedContextContext(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,        capitals=1, clamp=0, flags=[], traps=[])>>>setcontext(ExtendedContext)>>>Decimal(1)/Decimal(7)Decimal('0.142857143')>>>Decimal(42)/Decimal(0)Decimal('Infinity')>>>setcontext(BasicContext)>>>Decimal(42)/Decimal(0)Traceback (most recent call last):  File"<pyshell#143>", line1, in-toplevel-Decimal(42)/Decimal(0)DivisionByZero:x / 0

Contexts also have signal flags for monitoring exceptional conditionsencountered during computations. The flags remain set until explicitly cleared,so it is best to clear the flags before each set of monitored computations byusing theclear_flags() method.

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

Theflags entry shows that the rational approximation to pi wasrounded (digits beyond the context precision were thrown away) and that theresult is inexact (some of the discarded digits were non-zero).

Individual traps are set using the dictionary in thetrapsattribute of a context:

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

Most programs adjust the current context only once, at the beginning of theprogram. And, in many applications, data is converted toDecimal witha single cast inside a loop. With context set and decimals created, the bulk ofthe program manipulates the data no differently than with other Python numerictypes.

Decimal objects¶

classdecimal.Decimal(value='0',context=None)¶

Construct a newDecimal object based fromvalue.

value can be an integer, string, tuple,float, or anotherDecimalobject. If novalue is given, returnsDecimal('0'). Ifvalue is astring, it should conform to the decimal numeric string syntax after leadingand trailing whitespace characters, as well as underscores throughout, are removed:

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

Other Unicode decimal digits are also permitted wheredigitappears above. These include decimal digits from various otheralphabets (for example, Arabic-Indic and Devanāgarī digits) alongwith the fullwidth digits'\uff10' through'\uff19'.Case is not significant, so, for example,inf,Inf,INFINITY,andiNfINity are all acceptable spellings for positive infinity.

Ifvalue is atuple, it should have three components, a sign(0 for positive or1 for negative), atuple ofdigits, and an integer exponent. For example,Decimal((0,(1,4,1,4),-3))returnsDecimal('1.414').

Ifvalue is afloat, the binary floating-point value is losslesslyconverted to its exact decimal equivalent. This conversion can often require53 or more digits of precision. For example,Decimal(float('1.1'))converts toDecimal('1.100000000000000088817841970012523233890533447265625').

Thecontext precision does not affect how many digits are stored. That isdetermined exclusively by the number of digits invalue. For example,Decimal('3.00000') records all five zeros even if the context precision isonly three.

The purpose of thecontext argument is determining what to do ifvalue is amalformed string. If the context trapsInvalidOperation, an exceptionis raised; otherwise, the constructor returns a new Decimal with the value ofNaN.

Once constructed,Decimal objects are immutable.

在 3.2 版的變更:The argument to the constructor is now permitted to be afloatinstance.

在 3.3 版的變更:float arguments raise an exception if theFloatOperationtrap is set. By default the trap is off.

在 3.6 版的變更:Underscores are allowed for grouping, as with integral and floating-pointliterals in code.

Decimal floating-point objects share many properties with the other built-innumeric types such asfloat andint. All of the usual mathoperations and special methods apply. Likewise, decimal objects can becopied, pickled, printed, used as dictionary keys, used as set elements,compared, sorted, and coerced to another type (such asfloat orint).

There are some small differences between arithmetic on Decimal objects andarithmetic on integers and floats. When the remainder operator% isapplied to Decimal objects, the sign of the result is the sign of thedividend rather than the sign of the divisor:

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

The integer division operator// behaves analogously, returning theinteger part of the true quotient (truncating towards zero) rather than itsfloor, so as to preserve the usual identityx==(x//y)*y+x%y:

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

The% and// operators implement theremainder anddivide-integer operations (respectively) as described in thespecification.

Decimal objects cannot generally be combined with floats orinstances offractions.Fraction in arithmetic operations:an attempt to add aDecimal to afloat, forexample, will raise aTypeError. However, it is possible touse Python's comparison operators to compare aDecimalinstancex with another numbery. This avoids confusing resultswhen doing equality comparisons between numbers of different types.

在 3.2 版的變更:Mixed-type comparisons betweenDecimal instances and othernumeric types are now fully supported.

In addition to the standard numeric properties, decimal floating-pointobjects also have a number of specialized methods:

adjusted()¶

Return the adjusted exponent after shifting out the coefficient'srightmost digits until only the lead digit remains:Decimal('321e+5').adjusted() returns seven. Used for determining theposition of the most significant digit with respect to the decimal point.

as_integer_ratio()¶

Return a pair(n,d) of integers that represent the givenDecimal instance as a fraction, in lowest terms andwith a positive denominator:

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

The conversion is exact. Raise OverflowError on infinities and ValueErroron NaNs.

在 3.6 版被加入.

as_tuple()¶

Return anamed tuple representation of the number:DecimalTuple(sign,digits,exponent).

canonical()¶

Return the canonical encoding of the argument. Currently, the encoding ofaDecimal instance is always canonical, so this operation returnsits argument unchanged.

compare(other,context=None)¶

Compare the values of two Decimal instances.compare() returns aDecimal instance, and if either operand is a NaN then the result is aNaN:

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

compare_signal(other,context=None)¶

This operation is identical to thecompare() method, except that allNaNs signal. That is, if neither operand is a signaling NaN then anyquiet NaN operand is treated as though it were a signaling NaN.

compare_total(other,context=None)¶

Compare two operands using their abstract representation rather than theirnumerical value. Similar to thecompare() method, but the resultgives a total ordering onDecimal instances. TwoDecimal instances with the same numeric value but differentrepresentations compare unequal in this ordering:

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

Quiet and signaling NaNs are also included in the total ordering. Theresult of this function isDecimal('0') if both operands have the samerepresentation,Decimal('-1') if the first operand is lower in thetotal order than the second, andDecimal('1') if the first operand ishigher in the total order than the second operand. See the specificationfor details of the total order.

This operation is unaffected by context and is quiet: no flags are changedand no rounding is performed. As an exception, the C version may raiseInvalidOperation if the second operand cannot be converted exactly.

compare_total_mag(other,context=None)¶

Compare two operands using their abstract representation rather than theirvalue as incompare_total(), but ignoring the sign of each operand.x.compare_total_mag(y) is equivalent tox.copy_abs().compare_total(y.copy_abs()).

This operation is unaffected by context and is quiet: no flags are changedand no rounding is performed. As an exception, the C version may raiseInvalidOperation if the second operand cannot be converted exactly.

conjugate()¶

Just returns self, this method is only to comply with the DecimalSpecification.

copy_abs()¶

Return the absolute value of the argument. This operation is unaffectedby the context and is quiet: no flags are changed and no rounding isperformed.

copy_negate()¶

Return the negation of the argument. This operation is unaffected by thecontext and is quiet: no flags are changed and no rounding is performed.

copy_sign(other,context=None)¶

Return a copy of the first operand with the sign set to be the same as thesign of the second operand. For example:

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

This operation is unaffected by context and is quiet: no flags are changedand no rounding is performed. As an exception, the C version may raiseInvalidOperation if the second operand cannot be converted exactly.

exp(context=None)¶

Return the value of the (natural) exponential functione**x at thegiven number. The result is correctly rounded using theROUND_HALF_EVEN rounding mode.

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

classmethodfrom_float(f)¶

Alternative constructor that only accepts instances offloat orint.

NoteDecimal.from_float(0.1) is not the same asDecimal('0.1').Since 0.1 is not exactly representable in binary floating point, thevalue is stored as the nearest representable value which is0x1.999999999999ap-4. That equivalent value in decimal is0.1000000000000000055511151231257827021181583404541015625.

備註

From Python 3.2 onwards, aDecimal instancecan also be constructed directly from afloat.

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

在 3.1 版被加入.

fma(other,third,context=None)¶

Fused multiply-add. Return self*other+third with no rounding of theintermediate product self*other.

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

is_canonical()¶

ReturnTrue if the argument is canonical andFalseotherwise. Currently, aDecimal instance is always canonical, sothis operation always returnsTrue.

is_finite()¶

ReturnTrue if the argument is a finite number, andFalse if the argument is an infinity or a NaN.

is_infinite()¶

ReturnTrue if the argument is either positive or negativeinfinity andFalse otherwise.

is_nan()¶

ReturnTrue if the argument is a (quiet or signaling) NaN andFalse otherwise.

is_normal(context=None)¶

ReturnTrue if the argument is anormal finite number. ReturnFalse if the argument is zero, subnormal, infinite or a NaN.

is_qnan()¶

ReturnTrue if the argument is a quiet NaN, andFalse otherwise.

is_signed()¶

ReturnTrue if the argument has a negative sign andFalse otherwise. Note that zeros and NaNs can both carry signs.

is_snan()¶

ReturnTrue if the argument is a signaling NaN andFalseotherwise.

is_subnormal(context=None)¶

ReturnTrue if the argument is subnormal, andFalseotherwise.

is_zero()¶

ReturnTrue if the argument is a (positive or negative) zero andFalse otherwise.

ln(context=None)¶

Return the natural (base e) logarithm of the operand. The result iscorrectly rounded using theROUND_HALF_EVEN rounding mode.

log10(context=None)¶

Return the base ten logarithm of the operand. The result is correctlyrounded using theROUND_HALF_EVEN rounding mode.

logb(context=None)¶

For a nonzero number, return the adjusted exponent of its operand as aDecimal instance. If the operand is a zero thenDecimal('-Infinity') is returned and theDivisionByZero flagis raised. If the operand is an infinity thenDecimal('Infinity') isreturned.

logical_and(other,context=None)¶

logical_and() is a logical operation which takes twologicaloperands (seeLogical operands). The result is thedigit-wiseand of the two operands.

logical_invert(context=None)¶

logical_invert() is a logical operation. Theresult is the digit-wise inversion of the operand.

logical_or(other,context=None)¶

logical_or() is a logical operation which takes twologicaloperands (seeLogical operands). The result is thedigit-wiseor of the two operands.

logical_xor(other,context=None)¶

logical_xor() is a logical operation which takes twologicaloperands (seeLogical operands). The result is thedigit-wise exclusive or of the two operands.

max(other,context=None)¶

Likemax(self,other) except that the context rounding rule is appliedbefore returning and thatNaN values are either signaled orignored (depending on the context and whether they are signaling orquiet).

max_mag(other,context=None)¶

Similar to themax() method, but the comparison is done using theabsolute values of the operands.

min(other,context=None)¶

Likemin(self,other) except that the context rounding rule is appliedbefore returning and thatNaN values are either signaled orignored (depending on the context and whether they are signaling orquiet).

min_mag(other,context=None)¶

Similar to themin() method, but the comparison is done using theabsolute values of the operands.

next_minus(context=None)¶

Return the largest number representable in the given context (or in thecurrent thread's context if no context is given) that is smaller than thegiven operand.

next_plus(context=None)¶

Return the smallest number representable in the given context (or in thecurrent thread's context if no context is given) that is larger than thegiven operand.

next_toward(other,context=None)¶

If the two operands are unequal, return the number closest to the firstoperand in the direction of the second operand. If both operands arenumerically equal, return a copy of the first operand with the sign set tobe the same as the sign of the second operand.

normalize(context=None)¶

Used for producing canonical values of an equivalenceclass within either the current context or the specified context.

This has the same semantics as the unary plus operation, except that ifthe final result is finite it is reduced to its simplest form, with alltrailing zeros removed and its sign preserved. That is, while thecoefficient is non-zero and a multiple of ten the coefficient is dividedby ten and the exponent is incremented by 1. Otherwise (the coefficient iszero) the exponent is set to 0. In all cases the sign is unchanged.

For example,Decimal('32.100') andDecimal('0.321000e+2') bothnormalize to the equivalent valueDecimal('32.1').

Note that rounding is appliedbefore reducing to simplest form.

In the latest versions of the specification, this operation is also knownasreduce.

number_class(context=None)¶

Return a string describing theclass of the operand. The returned valueis one of the following ten strings.

• "-Infinity", indicating that the operand is negative infinity.

• "-Normal", indicating that the operand is a negative normal number.

• "-Subnormal", indicating that the operand is negative and subnormal.

• "-Zero", indicating that the operand is a negative zero.

• "+Zero", indicating that the operand is a positive zero.

• "+Subnormal", indicating that the operand is positive and subnormal.

• "+Normal", indicating that the operand is a positive normal number.

• "+Infinity", indicating that the operand is positive infinity.

• "NaN", indicating that the operand is a quiet NaN (Not a Number).

• "sNaN", indicating that the operand is a signaling NaN.

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

Return a value equal to the first operand after rounding and having theexponent of the second operand.

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

Unlike other operations, if the length of the coefficient after thequantize operation would be greater than precision, then anInvalidOperation is signaled. This guarantees that, unless thereis an error condition, the quantized exponent is always equal to that ofthe right-hand operand.

Also unlike other operations, quantize never signals Underflow, even ifthe result is subnormal and inexact.

If the exponent of the second operand is larger than that of the firstthen rounding may be necessary. In this case, the rounding mode isdetermined by therounding argument if given, else by the givencontext argument; if neither argument is given the rounding mode ofthe current thread's context is used.

An error is returned whenever the resulting exponent is greater thanEmax or less thanEtiny().

radix()¶

ReturnDecimal(10), the radix (base) in which theDecimalclass does all its arithmetic. Included for compatibility with thespecification.

remainder_near(other,context=None)¶

Return the remainder from dividingself byother. This differs fromself%other in that the sign of the remainder is chosen so as tominimize its absolute value. More precisely, the return value isself-n*other wheren is the integer nearest to the exactvalue ofself/other, and if two integers are equally near then theeven one is chosen.

If the result is zero then its sign will be the sign ofself.

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

rotate(other,context=None)¶

Return the result of rotating the digits of the first operand by an amountspecified by the second operand. The second operand must be an integer inthe range -precision through precision. The absolute value of the secondoperand gives the number of places to rotate. If the second operand ispositive then rotation is to the left; otherwise rotation is to the right.The coefficient of the first operand is padded on the left with zeros tolength precision if necessary. The sign and exponent of the first operandare unchanged.

same_quantum(other,context=None)¶

Test whether self and other have the same exponent or whether both areNaN.

This operation is unaffected by context and is quiet: no flags are changedand no rounding is performed. As an exception, the C version may raiseInvalidOperation if the second operand cannot be converted exactly.

scaleb(other,context=None)¶

Return the first operand with exponent adjusted by the second.Equivalently, return the first operand multiplied by10**other. Thesecond operand must be an integer.

shift(other,context=None)¶

Return the result of shifting the digits of the first operand by an amountspecified by the second operand. The second operand must be an integer inthe range -precision through precision. The absolute value of the secondoperand gives the number of places to shift. If the second operand ispositive then the shift is to the left; otherwise the shift is to theright. Digits shifted into the coefficient are zeros. The sign andexponent of the first operand are unchanged.

sqrt(context=None)¶

Return the square root of the argument to full precision.

to_eng_string(context=None)¶

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

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

For example, this convertsDecimal('123E+1') toDecimal('1.23E+3').

to_integral(rounding=None,context=None)¶

Identical to theto_integral_value() method. Theto_integralname has been kept for compatibility with older versions.

to_integral_exact(rounding=None,context=None)¶

Round to the nearest integer, signalingInexact orRounded as appropriate if rounding occurs. The rounding mode isdetermined by therounding parameter if given, else by the givencontext. If neither parameter is given then the rounding mode of thecurrent context is used.

to_integral_value(rounding=None,context=None)¶

Round to the nearest integer without signalingInexact orRounded. If given, appliesrounding; otherwise, uses therounding method in either the suppliedcontext or the current context.

Decimal numbers can be rounded using theround() function:

round(number)

round(number,ndigits)

Ifndigits is not given orNone,returns the nearestint tonumber,rounding ties to even, and ignoring the rounding mode of theDecimal context. RaisesOverflowError ifnumber is aninfinity orValueError if it is a (quiet or signaling) NaN.

Ifndigits is anint, the context's rounding mode is respectedand aDecimal representingnumber rounded to the nearestmultiple ofDecimal('1E-ndigits') is returned; in this case,round(number,ndigits) is equivalent toself.quantize(Decimal('1E-ndigits')). ReturnsDecimal('NaN') ifnumber is a quiet NaN. RaisesInvalidOperation ifnumberis an infinity, a signaling NaN, or if the length of the coefficient afterthe quantize operation would be greater than the current context'sprecision. In other words, for the non-corner cases:

• ifndigits is positive, returnnumber rounded tondigits decimalplaces;

• ifndigits is zero, returnnumber rounded to the nearest integer;

• ifndigits is negative, returnnumber rounded to the nearestmultiple of10**abs(ndigits).

For example:

>>>fromdecimalimportDecimal,getcontext,ROUND_DOWN>>>getcontext().rounding=ROUND_DOWN>>>round(Decimal('3.75'))# context rounding ignored4>>>round(Decimal('3.5'))# round-ties-to-even4>>>round(Decimal('3.75'),0)# uses the context roundingDecimal('3')>>>round(Decimal('3.75'),1)Decimal('3.7')>>>round(Decimal('3.75'),-1)Decimal('0E+1')

Context objects¶

Contexts are environments for arithmetic operations. They govern precision, setrules for rounding, determine which signals are treated as exceptions, and limitthe range for exponents.

Each thread has its own current context which is accessed or changed using thegetcontext() andsetcontext() functions:

decimal.getcontext()¶

Return the current context for the active thread.

decimal.setcontext(c)¶

Set the current context for the active thread toc.

You can also use thewith statement and thelocalcontext()function to temporarily change the active context.

decimal.localcontext(ctx=None,**kwargs)¶

Return a context manager that will set the current context for the active threadto a copy ofctx on entry to the with-statement and restore the previous contextwhen exiting the with-statement. If no context is specified, a copy of thecurrent context is used. Thekwargs argument is used to set the attributesof the new context.

For example, the following code sets the current decimal precision to 42 places,performs a calculation, and then automatically restores the previous context:

fromdecimalimportlocalcontextwithlocalcontext()asctx:ctx.prec=42# Perform a high precision calculations=calculate_something()s=+s# Round the final result back to the default precision

Using keyword arguments, the code would be the following:

fromdecimalimportlocalcontextwithlocalcontext(prec=42)asctx:s=calculate_something()s=+s

RaisesTypeError ifkwargs supplies an attribute thatContext doesn'tsupport. Raises eitherTypeError orValueError ifkwargs supplies aninvalid value for an attribute.

在 3.11 版的變更:localcontext() now supports setting context attributes through the use of keyword arguments.

New contexts can also be created using theContext constructordescribed below. In addition, the module provides three pre-made contexts:

decimal.BasicContext¶

This is a standard context defined by the General Decimal ArithmeticSpecification. Precision is set to nine. Rounding is set toROUND_HALF_UP. All flags are cleared. All traps are enabled (treatedas exceptions) exceptInexact,Rounded, andSubnormal.

Because many of the traps are enabled, this context is useful for debugging.

decimal.ExtendedContext¶

This is a standard context defined by the General Decimal ArithmeticSpecification. Precision is set to nine. Rounding is set toROUND_HALF_EVEN. All flags are cleared. No traps are enabled (so thatexceptions are not raised during computations).

Because the traps are disabled, this context is useful for applications thatprefer to have result value ofNaN orInfinity instead ofraising exceptions. This allows an application to complete a run in thepresence of conditions that would otherwise halt the program.

decimal.DefaultContext¶

This context is used by theContext constructor as a prototype for newcontexts. Changing a field (such a precision) has the effect of changing thedefault for new contexts created by theContext constructor.

This context is most useful in multi-threaded environments. Changing one of thefields before threads are started has the effect of setting system-widedefaults. Changing the fields after threads have started is not recommended asit would require thread synchronization to prevent race conditions.

In single threaded environments, it is preferable to not use this context atall. Instead, simply create contexts explicitly as described below.

The default values areContext.prec=28,Context.rounding=ROUND_HALF_EVEN,and enabled traps forOverflow,InvalidOperation, andDivisionByZero.

In addition to the three supplied contexts, new contexts can be created with theContext constructor.

classdecimal.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 isNone, thedefault values are copied from theDefaultContext. If theflagsfield is not specified or isNone, all flags are cleared.

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

Therounding option is one of the constants listed in the sectionRounding Modes.

Thetraps andflags fields list any signals to be set. Generally, newcontexts should only set traps and leave the flags clear.

TheEmin andEmax fields are integers specifying the outer limits allowablefor exponents.Emin must be in the range [MIN_EMIN,0],Emax in the range [0,MAX_EMAX].

Thecapitals field is either0 or1 (the default). If set to1, exponents are printed with a capitalE; otherwise, alowercasee is used:Decimal('6.02e+23').

Theclamp field is either0 (the default) or1.If set to1, the exponente of aDecimalinstance representable in this context is strictly limited to therangeEmin-prec+1<=e<=Emax-prec+1. Ifclamp is0 then a weaker condition holds: the adjusted exponent oftheDecimal instance is at mostEmax. Whenclamp is1, a large normal number will, where possible, have itsexponent reduced and a corresponding number of zeros added to itscoefficient, in order to fit the exponent constraints; thispreserves the value of the number but loses information aboutsignificant trailing zeros. For example:

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

Aclamp value of1 allows compatibility with thefixed-width decimal interchange formats specified in IEEE 754.

TheContext class defines several general purpose methods as well asa large number of methods for doing arithmetic directly in a given context.In addition, for each of theDecimal methods described above (withthe exception of theadjusted() andas_tuple() methods) there isa correspondingContext method. For example, for aContextinstanceC andDecimal instancex,C.exp(x) isequivalent tox.exp(context=C). EachContext method accepts aPython integer (an instance ofint) anywhere that aDecimal instance is accepted.

clear_flags()¶

Resets all of the flags to0.

clear_traps()¶

Resets all of the traps to0.

在 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 fromnum but usingself ascontext. Unlike theDecimal 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 precisionthan is needed by the application. Another benefit is that roundingimmediately eliminates unintended effects from digits beyond the currentprecision. In the following example, using unrounded inputs means thatadding 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 orunderscores are permitted.

create_decimal_from_float(f)¶

Creates a new Decimal instance from a floatf but rounding usingselfas the context. Unlike theDecimal.from_float() class method,the context precision, rounding method, flags, and traps are applied tothe 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

在 3.1 版被加入.

Etiny()¶

Returns a value equal toEmin-prec+1 which is the minimum exponentvalue for subnormal results. When underflow occurs, the exponent is settoEtiny.

Etop()¶

Returns a value equal toEmax-prec+1.

The usual approach to working with decimals is to createDecimalinstances and then apply arithmetic operations which take place within thecurrent context for the active thread. An alternative approach is to usecontext methods for calculating within a specific context. The methods aresimilar to those for theDecimal class and are only brieflyrecounted here.

abs(x)¶

Returns the absolute value ofx.

add(x,y)¶

Return the sum ofx andy.

canonical(x)¶

Returns the same Decimal objectx.

compare(x,y)¶

Comparesx andy 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 ofx with the sign set to 0.

copy_negate(x)¶

Returns a copy ofx with the sign inverted.

copy_sign(x,y)¶

Copies the sign fromy tox.

divide(x,y)¶

Returnx divided byy.

divide_int(x,y)¶

Returnx divided byy, truncated to an integer.

divmod(x,y)¶

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

exp(x)¶

Returnse**x.

fma(x,y,z)¶

Returnsx multiplied byy, plusz.

is_canonical(x)¶

ReturnsTrue ifx is canonical; otherwise returnsFalse.

is_finite(x)¶

ReturnsTrue ifx is finite; otherwise returnsFalse.

is_infinite(x)¶

ReturnsTrue ifx is infinite; otherwise returnsFalse.

is_nan(x)¶

ReturnsTrue ifx is a qNaN or sNaN; otherwise returnsFalse.

is_normal(x)¶

ReturnsTrue ifx is a normal number; otherwise returnsFalse.

is_qnan(x)¶

ReturnsTrue ifx is a quiet NaN; otherwise returnsFalse.

is_signed(x)¶

ReturnsTrue ifx is negative; otherwise returnsFalse.

is_snan(x)¶

ReturnsTrue ifx is a signaling NaN; otherwise returnsFalse.

is_subnormal(x)¶

ReturnsTrue ifx is subnormal; otherwise returnsFalse.

is_zero(x)¶

ReturnsTrue ifx is a zero; otherwise returnsFalse.

ln(x)¶

Returns the natural (base e) logarithm ofx.

log10(x)¶

Returns the base 10 logarithm ofx.

logb(x)¶

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

logical_and(x,y)¶

Applies the logical operationand between each operand's digits.

logical_invert(x)¶

Invert all the digits inx.

logical_or(x,y)¶

Applies the logical operationor between each operand's digits.

logical_xor(x,y)¶

Applies the logical operationxor 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 ofx andy.

next_minus(x)¶

Returns the largest representable number smaller thanx.

next_plus(x)¶

Returns the smallest representable number larger thanx.

next_toward(x,y)¶

Returns the number closest tox, in direction towardsy.

normalize(x)¶

Reducesx to its simplest form.

number_class(x)¶

Returns an indication of the class ofx.

plus(x)¶

Plus corresponds to the unary prefix plus operator in Python. Thisoperation applies the context precision and rounding, so it isnot anidentity operation.

power(x,y,modulo=None)¶

Returnx to the power ofy, reduced modulomodulo if given.

With two arguments, computex**y. Ifx is negative thenymust be integral. The result will be inexact unlessy is integral andthe result is finite and can be expressed exactly in 'precision' digits.The rounding mode of the context is used. Results are always correctly roundedin the Python version.

Decimal(0)**Decimal(0) results inInvalidOperation, and ifInvalidOperationis not trapped, then results inDecimal('NaN').

在 3.3 版的變更:The C module computespower() in terms of the correctly roundedexp() andln() functions. The result is well-defined butonly "almost always correctly rounded".

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

• all three arguments must be integral

• y must be nonnegative

• at least one ofx ory must be nonzero

• modulo must be nonzero and have at most 'precision' digits

The value resulting fromContext.power(x,y,modulo) isequal to the value that would be obtained by computing(x**y)%modulo with unbounded precision, but is computed moreefficiently. The exponent of the result is zero, regardless ofthe exponents ofx,y andmodulo. The result isalways exact.

quantize(x,y)¶

Returns a value equal tox (rounded), having the exponent ofy.

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

remainder_near(x,y)¶

Returnsx-y*n, wheren is the integer nearest the exact valueofx/y (if the result is 0 then its sign will be the sign ofx).

rotate(x,y)¶

Returns a rotated copy ofx,y times.

same_quantum(x,y)¶

ReturnsTrue 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 ofx,y times.

sqrt(x)¶

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

subtract(x,y)¶

Return the difference betweenx andy.

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. Thiscan leave up to 3 digits to the left of the decimal place and mayrequire 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.

常數¶

The constants in this section are only relevant for the C module. Theyare also included in the pure Python version for compatibility.

decimal.HAVE_THREADS¶

The value isTrue. Deprecated, because Python now always has threads.

在 3.9 版之後被棄用.

decimal.HAVE_CONTEXTVAR¶

The default value isTrue. If Python isconfiguredusingthe--without-decimal-contextvaroption,the C version uses a thread-local rather than a coroutine-local context and the valueisFalse. This is slightly faster in some nested context scenarios.

在 3.8.3 版被加入.

Rounding modes¶

decimal.ROUND_CEILING¶

Round towardsInfinity.

decimal.ROUND_DOWN¶

Round towards zero.

decimal.ROUND_FLOOR¶

Round towards-Infinity.

decimal.ROUND_HALF_DOWN¶

Round to nearest with ties going towards zero.

decimal.ROUND_HALF_EVEN¶

Round to nearest with ties going to nearest even integer.

decimal.ROUND_HALF_UP¶

Round to nearest with ties going away from zero.

decimal.ROUND_UP¶

Round away from zero.

decimal.ROUND_05UP¶

Round away from zero if last digit after rounding towards zero would havebeen 0 or 5; otherwise round towards zero.

Signals¶

Signals represent conditions that arise during computation. Each corresponds toone context flag and one context trap enabler.

The context flag is set whenever the condition is encountered. After thecomputation, flags may be checked for informational purposes (for instance, todetermine whether a computation was exact). After checking the flags, be sure toclear all flags before starting the next computation.

If the context's trap enabler is set for the signal, then the condition causes aPython exception to be raised. For example, if theDivisionByZero trapis set, then aDivisionByZero exception is raised upon encountering thecondition.

classdecimal.Clamped¶

Altered an exponent to fit representation constraints.

Typically, clamping occurs when an exponent falls outside the context'sEmin andEmax limits. If possible, the exponent is reduced tofit by adding zeros to the coefficient.

classdecimal.DecimalException¶

Base class for other signals and a subclass ofArithmeticError.

classdecimal.DivisionByZero¶

Signals the division of a non-infinite number by zero.

Can occur with division, modulo division, or when raising a number to a negativepower. If this signal is not trapped, returnsInfinity or-Infinity with the sign determined by the inputs to the calculation.

classdecimal.Inexact¶

Indicates that rounding occurred and the result is not exact.

Signals when non-zero digits were discarded during rounding. The rounded resultis returned. The signal flag or trap is used to detect when results areinexact.

classdecimal.InvalidOperation¶

An invalid operation was performed.

Indicates that an operation was requested that does not make sense. If nottrapped, returnsNaN. Possible causes include:

Infinity-Infinity0*InfinityInfinity/Infinityx%0Infinity%xsqrt(-x)andx>00**0x**(non-integer)x**Infinity

classdecimal.Overflow¶

Numerical overflow.

Indicates the exponent is larger thanContext.Emax after rounding hasoccurred. If not trapped, the result depends on the rounding mode, eitherpulling inward to the largest representable finite number or rounding outwardtoInfinity. In either case,Inexact andRoundedare also signaled.

classdecimal.Rounded¶

Rounding occurred though possibly no information was lost.

Signaled whenever rounding discards digits; even if those digits are zero(such as rounding5.00 to5.0). If not trapped, returnsthe result unchanged. This signal is used to detect loss of significantdigits.

classdecimal.Subnormal¶

Exponent was lower thanEmin prior to rounding.

Occurs when an operation result is subnormal (the exponent is too small). Ifnot trapped, returns the result unchanged.

classdecimal.Underflow¶

Numerical underflow with result rounded to zero.

Occurs when a subnormal result is pushed to zero by rounding.InexactandSubnormal are also signaled.

classdecimal.FloatOperation¶

Enable stricter semantics for mixing floats and Decimals.

If the signal is not trapped (default), mixing floats and Decimals ispermitted in theDecimal constructor,create_decimal() and all comparison operators.Both conversion and comparisons are exact. Any occurrence of a mixedoperation is silently recorded by settingFloatOperation in thecontext flags. Explicit conversions withfrom_float()orcreate_decimal_from_float() do not set the flag.

Otherwise (the signal is trapped), only equality comparisons and explicitconversions are silent. All other mixed operations raiseFloatOperation.

The following table summarizes the hierarchy of signals:

exceptions.ArithmeticError(exceptions.Exception)DecimalExceptionClampedDivisionByZero(DecimalException,exceptions.ZeroDivisionError)InexactOverflow(Inexact,Rounded)Underflow(Inexact,Rounded,Subnormal)InvalidOperationRoundedSubnormalFloatOperation(DecimalException,exceptions.TypeError)

Floating-Point Notes¶

# Examples from Seminumerical Algorithms, Section 4.2.2.>>>fromdecimalimportDecimal,getcontext>>>getcontext().prec=8>>>u,v,w=Decimal(11111113),Decimal(-11111111),Decimal('7.51111111')>>>(u+v)+wDecimal('9.5111111')>>>u+(v+w)Decimal('10')>>>u,v,w=Decimal(20000),Decimal(-6),Decimal('6.0000003')>>>(u*v)+(u*w)Decimal('0.01')>>>u*(v+w)Decimal('0.0060000')

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

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

Working with threads¶

Thegetcontext() function accesses a differentContext object foreach thread. Having separate thread contexts means that threads may makechanges (such asgetcontext().prec=10) without interfering with other threads.

Likewise, thesetcontext() function automatically assigns its target tothe current thread.

Ifsetcontext() has not been called beforegetcontext(), thengetcontext() will automatically create a new context for use in thecurrent thread.

The new context is copied from a prototype context calledDefaultContext. Tocontrol the defaults so that each thread will use the same values throughout theapplication, directly modify theDefaultContext object. This should be donebefore any threads are started so that there won't be a race condition betweenthreads callinggetcontext(). For example:

# Set applicationwide defaults for all threads about to be launchedDefaultContext.prec=12DefaultContext.rounding=ROUND_DOWNDefaultContext.traps=ExtendedContext.traps.copy()DefaultContext.traps[InvalidOperation]=1setcontext(DefaultContext)# Afterwards, the threads can be startedt1.start()t2.start()t3.start()...

Recipes¶

Here are a few recipes that serve as utility functions and that demonstrate waysto work with theDecimal class:

defmoneyfmt(value,places=2,curr='',sep=',',dp='.',pos='',neg='-',trailneg=''):"""Convert Decimal to a money formatted string.    places:  required number of places after the decimal point    curr:    optional currency symbol before the sign (may be blank)    sep:     optional grouping separator (comma, period, space, or blank)    dp:      decimal point indicator (comma or period)             only specify as blank when places is zero    pos:     optional sign for positive numbers: '+', space or blank    neg:     optional sign for negative numbers: '-', '(', space or blank    trailneg:optional trailing minus indicator:  '-', ')', space or blank    >>> d = Decimal('-1234567.8901')    >>> moneyfmt(d, curr='$')    '-$1,234,567.89'    >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')    '1.234.568-'    >>> moneyfmt(d, curr='$', neg='(', trailneg=')')    '($1,234,567.89)'    >>> moneyfmt(Decimal(123456789), sep=' ')    '123 456 789.00'    >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')    '<0.02>'    """q=Decimal(10)**-places# 2 places --> '0.01'sign,digits,exp=value.quantize(q).as_tuple()result=[]digits=list(map(str,digits))build,next=result.append,digits.popifsign:build(trailneg)foriinrange(places):build(next()ifdigitselse'0')ifplaces:build(dp)ifnotdigits:build('0')i=0whiledigits:build(next())i+=1ifi==3anddigits:i=0build(sep)build(curr)build(negifsignelsepos)return''.join(reversed(result))defpi():"""Compute Pi to the current precision.    >>> print(pi())    3.141592653589793238462643383    """getcontext().prec+=2# extra digits for intermediate stepsthree=Decimal(3)# substitute "three=3.0" for regular floatslasts,t,s,n,na,d,da=0,three,3,1,0,0,24whiles!=lasts:lasts=sn,na=n+na,na+8d,da=d+da,da+32t=(t*n)/ds+=tgetcontext().prec-=2return+s# unary plus applies the new precisiondefexp(x):"""Return e raised to the power of x.  Result type matches input type.    >>> print(exp(Decimal(1)))    2.718281828459045235360287471    >>> print(exp(Decimal(2)))    7.389056098930650227230427461    >>> print(exp(2.0))    7.38905609893    >>> print(exp(2+0j))    (7.38905609893+0j)    """getcontext().prec+=2i,lasts,s,fact,num=0,0,1,1,1whiles!=lasts:lasts=si+=1fact*=inum*=xs+=num/factgetcontext().prec-=2return+sdefcos(x):"""Return the cosine of x as measured in radians.    The Taylor series approximation works best for a small value of x.    For larger values, first compute x = x % (2 * pi).    >>> print(cos(Decimal('0.5')))    0.8775825618903727161162815826    >>> print(cos(0.5))    0.87758256189    >>> print(cos(0.5+0j))    (0.87758256189+0j)    """getcontext().prec+=2i,lasts,s,fact,num,sign=0,0,1,1,1,1whiles!=lasts:lasts=si+=2fact*=i*(i-1)num*=x*xsign*=-1s+=num/fact*signgetcontext().prec-=2return+sdefsin(x):"""Return the sine of x as measured in radians.    The Taylor series approximation works best for a small value of x.    For larger values, first compute x = x % (2 * pi).    >>> print(sin(Decimal('0.5')))    0.4794255386042030002732879352    >>> print(sin(0.5))    0.479425538604    >>> print(sin(0.5+0j))    (0.479425538604+0j)    """getcontext().prec+=2i,lasts,s,fact,num,sign=1,0,x,1,x,1whiles!=lasts:lasts=si+=2fact*=i*(i-1)num*=x*xsign*=-1s+=num/fact*signgetcontext().prec-=2return+s

Decimal FAQ¶

Q. It is cumbersome to typedecimal.Decimal('1234.5'). Is there a way tominimize typing when using the interactive interpreter?

A. Some users abbreviate the constructor to just a single letter:

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

Q. In a fixed-point application with two decimal places, some inputs have manyplaces and need to be rounded. Others are not supposed to have excess digitsand need to be validated. What methods should be used?

A. Thequantize() method rounds to a fixed number of decimal places. IftheInexact trap is set, it is also useful for validation:

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

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

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

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

Q. Once I have valid two place inputs, how do I maintain that invariantthroughout an application?

A. Some operations like addition, subtraction, and multiplication by an integerwill automatically preserve fixed point. Others operations, like division andnon-integer multiplication, will change the number of decimal places and need tobe followed-up with aquantize() step:

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

In developing fixed-point applications, it is convenient to define functionsto handle thequantize() step:

>>>defmul(x,y,fp=TWOPLACES):...return(x*y).quantize(fp)...>>>defdiv(x,y,fp=TWOPLACES):...return(x/y).quantize(fp)

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

Q. There are many ways to express the same value. The numbers200,200.000,2E2, and.02E+4 all have the same value atvarious precisions. Is there a way to transform them to a single recognizablecanonical value?

A. Thenormalize() method maps all equivalent values to a singlerepresentative:

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

Q. When does rounding occur in a computation?

A. It occursafter the computation. The philosophy of the decimalspecification is that numbers are considered exact and are createdindependent of the current context. They can even have greaterprecision than current context. Computations process with thoseexact inputs and then rounding (or other context operations) isapplied to theresult of the computation:

>>>getcontext().prec=5>>>pi=Decimal('3.1415926535')# More than 5 digits>>>pi# All digits are retainedDecimal('3.1415926535')>>>pi+0# Rounded after an additionDecimal('3.1416')>>>pi-Decimal('0.00005')# Subtract unrounded numbers, then roundDecimal('3.1415')>>>pi+0-Decimal('0.00005').# Intermediate values are roundedDecimal('3.1416')

Q. Some decimal values always print with exponential notation. Is there a wayto get a non-exponential representation?

A. For some values, exponential notation is the only way to express the numberof significant places in the coefficient. For example, expressing5.0E+3 as5000 keeps the value constant but cannot show theoriginal's two-place significance.

If an application does not care about tracking significance, it is easy toremove the exponent and trailing zeroes, losing significance, but keeping thevalue unchanged:

>>>defremove_exponent(d):...returnd.quantize(Decimal(1))ifd==d.to_integral()elsed.normalize()

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

Q. Is there a way to convert a regular float to aDecimal?

A. Yes, any binary floating-point number can be exactly expressed as aDecimal though an exact conversion may take more precision than intuition wouldsuggest:

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

Q. Within a complex calculation, how can I make sure that I haven't gotten aspurious result because of insufficient precision or rounding anomalies.

A. The decimal module makes it easy to test results. A best practice is tore-run calculations using greater precision and with various rounding modes.Widely differing results indicate insufficient precision, rounding mode issues,ill-conditioned inputs, or a numerically unstable algorithm.

Q. I noticed that context precision is applied to the results of operations butnot to the inputs. Is there anything to watch out for when mixing values ofdifferent precisions?

A. Yes. The principle is that all values are considered to be exact and so isthe arithmetic on those values. Only the results are rounded. The advantagefor inputs is that "what you type is what you get". A disadvantage is that theresults can look odd if you forget that the inputs haven't been rounded:

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

The solution is either to increase precision or to force rounding of inputsusing the unary plus operation:

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

Alternatively, inputs can be rounded upon creation using theContext.create_decimal() method:

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

Q. Is the CPython implementation fast for large numbers?

A. Yes. In the CPython and PyPy3 implementations, the C/CFFI versions ofthe decimal module integrate the high speedlibmpdec library forarbitrary precision correctly rounded decimal floating-point arithmetic[1].libmpdec usesKaratsuba multiplicationfor medium-sized numbers and theNumber Theoretic Transformfor very large numbers.

The context must be adapted for exact arbitrary precision arithmetic.EminandEmax should always be set to the maximum values,clampshould always be 0 (the default). Settingprec requires some care.

The easiest approach for trying out bignum arithmetic is to use the maximumvalue forprec as well[2]:

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

For inexact results,MAX_PREC is far too large on 64-bit platforms andthe available memory will be insufficient:

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

On systems with overallocation (e.g. Linux), a more sophisticated approach is toadjustprec to the amount of available RAM. Suppose that you have 8GB ofRAM and expect 10 simultaneous operands using a maximum of 500MB each:

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

In general (and especially on systems without overallocation), it is recommendedto estimate even tighter bounds and set theInexact trap if all calculationsare expected to be exact.