decimal
--- Decimal fixed-point and floating-point arithmetic¶
Code source : Lib/decimal.py
The decimal
module provides support for fast correctly rounded
decimal floating-point arithmetic. It offers several advantages over the
float
datatype:
Le module
decimal
« est basé sur un modèle en virgule flottante conçu pour les humains, qui suit ce principe directeur : l'ordinateur doit fournir un modèle de calcul qui fonctionne de la même manière que le calcul qu'on apprend à l'école » – extrait (traduit) de la spécification de l'arithmétique décimale.Les nombres décimaux peuvent être représentés exactement en base décimale flottante. En revanche, des nombres tels que
1.1
ou1.2
n'ont pas de représentation exacte en base binaire flottante. L'utilisateur final ne s'attend typiquement pas à obtenir3.3000000000000003
lorsqu'il saisit1.1 + 2.2
, ce qui se passe en arithmétique binaire à virgule flottante.Ces inexactitudes ont des conséquences en arithmétique. En base décimale à virgule flottante,
0.1 + 0.1 + 0.1 - 0.3
est exactement égal à zéro. En virgule flottante binaire, l'ordinateur l'évalue à5.5511151231257827e-017
. Bien que très proche de zéro, cette différence induit des erreurs lors des tests d'égalité, erreurs qui peuvent s'accumuler. Pour ces raisonsdecimal
est le module utilisé pour des applications comptables ayant des contraintes strictes de fiabilité.Le module
decimal
incorpore la notion de chiffres significatifs, de façon à ce que1.30 + 1.20
égale2.50
. Le dernier zéro est conservé pour respecter le nombre de chiffres significatifs. C'est l'affichage préféré pour représenter des sommes d'argent. Pour la multiplication, l'approche « scolaire » utilise tous les chiffres présents dans les facteurs. Par exemple,1.3 * 1.2
donne1.56
tandis que1.30 * 1.20
donne1.5600
.Contrairement à l'arithmétique en virgule flottante binaire, le module
decimal
possède un paramètre de précision ajustable (par défaut à 28 chiffres significatifs) qui peut être aussi élevée que nécessaire pour un problème donné :>>> from decimal import * >>> getcontext().prec = 6 >>> Decimal(1) / Decimal(7) Decimal('0.142857') >>> getcontext().prec = 28 >>> Decimal(1) / Decimal(7) Decimal('0.1428571428571428571428571429')
L'arithmétique binaire et décimale en virgule flottante sont implémentées selon des standards publiés. Alors que le type
float
n'expose qu'une faible portion de ses capacités, le moduledecimal
expose tous les composants nécessaires du standard. Lorsque nécessaire, le développeur a un contrôle total de la gestion des signaux et de l'arrondi. Cela inclut la possibilité de forcer une arithmétique exacte en utilisant des exceptions pour bloquer toute opération inexacte.Le module
decimal
a été conçu pour gérer « sans préjugé, à la fois une arithmétique décimale non-arrondie (aussi appelée arithmétique en virgule fixe) et à la fois une arithmétique en virgule flottante » (extrait traduit de la spécification de l'arithmétique décimale).
Le module est conçu autour de trois concepts : le nombre décimal, le contexte arithmétique et les signaux.
Un Decimal
est immuable. Il a un signe, un coefficient et un exposant. Pour préserver le nombre de chiffres significatifs, les zéros en fin de chaîne ne sont pas tronqués. Les décimaux incluent aussi des valeurs spéciales telles que Infinity
, -Infinity
et NaN
. Le standard fait également la différence entre -0
et +0
.
Le contexte de l'arithmétique est un environnement qui permet de configurer une précision, une règle pour l'arrondi, des limites sur l'exposant, des options indiquant le résultat des opérations et si les signaux (remontés lors d'opérations illégales) sont traités comme des exceptions Python. Les options d'arrondi incluent ROUND_CEILING
, ROUND_DOWN
, ROUND_FLOOR
, ROUND_HALF_DOWN
, ROUND_HALF_EVEN
, ROUND_HALF_UP
, ROUND_UP
et ROUND_05UP
.
Les signaux sont des groupes de conditions exceptionnelles qui surviennent durant le calcul. Selon les besoins de l'application, les signaux peuvent être ignorés, considérés comme de l'information, ou bien traités comme des exceptions. Les signaux dans le module decimal
sont : Clamped
, InvalidOperation
, DivisionByZero
, Inexact
, Rounded
, Subnormal
, Overflow
, Underflow
et FloatOperation
.
Chaque signal est configurable indépendamment, à travers un drapeau (ou option) et un activateur de déroutement. Quand une opération illégale survient, le drapeau du signal est mis à 1
puis, si l'activateur est configuré, une exception est levée. La mise à 1
du drapeau est persistante, l'utilisateur doit donc remettre les drapeaux à zéro avant de commencer un calcul qu'il souhaite surveiller.
Voir aussi
Spécification d'IBM sur l'arithmétique décimale : The General Decimal Arithmetic Specification (article en anglais).
Introduction pratique¶
Commençons par importer le module, regarder le contexte actuel avec getcontext()
et, si nécessaire, configurer la précision, l'arrondi et la gestion des signaux :
>>> from decimal import *
>>> 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
Les instances de Decimal
peuvent être construites avec des entiers, des chaînes de caractères, des floats
ou des n-uplets. La construction depuis un entier ou un float
effectue la conversion exacte de cet entier ou de ce float
. Les nombres décimaux incluent des valeurs spéciales telles que NaN
qui signifie en anglais « Not a number », en français « pas un nombre », des Infinity
positifs ou négatifs et -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')
Si le signal FloatOperation
est activé pour déroutement, un mélange accidentel d'objets Decimal
et de float
dans les constructeurs ou des opérations de comparaison lève une exception :
>>> c = getcontext()
>>> c.traps[FloatOperation] = True
>>> Decimal(3.14)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
>>> Decimal('3.5') < 3.7
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
>>> Decimal('3.5') == 3.5
True
Ajouté dans la version 3.3.
Le nombre de chiffres significatifs d'un nouvel objet Decimal
est déterminé entièrement par le nombre de chiffres saisis. La précision et les règles d'arrondis n'interviennent que lors d'opérations arithmétiques.
>>> 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')
Si les limites internes de la version en C sont dépassées, la construction d'un objet décimal lève l'exception InvalidOperation
:
>>> Decimal("1e9999999999999999999")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>]
Modifié dans la version 3.3.
Decimals interact well with much of the rest of Python. Here is a small decimal floating-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 * 5
Decimal('6.70')
>>> a * b
Decimal('2.5058')
>>> c % a
Decimal('0.77')
Et certaines fonctions mathématiques sont également disponibles sur des instances de 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')
La méthode quantize()
arrondit un nombre à un exposant déterminé. Cette méthode est utile pour des applications monétaires qui arrondissent souvent un résultat à un nombre déterminé de chiffres après la virgule :
>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
Decimal('7.32')
>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
Decimal('8')
Comme montré plus haut, la fonction getcontext()
accède au contexte actuel et permet de modifier les paramètres. Cette approche répond aux besoins de la plupart des applications.
Pour un travail plus avancé, il peut être utile de créer des contextes alternatifs en utilisant le constructeur de Context
. Pour activer cet objet Context
, utilisez la fonction setcontext()
.
En accord avec le standard, le module decimal
fournit des objets Context standards, BasicContext
et ExtendedContext
. Le premier est particulièrement utile pour le débogage car beaucoup des signaux ont leur déroutement activé :
>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
>>> setcontext(myothercontext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857142857142857142857142857')
>>> ExtendedContext
Context(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>", line 1, in -toplevel-
Decimal(42) / Decimal(0)
DivisionByZero: x / 0
Les objets Context
ont aussi des options pour détecter des opérations illégales lors des calculs. Ces options restent activées jusqu'à ce qu'elles soit remises à zéro de manière explicite. Il convient donc de remettre à zéro ces options avant chaque inspection de chaque calcul, avec la méthode clear_flags()
.
>>> 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=[])
Les options montrent que l'approximation de π par une fraction a été arrondie (les chiffres au-delà de la précision spécifiée par l'objet Context ont été tronqués) et que le résultat est différent (certains des chiffres tronqués étaient différents de zéro).
L'activation du déroutement se fait en utilisant un dictionnaire dans l'attribut traps
du contexte :
>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(0)
Decimal('Infinity')
>>> getcontext().traps[DivisionByZero] = 1
>>> Decimal(1) / Decimal(0)
Traceback (most recent call last):
File "<pyshell#112>", line 1, in -toplevel-
Decimal(1) / Decimal(0)
DivisionByZero: x / 0
La plupart des applications n'ajustent l'objet Context
qu'une seule fois, au démarrage. Et, dans beaucoup d'applications, les données sont converties une fois pour toutes en Decimal
. Une fois le Context
initialisé et les objets Decimal
créés, la majeure partie du programme manipule les données de la même manière qu'avec d'autres types numériques Python.
Les objets Decimal¶
- class decimal.Decimal(value='0', context=None)¶
Construit un nouvel objet
Decimal
à partir de value.value peut être un entier, une chaîne de caractères, un n-uplet, un
float
ou une autre instance deDecimal
. Si value n'est pas fourni, le constructeur renvoieDecimal('0')
. Si value est une chaîne de caractères, elle doit correspondre à la syntaxe décimale en dehors des espaces de début et de fin, ou des tirets bas, qui sont enlevés :sign ::= '+' | '-' digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' indicator ::= 'e' | 'E' digits ::= digit [digit]... decimal-part ::= digits '.' [digits] | ['.'] digits exponent-part ::= indicator [sign] digits infinity ::= 'Infinity' | 'Inf' nan ::= 'NaN' [digits] | 'sNaN' [digits] numeric-value ::= decimal-part [exponent-part] | infinity numeric-string ::= [sign] numeric-value | [sign] nan
Les chiffres codés en Unicode sont aussi autorisés, dans les emplacements
digit
ci-dessus. Cela inclut des chiffres décimaux venant d'autres alphabets (par exemple les chiffres indo-arabes ou Devanagari) ainsi que les chiffres de pleine largeur'\uff10'
jusqu'à'\uff19'
.Si value est un
n-uplet
, il doit avoir trois éléments, le signe (0
pour positif ou1
pour négatif), unn-uplet
de chiffres et un entier représentant l'exposant. Par exemple,Decimal((0, (1, 4, 1, 4), -3))
construit l'objetDecimal('1.414')
.If value is a
float
, the binary floating-point value is losslessly converted to its exact decimal equivalent. This conversion can often require 53 or more digits of precision. For example,Decimal(float('1.1'))
converts toDecimal('1.100000000000000088817841970012523233890533447265625')
.La précision spécifiée dans le contexte n'affecte pas le nombre de chiffres stockés. Cette valeur est déterminée exclusivement par le nombre de chiffres dans value. Par exemple,
Decimal('3.00000')
enregistre les 5 zéros même si la précision du contexte est de 3.L'objectif de l'argument context est de déterminer ce que Python doit faire si value est une chaîne avec un mauvais format. Si le déroutement est activé pour
InvalidOperation
, une exception est levée, sinon le constructeur renvoie un objetDecimal
de valeurNaN
.Une fois construit, un objet
Decimal
est immuable.Modifié dans la version 3.2: l'argument du constructeur peut désormais être un objet
float
.Modifié dans la version 3.3: un argument
float
lève une exception si le déroutement est activé pourFloatOperation
. Par défaut le déroutement n'est pas activé.Modifié dans la version 3.6: les tirets bas sont autorisés pour regrouper, tout comme pour l'arithmétique en virgule fixe et flottante.
Decimal floating-point objects share many properties with the other built-in numeric types such as
float
andint
. All of the usual math operations and special methods apply. Likewise, decimal objects can be copied, pickled, printed, used as dictionary keys, used as set elements, compared, sorted, and coerced to another type (such asfloat
orint
).Il existe quelques différences mineures entre l'arithmétique entre les objets décimaux et l'arithmétique avec les entiers et les
float
. Quand l'opérateur modulo%
est appliqué sur des objets décimaux, le signe du résultat est le signe du dividende plutôt que le signe du diviseur :>>> (-7) % 4 1 >>> Decimal(-7) % Decimal(4) Decimal('-3')
L'opérateur division entière (
//
) se comporte de la même manière, renvoyant la partie entière du quotient plutôt que son arrondi, de manière à préserver l'identité d'Euclidex == (x // y) * y + x % y
:>>> -7 // 4 -2 >>> Decimal(-7) // Decimal(4) Decimal('-1')
Les opérateurs
//
et%
implémentent la division entière et le reste (ou modulo), respectivement, tels que décrits dans la spécification.Les objets
Decimal
ne peuvent généralement pas être combinés avec desfloat
ou des objetsfractions.Fraction
lors d'opérations arithmétiques : toute addition entre unDecimal
et unfloat
, par exemple, lève une exceptionTypeError
. Cependant, il est possible d'utiliser les opérateurs de comparaison entre instances deDecimal
et les autres types numériques. Cela évite d'avoir des résultats absurdes lors des tests d'égalité entre différents types.Modifié dans la version 3.2: les comparaisons inter-types entre
Decimal
et les autres types numériques sont désormais intégralement gérées.In addition to the standard numeric properties, decimal floating-point objects also have a number of specialized methods:
- adjusted()¶
Renvoie l'exposant ajusté après avoir décalé les chiffres les plus à droite du coefficient jusqu'à ce qu'il ne reste que le premier chiffre :
Decimal('321e+5').adjusted()
renvoie sept. Utilisée pour déterminer la position du chiffre le plus significatif par rapport à la virgule.
- as_integer_ratio()¶
Renvoie un couple d'entiers
(n, d)
qui représentent l'instanceDecimal
donnée sous la forme d'une fraction, avec les termes les plus petits possibles et avec un dénominateur positif :>>> Decimal('-3.14').as_integer_ratio() (-157, 50)
La conversion est exacte. Lève une
OverflowError
sur l'infini etValueError
sur les Nan.
Ajouté dans la version 3.6.
- as_tuple()¶
Renvoie une représentation sous la forme d'un n-uplet nommé du nombre
DecimalTuple(sign, digits, exposant)
.
- canonical()¶
Renvoie la forme canonique de l'argument. Actuellement, la forme d'une instance
Decimal
est toujours canonique, donc cette opération renvoie son argument inchangé.
- compare(other, context=None)¶
Compare les valeurs de deux instances Decimal.
compare()
renvoie une instance Decimal et, si l'un des opérandes est un NaN, alors le résultat est un NaN :a or b is a NaN ==> Decimal('NaN') a < b ==> Decimal('-1') a == b ==> Decimal('0') a > b ==> Decimal('1')
- compare_signal(other, context=None)¶
Cette opération est identique à la méthode
compare()
, sauf que tous les NaN activent un déroutement. Autrement dit, si aucun des opérandes n'est un NaN de signalisation, alors tout opérande NaN silencieux est traité comme s'il s'agissait d'un NaN de signalisation.
- compare_total(other, context=None)¶
Compare deux opérandes en utilisant leur représentation abstraite plutôt que leur valeur numérique. Similaire à la méthode
compare()
, mais le résultat donne un ordre total sur les instancesDecimal
. Deux instances deDecimal
avec la même valeur numérique mais des représentations différentes se comparent de manière inégale dans cet ordre :>>> Decimal('12.0').compare_total(Decimal('12')) Decimal('-1')
Les NaN silencieux et de signalisation sont également inclus dans l'ordre total. Le résultat de cette fonction est
Decimal('0')
si les deux opérandes ont la même représentation,Decimal('-1')
si le premier opérande est inférieur au second, etDecimal('1')
si le premier opérande est supérieur au deuxième opérande. Voir les spécifications pour les détails de l'ordre total.Cette opération ne dépend pas du contexte et est silencieuse : aucun indicateur n'est modifié et aucun arrondi n'est effectué. Exceptionnellement, la version C peut lever une InvalidOperation si le deuxième opérande ne peut pas être converti exactement.
- compare_total_mag(other, context=None)¶
Compare deux opérandes en utilisant leur représentation abstraite plutôt que leur valeur comme dans
compare_total()
, mais en ignorant le signe de chaque opérande.x.compare_total_mag(y)
est équivalent àx.copy_abs().compare_total(y.copy_abs())
.Cette opération ne dépend pas du contexte et est silencieuse : aucun indicateur n'est modifié et aucun arrondi n'est effectué. Exceptionnellement, la version C peut lever une InvalidOperation si le deuxième opérande ne peut pas être converti exactement.
- conjugate()¶
Ne fait que renvoyer self ; cette méthode existe uniquement pour se conformer à la spécification.
- copy_abs()¶
Renvoie la valeur absolue de l'argument. Cette opération ne dépend pas du contexte et est silencieuse : aucun drapeau n'est modifié et aucun arrondi n'est effectué.
- copy_negate()¶
Renvoie la négation de l'argument. Cette opération ne dépend pas du contexte et est silencieuse : aucun drapeau n'est modifié et aucun arrondi n'est effectué.
- copy_sign(other, context=None)¶
Renvoie une copie du premier opérande mais avec le même signe que celui du deuxième opérande. Par exemple :
>>> Decimal('2.3').copy_sign(Decimal('-1.5')) Decimal('-2.3')
Cette opération ne dépend pas du contexte et est silencieuse : aucun indicateur n'est modifié et aucun arrondi n'est effectué. Exceptionnellement, la version C peut lever une InvalidOperation si le deuxième opérande ne peut pas être converti exactement.
- exp(context=None)¶
Renvoie la valeur
e**x
(fonction exponentielle) du nombre donné. Le résultat est correctement arrondi en utilisant le mode d'arrondiROUND_HALF_EVEN
.>>> Decimal(1).exp() Decimal('2.718281828459045235360287471') >>> Decimal(321).exp() Decimal('2.561702493119680037517373933E+139')
- classmethod from_float(f)¶
Constructeur alternatif qui n'accepte que les instances de
float
ouint
.Remarquez que
Decimal.from_float(0.1)
est différent deDecimal('0.1')
. Puisque 0.1 n'est pas exactement représentable en virgule flottante binaire, la valeur est stockée comme la valeur représentable la plus proche qui est0x1.999999999999ap-4
. La valeur équivalente en décimal est0.1000000000000000055511151231257827021181583404541015625
.Note
depuis Python 3.2, une instance
Decimal
peut également être construite directement à partir d'unfloat
.>>> 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')
Ajouté dans la version 3.1.
- fma(other, third, context=None)¶
Multiplier-ajouter fusionné. Renvoie
self*other+third
sans arrondir le produit intermédiaireself*other
.>>> Decimal(2).fma(3, 5) Decimal('11')
- is_canonical()¶
Renvoie
True
si l'argument est sous forme canonique etFalse
sinon. Actuellement, une instanceDecimal
est toujours canonique, donc cette opération renvoie toujoursTrue
.
- is_finite()¶
Renvoie
True
si l'argument est un nombre fini etFalse
si l'argument est un infini ou un NaN.
- is_normal(context=None)¶
Renvoie
True
si l'argument est un nombre fini normal. RenvoieFalse
si l'argument est zéro, infini, résultat d'un dépassement par valeur inférieure ou un NaN.
- is_signed()¶
Renvoie
True
si l'argument est négatif,False
sinon. Remarquez que les zéros et les NaN peuvent être signés.
- is_subnormal(context=None)¶
Renvoie
True
si l'argument est le résultat d'un dépassement par valeur inférieure,False
sinon.
- ln(context=None)¶
Renvoie le logarithme naturel (base e) de l'opérande. Le résultat est arrondi avec le mode
ROUND_HALF_EVEN
.
- log10(context=None)¶
Renvoie le logarithme en base 10 de l'opérande. Le résultat est arrondi avec le mode
ROUND_HALF_EVEN
.
- logb(context=None)¶
Pour un nombre non nul, renvoie l'exposant ajusté de son opérande en tant qu'instance
Decimal
. Si l'opérande est un zéro alorsDecimal('-Infinity')
est renvoyé et le drapeauDivisionByZero
est levé. Si l'opérande est un infini alorsDecimal('Infinity')
est renvoyé.
- logical_and(other, context=None)¶
logical_and()
est une opération logique qui prend deux opérandes logiques (voir Opérandes logiques). Le résultat est le ET des chiffres des deux opérandes.
- logical_invert(context=None)¶
logical_invert()
est une opération logique. Le résultat est l'inversion de chacun des chiffres de l'opérande.
- logical_or(other, context=None)¶
logical_or()
est une opération logique qui prend deux opérandes logiques (voir Opérandes logiques). Le résultat est le OU des chiffres des deux opérandes.
- logical_xor(other, context=None)¶
logical_xor()
est une opération logique qui prend deux opérandes logiques (voir Opérandes logiques). Le résultat est le OU EXCLUSIF des chiffres des deux opérandes.
- max(other, context=None)¶
Comme
max(self, other)
sauf que la règle d'arrondi de context est appliquée avant le retour et que les valeursNaN
sont signalées ou ignorées (selon le contexte et si elles sont signalétiques ou silencieuses).
- max_mag(other, context=None)¶
Semblable à la méthode
max()
, mais la comparaison est effectuée en utilisant les valeurs absolues des opérandes.
- min(other, context=None)¶
Comme
min(self, other)
sauf que la règle d'arrondi de context est appliquée avant le retour et que les valeursNaN
sont signalées ou ignorées (selon le contexte et si elles sont signalétiques ou silencieuses).
- min_mag(other, context=None)¶
Semblable à la méthode
min()
, mais la comparaison est effectuée en utilisant les valeurs absolues des opérandes.
- next_minus(context=None)¶
Renvoie le plus grand nombre représentable dans le context donné (ou dans le contexte du fil d'exécution actuel si aucun contexte n'est donné) qui est plus petit que l'opérande donné.
- next_plus(context=None)¶
Renvoie le plus petit nombre représentable dans le context donné (ou dans le contexte du fil d'exécution actuel si aucun contexte n'est donné) qui est supérieur à l'opérande donné.
- next_toward(other, context=None)¶
Si les deux opérandes ne sont pas égaux, renvoie le nombre le plus proche du premier opérande dans la direction du deuxième opérande. Si les deux opérandes sont numériquement égaux, renvoie une copie du premier opérande avec le signe défini comme étant le même que le signe du second opérande.
- normalize(context=None)¶
Used for producing canonical values of an equivalence class within either the current context or the specified context.
This has the same semantics as the unary plus operation, except that if the final result is finite it is reduced to its simplest form, with all trailing zeros removed and its sign preserved. That is, while the coefficient is non-zero and a multiple of ten the coefficient is divided by ten and the exponent is incremented by 1. Otherwise (the coefficient is zero) the exponent is set to 0. In all cases the sign is unchanged.
For example,
Decimal('32.100')
andDecimal('0.321000e+2')
both normalize to the equivalent valueDecimal('32.1')
.Note that rounding is applied before reducing to simplest form.
In the latest versions of the specification, this operation is also known as
reduce
.
- number_class(context=None)¶
Renvoie une chaîne décrivant la classe de l'opérande. La valeur renvoyée est l'une des dix chaînes suivantes.
"-Infinity"
, indiquant que l'opérande est l'infini négatif ;"-Normal"
, indiquant que l'opérande est un nombre négatif normal ;"-Subnormal"
, indiquant que l'opérande est négatif et qu'il est le résultat d'un dépassement par valeur inférieure ;"-Zero"
, indiquant que l'opérande est un zéro négatif ;"+Zero"
, indiquant que l'opérande est un zéro positif ;"+Subnormal"
, indiquant que l'opérande est positif et qu'il est le résultat un dépassement par valeur inférieure ;"+Normal"
, indiquant que l'opérande est un nombre positif normal ;"+Infinity"
, indiquant que l'opérande est l'infini positif ;"NaN"
, indiquant que l'opérande est un NaN (Not a Number, pas un nombre) silencieux ;"sNaN"
, indiquant que l'opérande est un NaN (Not a Number, pas un nombre) signalétique.
- quantize(exp, rounding=None, context=None)¶
Renvoie une valeur égale au premier opérande après arrondi et ayant l'exposant du second opérande.
>>> Decimal('1.41421356').quantize(Decimal('1.000')) Decimal('1.414')
Contrairement aux autres opérations, si la longueur du coefficient après l'opération de quantification est supérieure à la précision, alors une
InvalidOperation
est signalée. Ceci garantit que, sauf condition d'erreur, l'exposant quantifié est toujours égal à celui de l'opérande de droite.Contrairement aux autres opérations, la quantification ne signale jamais de dépassement par valeur inférieure, même si le résultat est inférieur à la valeur minimale représentable et inexact.
Si l'exposant du deuxième opérande est supérieur à celui du premier, un arrondi peut être nécessaire. Dans ce cas, le mode d'arrondi est déterminé par l'argument
rounding
s'il est donné, sinon par l'argumentcontext
donné ; si aucun argument n'est donné, le mode d'arrondi du contexte du fil d'exécution courant est utilisé.Une erreur est renvoyée chaque fois que l'exposant résultant est supérieur à
Emax
ou inférieur àEtiny()
.
- radix()¶
Renvoie
Decimal(10)
, la base (base) dans laquelle la classeDecimal
fait toute son arithmétique. Inclus pour la compatibilité avec la spécification.
- remainder_near(other, context=None)¶
Renvoie le reste de la division de self par other. La différence avec
self % other
réside dans le signe du reste, qui est choisi de manière à minimiser sa valeur absolue. Plus précisément, la valeur de retour estself - n * other
oùn
est l'entier le plus proche de la valeur exacte deself / other
et, si deux entiers sont également proches, alors l'entier pair est choisi.Si le résultat est zéro, alors son signe est le signe de self.
>>> 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)¶
Renvoie le résultat de la rotation des chiffres du premier opérande d'une quantité spécifiée par le deuxième opérande. Le deuxième opérande doit être un entier compris dans la plage -précision à précision. La valeur absolue du deuxième opérande donne le nombre de rotations unitaires à faire. Si le deuxième opérande est positif alors la rotation se fait vers la gauche ; sinon la rotation se fait vers la droite. Le coefficient du premier opérande est complété à gauche avec des zéros à la précision de la longueur si nécessaire. Le signe et l'exposant du premier opérande sont inchangés.
- same_quantum(other, context=None)¶
Teste si self et other ont le même exposant ou si les deux sont
NaN
.Cette opération ne dépend pas du contexte et est silencieuse : aucun indicateur n'est modifié et aucun arrondi n'est effectué. Exceptionnellement, la version C peut lever une InvalidOperation si le deuxième opérande ne peut pas être converti exactement.
- scaleb(other, context=None)¶
Renvoie le premier opérande avec l'exposant ajusté par le second. De manière équivalente, renvoie le premier opérande multiplié par
10**other
. Le deuxième opérande doit être entier.
- shift(other, context=None)¶
Renvoie le résultat du décalage des chiffres du premier opérande d'une quantité spécifiée par le deuxième opérande. Le deuxième opérande doit être un entier compris dans la plage -précision à précision. La valeur absolue du deuxième opérande donne le nombre de décalages unitaires à effectuer. Si le deuxième opérande est positif alors le décalage est vers la gauche ; sinon le décalage est vers la droite. Les chiffres insérés dans le nombre par le décalage sont des zéros. Le signe et l'exposant du premier opérande sont inchangés.
- sqrt(context=None)¶
Renvoie la racine carrée de l'argument avec une précision maximale.
- to_eng_string(context=None)¶
Convertir en chaîne, en utilisant la notation ingénieur si un exposant est nécessaire.
La notation ingénieur possède un exposant qui est un multiple de 3. Cela peut laisser jusqu'à 3 chiffres à gauche de la décimale et peut nécessiter l'ajout d'un ou de deux zéros à la fin.
Par exemple,
Decimal('123E+1')
est converti enDecimal('1.23E+3')
.
- to_integral(rounding=None, context=None)¶
Identique à la méthode
to_integral_value()
. Le nomto_integral
a été conservé pour la compatibilité avec les anciennes versions.
- to_integral_exact(rounding=None, context=None)¶
Arrondit à l'entier le plus proche, en signalant
Inexact
ouRounded
selon le cas si l'arrondi se produit. Le mode d'arrondi est déterminé par le paramètrerounding
s'il est donné, sinon par lecontext
donné. Si aucun paramètre n'est donné, le mode d'arrondi du contexte courant est utilisé.
- to_integral_value(rounding=None, context=None)¶
Arrondit à l'entier le plus proche sans signaler
Inexact
ouRounded
. Si donné, applique rounding ; sinon, utilise la méthode d'arrondi dans le context fourni ou dans le contexte actuel.
Decimal numbers can be rounded using the
round()
function:- round(number)
- round(number, ndigits)
If ndigits is not given or
None
, returns the nearestint
to number, rounding ties to even, and ignoring the rounding mode of theDecimal
context. RaisesOverflowError
if number is an infinity orValueError
if it is a (quiet or signaling) NaN.If ndigits is an
int
, the context's rounding mode is respected and aDecimal
representing number rounded to the nearest multiple ofDecimal('1E-ndigits')
is returned; in this case,round(number, ndigits)
is equivalent toself.quantize(Decimal('1E-ndigits'))
. ReturnsDecimal('NaN')
if number is a quiet NaN. RaisesInvalidOperation
if number is an infinity, a signaling NaN, or if the length of the coefficient after the quantize operation would be greater than the current context's precision. In other words, for the non-corner cases:if ndigits is positive, return number rounded to ndigits decimal places;
if ndigits is zero, return number rounded to the nearest integer;
if ndigits is negative, return number rounded to the nearest multiple of
10**abs(ndigits)
.
Par exemple :
>>> from decimal import Decimal, getcontext, ROUND_DOWN >>> getcontext().rounding = ROUND_DOWN >>> round(Decimal('3.75')) # context rounding ignored 4 >>> round(Decimal('3.5')) # round-ties-to-even 4 >>> round(Decimal('3.75'), 0) # uses the context rounding Decimal('3') >>> round(Decimal('3.75'), 1) Decimal('3.7') >>> round(Decimal('3.75'), -1) Decimal('0E+1')
Opérandes logiques¶
Les méthodes logical_and()
, logical_invert()
, logical_or()
et logical_xor()
s'attendent à ce que leurs arguments soient des opérandes logiques. Un opérande logique est une instance Decimal
dont l'exposant et le signe sont tous les deux zéro et dont les chiffres sont tous 0
ou 1
.
Objets de contexte¶
Les contextes sont des environnements pour les opérations arithmétiques. Ils régissent la précision, établissent des règles d'arrondi, déterminent quels signaux sont traités comme des exceptions et limitent la plage des exposants.
Chaque fil d'exécution a son propre contexte actuel qui est accessible ou modifié à l'aide des fonctions getcontext()
et setcontext()
:
- decimal.getcontext()¶
Renvoie le contexte actuel du fil d'exécution courant.
- decimal.setcontext(c)¶
Définit le contexte du fil d'exécution courant à c.
Vous pouvez également utiliser l'instruction with
et la fonction localcontext()
pour modifier temporairement le contexte actif.
- decimal.localcontext(ctx=None, **kwargs)¶
Renvoie un gestionnaire de contexte qui définira le contexte actuel du fil d'exécution actif sur une copie de ctx à l'entrée de l'instruction with et restaurera le contexte précédent lors de la sortie de l'instruction with. Si aucun contexte n'est spécifié, une copie du contexte actuel est utilisée. L'argument kwargs est utilisé pour définir les attributs du nouveau contexte.
Par exemple, le code suivant définit la précision décimale actuelle à 42 chiffres, effectue un calcul, puis restaure automatiquement le contexte précédent :
from decimal import localcontext with localcontext() as ctx: ctx.prec = 42 # Perform a high precision calculation s = calculate_something() s = +s # Round the final result back to the default precision
En utilisant des arguments nommés, le code serait le suivant :
from decimal import localcontext with localcontext(prec=42) as ctx: s = calculate_something() s = +s
Lève
TypeError
si kwargs fournit un attribut queContext
ne prend pas en charge. Lève soitTypeError
ouValueError
si kwargs fournit une valeur invalide pour un attribut.Modifié dans la version 3.11:
localcontext()
prend désormais en charge la définition des attributs de contexte grâce à l'utilisation d'arguments nommés.
De nouveaux contextes peuvent également être créés à l'aide du constructeur Context
décrit ci-dessous. De plus, le module fournit trois contextes prédéfinis :
- class decimal.BasicContext¶
Il s'agit d'un contexte standard défini par la General Decimal Arithmetic Specification. La précision est fixée à neuf. L'arrondi est défini sur
ROUND_HALF_UP
. Tous les drapeaux sont effacés. Tous les déroutements sont activés (ils lèvent des exceptions) saufInexact
,Rounded
etSubnormal
.Étant donné que de nombreuses options de déroutement sont activées, ce contexte est utile pour le débogage.
- class decimal.ExtendedContext¶
Il s'agit d'un contexte standard défini par la General Decimal Arithmetic Specification. La précision est fixée à neuf. L'arrondi est défini sur
ROUND_HALF_EVEN
. Toutes les options de déroutement sont désactivées (afin que les exceptions ne soient pas levées pendant les calculs).Comme les interruptions sont désactivées, ce contexte est utile pour les applications qui préfèrent avoir une valeur de résultat
NaN
ouInfinity
au lieu de lever des exceptions. Cela permet à une application de terminer une exécution en présence de conditions qui, autrement, arrêteraient le programme.
- class decimal.DefaultContext¶
Ce contexte est utilisé par le constructeur
Context
comme prototype pour de nouveaux contextes. Changer un champ (par exemple la précision) a pour effet de changer la valeur par défaut pour les nouveaux contextes créés par le constructeurContext
.Ce contexte est particulièrement utile dans les environnements à plusieurs fils d'exécution. La modification de l'un des champs avant le démarrage des fils a pour effet de définir des valeurs par défaut à l'échelle du système. La modification des champs après le démarrage des fils d'exécution n'est pas recommandée car cela nécessiterait une synchronisation des fils d'exécution pour éviter des conditions de concurrence.
Dans les environnements à fil d'exécution unique, il est préférable de ne pas utiliser ce contexte du tout. Créez plutôt simplement des contextes explicitement comme décrit ci-dessous.
Les valeurs par défaut sont
Context.prec
=28
,Context.rounding
=ROUND_HALF_EVEN
et les interruptions sont activées pourOverflow
,InvalidOperation
etDivisionByZero
.
En plus des trois contextes fournis, de nouveaux contextes peuvent être créés avec le constructeur 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 theDefaultContext
. If the flags field is not specified or isNone
, 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
or1
(the default). If set to1
, exponents are printed with a capitalE
; otherwise, a lowercasee
is used:Decimal('6.02e+23')
.The clamp field is either
0
(the default) or1
. If set to1
, the exponente
of aDecimal
instance representable in this context is strictly limited to the rangeEmin - prec + 1 <= e <= Emax - prec + 1
. If clamp is0
then a weaker condition holds: the adjusted exponent of theDecimal
instance is at mostEmax
. When clamp is1
, 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 theDecimal
methods described above (with the exception of theadjusted()
andas_tuple()
methods) there is a correspondingContext
method. For example, for aContext
instanceC
andDecimal
instancex
,C.exp(x)
is equivalent tox.exp(context=C)
. EachContext
method accepts a Python integer (an instance ofint
) 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
.Ajouté dans la 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 or underscores are 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
Ajouté dans la 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 toEtiny
.
- 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 theDecimal
class and are only briefly recounted here.- abs(x)¶
Renvoie la valeur absolue de x.
- add(x, y)¶
Renvoie la somme de x et 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)¶
Renvoie une copie de x mais de signe opposé.
- copy_sign(x, y)¶
Copie le signe de y vers x.
- divide(x, y)¶
Renvoie x divisé par y.
- divide_int(x, y)¶
Renvoie x divisé par y, tronqué comme entier.
- divmod(x, y)¶
Renvoie la partie entière de la division entre deux nombres.
- exp(x)¶
Renvoie
e ** x
.
- fma(x, y, z)¶
Renvoie x multiplié par y, plus z.
- is_canonical(x)¶
Returns
True
if x is canonical; otherwise returnsFalse
.
- is_finite(x)¶
Returns
True
if x is finite; otherwise returnsFalse
.
- is_infinite(x)¶
Renvoie
True
si x est infini etFalse
sinon.
- is_nan(x)¶
Renvoie
True
si x est un NaN (silencieux ou signalétique),False
sinon.
- is_normal(x)¶
Returns
True
if x is a normal number; otherwise returnsFalse
.
- is_qnan(x)¶
Renvoie
True
si x est un NaN silencieux,False
sinon.
- is_signed(x)¶
Renvoie
True
si x est négatif etFalse
sinon.
- is_snan(x)¶
Renvoie
True
si x est un NaN signalétique,False
sinon.
- is_subnormal(x)¶
Returns
True
if x is subnormal; otherwise returnsFalse
.
- is_zero(x)¶
Renvoie
True
si x est un zéro etFalse
sinon.
- ln(x)¶
Renvoie le logarithme naturel (en base e) de x.
- log10(x)¶
Renvoie le logarithme en base 10 de 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)¶
Renvoie le maximum entre les deux valeurs numériques.
- 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)¶
Renvoie la multiplication de x avec 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)¶
Réduit x à sa forme la plus simple.
- 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 ofy
, reduced modulomodulo
if given.With two arguments, compute
x**y
. Ifx
is negative theny
must be integral. The result will be inexact unlessy
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.Decimal(0) ** Decimal(0)
results inInvalidOperation
, and ifInvalidOperation
is not trapped, then results inDecimal('NaN')
.Modifié dans la version 3.3: The C module computes
power()
in terms of the correctly roundedexp()
andln()
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
ne doit pas être négatif ;au moins l'un de
x
ouy
doit être différent de zéro ;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 ofx
,y
andmodulo
. The result is always exact.
- quantize(x, y)¶
Returns a value equal to x (rounded), having the exponent of y.
- radix()¶
Renvoie 10 car c'est Decimal, :)
- remainder(x, y)¶
Renvoie le reste de la division entière.
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 ofx / 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)¶
Renvoie
True
si les deux opérandes ont le même exposant.
- 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)¶
Convertir en chaîne, en utilisant la notation ingénieur si un exposant est nécessaire.
La notation ingénieur possède un exposant qui est un multiple de 3. Cela peut laisser jusqu'à 3 chiffres à gauche de la décimale et peut nécessiter l'ajout d'un ou de deux zéros à la fin.
- to_integral_exact(x)¶
Rounds to an integer.
- to_sci_string(x)¶
Converts a number to a string using scientific notation.
Constantes¶
Les constantes de cette section ne sont pertinentes que pour le module C. Elles sont aussi incluses pour la compatibilité dans la version en Python pur.
32-bit |
64-bit |
|
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
- decimal.HAVE_THREADS¶
La valeur est
True
. Déprécié, parce que maintenant Python possède toujours des fils d'exécution.Obsolète depuis la version 3.9.
- decimal.HAVE_CONTEXTVAR¶
The default value is
True
. If Python isconfigured using the --without-decimal-contextvar option
, the C version uses a thread-local rather than a coroutine-local context and the value isFalse
. This is slightly faster in some nested context scenarios.Ajouté dans la version 3.8.3.
Modes d'arrondi¶
- decimal.ROUND_CEILING¶
Round towards
Infinity
.
- 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 have been 0 or 5; otherwise round towards zero.
Signaux¶
Signals represent conditions that arise during computation. Each corresponds to one context flag and one context trap enabler.
The context flag is set whenever the condition is encountered. After the computation, flags may be checked for informational purposes (for instance, to determine whether a computation was exact). After checking the flags, be sure to clear all flags before starting the next computation.
If the context's trap enabler is set for the signal, then the condition causes a
Python exception to be raised. For example, if the DivisionByZero
trap
is set, then a DivisionByZero
exception is raised upon encountering the
condition.
- class decimal.Clamped¶
Altered an exponent to fit representation constraints.
Typically, clamping occurs when an exponent falls outside the context's
Emin
andEmax
limits. If possible, the exponent is reduced to fit by adding zeros to the coefficient.
- class decimal.DecimalException¶
Base class for other signals and a subclass of
ArithmeticError
.
- class decimal.DivisionByZero¶
Signals the division of a non-infinite number by zero.
Can occur with division, modulo division, or when raising a number to a negative power. If this signal is not trapped, returns
Infinity
or-Infinity
with the sign determined by the inputs to the calculation.
- class decimal.Inexact¶
Indicates that rounding occurred and the result is not exact.
Signals when non-zero digits were discarded during rounding. The rounded result is returned. The signal flag or trap is used to detect when results are inexact.
- class decimal.InvalidOperation¶
An invalid operation was performed.
Indicates that an operation was requested that does not make sense. If not trapped, returns
NaN
. Possible causes include:Infinity - Infinity 0 * Infinity Infinity / Infinity x % 0 Infinity % x sqrt(-x) and x > 0 0 ** 0 x ** (non-integer) x ** Infinity
- class decimal.Overflow¶
Débordement numérique.
Indicates the exponent is larger than
Context.Emax
after rounding has occurred. If not trapped, the result depends on the rounding mode, either pulling inward to the largest representable finite number or rounding outward toInfinity
. In either case,Inexact
andRounded
are also signaled.
- class decimal.Rounded¶
Rounding occurred though possibly no information was lost.
Signaled whenever rounding discards digits; even if those digits are zero (such as rounding
5.00
to5.0
). If not trapped, returns the result unchanged. This signal is used to detect loss of significant digits.
- class decimal.Subnormal¶
Exponent was lower than
Emin
prior to rounding.Occurs when an operation result is subnormal (the exponent is too small). If not trapped, returns the result unchanged.
- class decimal.Underflow¶
Numerical underflow with result rounded to zero.
Occurs when a subnormal result is pushed to zero by rounding.
Inexact
andSubnormal
are also signaled.
- class decimal.FloatOperation¶
Enable stricter semantics for mixing floats and Decimals.
If the signal is not trapped (default), mixing floats and Decimals is permitted in the
Decimal
constructor,create_decimal()
and all comparison operators. Both conversion and comparisons are exact. Any occurrence of a mixed operation is silently recorded by settingFloatOperation
in the context flags. Explicit conversions withfrom_float()
orcreate_decimal_from_float()
do not set the flag.Otherwise (the signal is trapped), only equality comparisons and explicit conversions are silent. All other mixed operations raise
FloatOperation
.
The following table summarizes the hierarchy of signals:
exceptions.ArithmeticError(exceptions.Exception)
DecimalException
Clamped
DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
Inexact
Overflow(Inexact, Rounded)
Underflow(Inexact, Rounded, Subnormal)
InvalidOperation
Rounded
Subnormal
FloatOperation(DecimalException, exceptions.TypeError)
Floating-Point Notes¶
Mitigating round-off error with increased precision¶
The use of decimal floating point eliminates decimal representation error
(making it possible to represent 0.1
exactly); however, some operations
can still incur round-off error when non-zero digits exceed the fixed precision.
The effects of round-off error can be amplified by the addition or subtraction of nearly offsetting quantities resulting in loss of significance. Knuth provides two instructive examples where rounded floating-point arithmetic with insufficient precision causes the breakdown of the associative and distributive properties of addition:
# Examples from Seminumerical Algorithms, Section 4.2.2.
>>> from decimal import Decimal, getcontext
>>> getcontext().prec = 8
>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('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')
The decimal
module makes it possible to restore the identities by
expanding the precision sufficiently to avoid loss of significance:
>>> getcontext().prec = 20
>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('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')
Special values¶
The number system for the decimal
module provides special values
including NaN
, sNaN
, -Infinity
, Infinity
,
and two zeros, +0
and -0
.
Infinities can be constructed directly with: Decimal('Infinity')
. Also,
they can arise from dividing by zero when the DivisionByZero
signal is
not trapped. Likewise, when the Overflow
signal is not trapped, infinity
can result from rounding beyond the limits of the largest representable number.
The infinities are signed (affine) and can be used in arithmetic operations where they get treated as very large, indeterminate numbers. For instance, adding a constant to infinity gives another infinite result.
Some operations are indeterminate and return NaN
, or if the
InvalidOperation
signal is trapped, raise an exception. For example,
0/0
returns NaN
which means "not a number". This variety of
NaN
is quiet and, once created, will flow through other computations
always resulting in another NaN
. This behavior can be useful for a
series of computations that occasionally have missing inputs --- it allows the
calculation to proceed while flagging specific results as invalid.
A variant is sNaN
which signals rather than remaining quiet after every
operation. This is a useful return value when an invalid result needs to
interrupt a calculation for special handling.
The behavior of Python's comparison operators can be a little surprising where a
NaN
is involved. A test for equality where one of the operands is a
quiet or signaling NaN
always returns False
(even when doing
Decimal('NaN')==Decimal('NaN')
), while a test for inequality always returns
True
. An attempt to compare two Decimals using any of the <
,
<=
, >
or >=
operators will raise the InvalidOperation
signal
if either operand is a NaN
, and return False
if this signal is
not trapped. Note that the General Decimal Arithmetic specification does not
specify the behavior of direct comparisons; these rules for comparisons
involving a NaN
were taken from the IEEE 854 standard (see Table 3 in
section 5.7). To ensure strict standards-compliance, use the compare()
and compare_signal()
methods instead.
The signed zeros can result from calculations that underflow. They keep the sign that would have resulted if the calculation had been carried out to greater precision. Since their magnitude is zero, both positive and negative zeros are treated as equal and their sign is informational.
In addition to the two signed zeros which are distinct yet equal, there are various representations of zero with differing precisions yet equivalent in value. This takes a bit of getting used to. For an eye accustomed to normalized floating-point representations, it is not immediately obvious that the following calculation returns a value equal to zero:
>>> 1 / Decimal('Infinity')
Decimal('0E-1000026')
Working with threads¶
The getcontext()
function accesses a different Context
object for
each thread. Having separate thread contexts means that threads may make
changes (such as getcontext().prec=10
) without interfering with other threads.
Likewise, the setcontext()
function automatically assigns its target to
the current thread.
If setcontext()
has not been called before getcontext()
, then
getcontext()
will automatically create a new context for use in the
current thread.
The new context is copied from a prototype context called DefaultContext. To
control the defaults so that each thread will use the same values throughout the
application, directly modify the DefaultContext object. This should be done
before any threads are started so that there won't be a race condition between
threads calling getcontext()
. For example:
# Set applicationwide defaults for all threads about to be launched
DefaultContext.prec = 12
DefaultContext.rounding = ROUND_DOWN
DefaultContext.traps = ExtendedContext.traps.copy()
DefaultContext.traps[InvalidOperation] = 1
setcontext(DefaultContext)
# Afterwards, the threads can be started
t1.start()
t2.start()
t3.start()
. . .
Cas pratiques¶
Here are a few recipes that serve as utility functions and that demonstrate ways
to work with the Decimal
class:
def moneyfmt(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.pop
if sign:
build(trailneg)
for i in range(places):
build(next() if digits else '0')
if places:
build(dp)
if not digits:
build('0')
i = 0
while digits:
build(next())
i += 1
if i == 3 and digits:
i = 0
build(sep)
build(curr)
build(neg if sign else pos)
return ''.join(reversed(result))
def pi():
"""Compute Pi to the current precision.
>>> print(pi())
3.141592653589793238462643383
"""
getcontext().prec += 2 # extra digits for intermediate steps
three = Decimal(3) # substitute "three=3.0" for regular floats
lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
while s != lasts:
lasts = s
n, na = n+na, na+8
d, da = d+da, da+32
t = (t * n) / d
s += t
getcontext().prec -= 2
return +s # unary plus applies the new precision
def exp(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 += 2
i, lasts, s, fact, num = 0, 0, 1, 1, 1
while s != lasts:
lasts = s
i += 1
fact *= i
num *= x
s += num / fact
getcontext().prec -= 2
return +s
def cos(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 += 2
i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
while s != lasts:
lasts = s
i += 2
fact *= i * (i-1)
num *= x * x
sign *= -1
s += num / fact * sign
getcontext().prec -= 2
return +s
def sin(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 += 2
i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
while s != lasts:
lasts = s
i += 2
fact *= i * (i-1)
num *= x * x
sign *= -1
s += num / fact * sign
getcontext().prec -= 2
return +s
FAQ decimal¶
Q. C'est fastidieux de taper decimal.Decimal('1234.5')
. Y a-t-il un moyen de réduire la frappe quand on utilise l'interpréteur interactif ?
R. Certains utilisateurs abrègent le constructeur en une seule lettre :
>>> 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 many places and need to be rounded. Others are not supposed to have excess digits and need to be validated. What methods should be used?
A. The quantize()
method rounds to a fixed number of decimal places. If
the Inexact
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. Une fois que mes entrées sont à deux décimales valides, comment maintenir cet invariant dans l'application ?
R. Certaines opérations comme l'addition, la soustraction et la multiplication par un entier préservent automatiquement la virgule fixe. D'autres opérations, comme la division et la multiplication par des non-entiers, changent le nombre de décimales et doivent être suivies d'une étape quantize()
:
>>> a = Decimal('102.72') # Initial fixed-point values
>>> b = Decimal('3.17')
>>> a + b # Addition preserves fixed-point
Decimal('105.89')
>>> a - b
Decimal('99.55')
>>> a * 42 # So does integer multiplication
Decimal('4314.24')
>>> (a * b).quantize(TWOPLACES) # Must quantize non-integer multiplication
Decimal('325.62')
>>> (b / a).quantize(TWOPLACES) # And quantize division
Decimal('0.03')
Lors du développement d'applications en virgule fixe, il est pratique de définir des fonctions pour gérer cette étape de quantification par quantize()
:
>>> def mul(x, y, fp=TWOPLACES):
... return (x * y).quantize(fp)
...
>>> def div(x, y, fp=TWOPLACES):
... return (x / y).quantize(fp)
>>> mul(a, b) # Automatically preserve fixed-point
Decimal('325.62')
>>> div(b, a)
Decimal('0.03')
Q. There are many ways to express the same value. The numbers 200
,
200.000
, 2E2
, and .02E+4
all have the same value at
various precisions. Is there a way to transform them to a single recognizable
canonical value?
A. The normalize()
method maps all equivalent values to a single
representative:
>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
>>> [v.normalize() for v in values]
[Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]
Q. When does rounding occur in a computation?
A. It occurs after the computation. The philosophy of the decimal specification is that numbers are considered exact and are created independent of the current context. They can even have greater precision than current context. Computations process with those exact inputs and then rounding (or other context operations) is applied to the result of the computation:
>>> getcontext().prec = 5
>>> pi = Decimal('3.1415926535') # More than 5 digits
>>> pi # All digits are retained
Decimal('3.1415926535')
>>> pi + 0 # Rounded after an addition
Decimal('3.1416')
>>> pi - Decimal('0.00005') # Subtract unrounded numbers, then round
Decimal('3.1415')
>>> pi + 0 - Decimal('0.00005'). # Intermediate values are rounded
Decimal('3.1416')
Q. Some decimal values always print with exponential notation. Is there a way to get a non-exponential representation?
A. For some values, exponential notation is the only way to express the number
of significant places in the coefficient. For example, expressing
5.0E+3
as 5000
keeps the value constant but cannot show the
original's two-place significance.
If an application does not care about tracking significance, it is easy to remove the exponent and trailing zeroes, losing significance, but keeping the value unchanged:
>>> def remove_exponent(d):
... return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()
>>> remove_exponent(Decimal('5E+3'))
Decimal('5000')
Q. Is there a way to convert a regular float to a Decimal
?
A. Yes, any binary floating-point number can be exactly expressed as a Decimal though an exact conversion may take more precision than intuition would suggest:
>>> Decimal(math.pi)
Decimal('3.141592653589793115997963468544185161590576171875')
Q. Within a complex calculation, how can I make sure that I haven't gotten a spurious result because of insufficient precision or rounding anomalies.
A. The decimal module makes it easy to test results. A best practice is to re-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 but not to the inputs. Is there anything to watch out for when mixing values of different precisions?
A. Yes. The principle is that all values are considered to be exact and so is the arithmetic on those values. Only the results are rounded. The advantage for inputs is that "what you type is what you get". A disadvantage is that the results 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 inputs using the unary plus operation:
>>> getcontext().prec = 3
>>> +Decimal('1.23456789') # unary plus triggers rounding
Decimal('1.23')
Alternatively, inputs can be rounded upon creation using the
Context.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 of
the decimal module integrate the high speed libmpdec library for
arbitrary precision correctly rounded decimal floating-point arithmetic [1].
libmpdec
uses Karatsuba multiplication
for medium-sized numbers and the Number Theoretic Transform
for very large numbers.
The context must be adapted for exact arbitrary precision arithmetic. Emin
and Emax
should always be set to the maximum values, clamp
should always be 0 (the default). Setting prec
requires some care.
The easiest approach for trying out bignum arithmetic is to use the maximum
value for prec
as well [2]:
>>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))
>>> x = Decimal(2) ** 256
>>> x / 128
Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')
For inexact results, MAX_PREC
is far too large on 64-bit platforms and
the available memory will be insufficient:
>>> Decimal(1) / 3
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
MemoryError
On systems with overallocation (e.g. Linux), a more sophisticated approach is to
adjust prec
to the amount of available RAM. Suppose that you have 8GB of
RAM and expect 10 simultaneous operands using a maximum of 500MB each:
>>> import sys
>>>
>>> # 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 + 2
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
decimal.Inexact: [<class 'decimal.Inexact'>]
In general (and especially on systems without overallocation), it is recommended
to estimate even tighter bounds and set the Inexact
trap if all calculations
are expected to be exact.