# `decimal` — Arithmétique décimale en virgule fixe et flottante

Code source : Lib/decimal.py

Le module `decimal` fournit une arithmétique en virgule flottante rapide et produisant des arrondis mathématiquement corrects. Il possède plusieurs avantages par rapport au type `float` :

- 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` ou `1.2` n'ont pas de représentation exacte en base binaire flottante. L'utilisateur final ne s'attend typiquement pas à obtenir `3.3000000000000003` lorsqu'il saisit `1.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 raisons `decimal` 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 que `1.30 + 1.20` égale `2.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` donne `1.56` tandis que `1.30 * 1.20` donne `1.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 module `decimal` 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, une mantisse 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 surveillance. 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 la surveillance, 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

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

Les objets `Decimal` interagissent très bien avec le reste de Python. Voici quelques exemples d'opérations avec des décimaux :

    >>> 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 surveillance activée :

    >>> 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 de la surveillance 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 de `Decimal`. Si value n'est pas fourni, le constructeur renvoie `Decimal('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 ou `1` pour négatif), un `n-uplet` de chiffres et un entier représentant l'exposant. Par exemple, `Decimal((0, (1, 4, 1, 4), -3))` construit l'objet `Decimal('1.414')`.

  Si value est un `float`, la valeur en binaire flottant est convertie exactement à son équivalent décimal. Cette conversion peut parfois nécessiter 53 chiffres significatifs ou plus. Par exemple, `Decimal(float('1.1'))` devient `Decimal('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 la surveillance est activée pour `InvalidOperation`, une exception est levée, sinon le constructeur renvoie un objet `Decimal` de valeur `NaN`.

  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 la surveillance est activée pour `FloatOperation`. Par défaut la surveillance n'est pas activée.

  Modifié dans la version 3.6: les tirets bas sont autorisés pour grouper des chiffres, tout comme pour l'arithmétique en virgule fixe et flottante.

  Les objets `Decimal` partagent beaucoup de propriétés avec les autres types numériques natifs tels que `float` et `int`. Toutes les opérations mathématiques et méthodes sont conservées. De même les objets `Decimal` peuvent être copiés, sérialisés via le module `pickle`, affichés, utilisés comme clé de dictionnaire, éléments d'ensembles, comparés, classés et convertis vers un autre type (tel que `float` ou `int`).

  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'Euclide `x == (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 des `float` ou des objets `fractions.Fraction` lors d'opérations arithmétiques : toute addition entre un `Decimal` et un `float`, par exemple, lève une exception `TypeError`. Cependant, il est possible d'utiliser les opérateurs de comparaison entre instances de `Decimal` 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.

  En plus des propriétés numériques standard, les objets décimaux à virgule flottante ont également un certain nombre de méthodes spécialisées :

  adjusted()

    Renvoie l'exposant ajusté après avoir décalé les chiffres les plus à droite de la mantisse 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'instance `Decimal` 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 et `ValueError` sur les Nan.

  Nouveau dans la version 3.6.

  as_tuple()

    Renvoie une représentation sous la forme d'un n-uplet nommé du nombre `DecimalTuple(sign, digits, exponent)`.

  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 sont surveillés. 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 instances `Decimal`. Deux instances de `Decimal` 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, et `Decimal('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 l'opposé 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'arrondi `ROUND_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` ou `int`.

    Remarquez que `Decimal.from_float(0.1)` est différent de `Decimal('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 est `0x1.999999999999ap-4`. La valeur équivalente en décimal est `0.1000000000000000055511151231257827021181583404541015625`.

    Note

    depuis Python 3.2, une instance `Decimal` peut également être construite directement à partir d'un `float`.

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

    Nouveau dans la version 3.1.

  fma(other, third, context=None)

    Multiplier-ajouter fusionné. Renvoie `self*other+third` sans arrondir le produit intermédiaire `self*other`.

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

  is_canonical()

    Renvoie `True` si l'argument est sous forme canonique et `False` sinon. Actuellement, une instance `Decimal` est toujours canonique, donc cette opération renvoie toujours `True`.

  is_finite()

    Renvoie `True` si l'argument est un nombre fini et `False` si l'argument est un infini ou un NaN.

  is_infinite()

    Renvoie `True` si l'argument est un infini positif ou négatif, `False` sinon.

  is_nan()

    Renvoie `True` si l'argument est un NaN (signalisé ou silencieux), `False` sinon.

  is_normal(context=None)

    Renvoie `True` si l'argument est un nombre fini normal. Renvoie `False` si l'argument est zéro, infini, résultat d'un dépassement par valeur inférieure ou un NaN.

  is_qnan()

    Renvoie `True` si l'argument est un NaN silencieux, `False` sinon.

  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_snan()

    Renvoie `True` si l'argument est un NaN signalisé, `False` sinon.

  is_subnormal(context=None)

    Renvoie `True` si l'argument est le résultat d'un dépassement par valeur inférieure, `False` sinon.

  is_zero()

    Renvoie `True` si l'argument est un zéro (positif ou négatif), `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 alors `Decimal('-Infinity')` est renvoyé et le drapeau `DivisionByZero` est levé. Si l'opérande est un infini alors `Decimal('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 les valeurs `NaN` sont signalées ou ignorées (selon le contexte et suivant qu'elles sont signalisées 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 les valeurs `NaN` sont signalées ou ignorées (selon le contexte et suivant qu'elles sont signalisées 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)

    Utilisé pour produire des valeurs canoniques d'une classe d'équivalence dans le contexte actuel ou dans le contexte spécifié.

    C'est la même sémantique que l'opération unaire plus, sauf que si le résultat final est fini, il est réduit à sa forme la plus simple, avec tous les zéros à droite supprimés et son signe conservé. Autrement dit, tant que la mantisse est différente de zéro et est un multiple de dix, elle est divisée par dix et l'exposant est incrémenté de 1. Sinon (la mantisse est nulle), l'exposant est mis à 0. Dans tous les cas, le signe est inchangé.

    Par exemple, `Decimal('32.100')` et `Decimal('0.321000e+2')` se normalisent tous deux à la valeur équivalente `Decimal('32.1')`.

    Notez que l'arrondi est appliqué avant la réduction à la forme la plus simple.

    Dans les dernières versions de la spécification, cette opération est également connue sous le nom de `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) signalisé.

  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 de la mantisse 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 est 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'argument `context` 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 classe `Decimal` 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 est `self - n * other` où `n` est l'entier le plus proche de la valeur exacte de `self / 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. La mantisse du premier opérande est complétée à 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)

    Convertit 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 en fin de mantisse.

    Par exemple, `Decimal('123E+1')` est converti en `Decimal('1.23E+3')`.

  to_integral(rounding=None, context=None)

    Identique à la méthode `to_integral_value()`. Le nom `to_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` ou `Rounded` selon le cas si l'arrondi se produit. Le mode d'arrondi est déterminé par le paramètre `rounding` s'il est donné, sinon par le `context` 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` ou `Rounded`. Si donné, applique rounding ; sinon, utilise la méthode d'arrondi dans le context fourni ou dans le contexte actuel.

### 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 que `Context` ne prend pas en charge. Lève soit `TypeError` ou `ValueError` 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. Toutes les surveillances sont activées (elles lèvent des exceptions) sauf `Inexact`, `Rounded` et `Subnormal`.

  Étant donné que de nombreuses options de surveillance 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 surveillance 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` ou `Infinity` 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 constructeur `Context`.

  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 pour `Overflow`, `InvalidOperation` et `DivisionByZero`.

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)

  Crée un nouveau contexte. Si un champ n'est pas spécifié ou est `None`, les valeurs par défaut sont copiées à partir du `DefaultContext`. Si le champ flags n'est pas spécifié ou est `None`, tous les indicateurs sont effacés.

  prec est un entier compris dans la plage [`1`, `MAX_PREC`] qui définit la précision des opérations arithmétiques dans le contexte.

  L'option rounding est l'une des constantes répertoriées dans la section Modes d'arrondi.

  Les champs traps et flags répertorient tous les signaux à définir. En général, les nouveaux contextes ne doivent qu'activer des surveillances et laisser les drapeaux baissés.

  Les champs Emin et Emax sont des entiers spécifiant les valeurs limites autorisées pour les exposants. Emin doit être dans [`MIN_EMIN`, `0`], Emax dans la plage [`0`, `MAX_EMAX`].

  Le champ capitals est soit `0` soit `1` (la valeur par défaut). S'il est défini à `1`, les exposants sont imprimés avec un `E` majuscule ; sinon, un `e` minuscule est utilisé : `Decimal('6.02e+23')`.

  Le champ clamp est soit `0` (la valeur par défaut), soit `1`. S'il est défini à `1`, l'exposant `e` d'une instance `Decimal` représentable dans ce contexte est strictement limité à la plage `Emin - prec + 1 <= e <= Emax - prec + 1`. Si clamp est `0` alors une condition plus faible est vraie : l'exposant ajusté de l'instance `Decimal` est au plus `Emax`. Lorsque clamp vaut `1`, un grand nombre normal voit, si possible, son exposant réduit et un nombre correspondant de zéros ajouté à sa mantisse, afin de s'adapter aux contraintes d'exposant ; cela préserve la valeur du nombre mais perd des informations sur les zéros significatifs. Par exemple :

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

  Une valeur clamp de `1` permet la compatibilité avec les formats d'échange décimaux à largeur fixe spécifiés dans la norme IEEE 754.

  La classe `Context` définit plusieurs méthodes à usage général ainsi qu'un grand nombre de méthodes permettant de faire de l'arithmétique directement dans un contexte donné. De plus, pour chacune des méthodes `Decimal` décrites ci-dessus (à l'exception des méthodes `adjusted()` et `as_tuple()`), il existe une méthode `Context` correspondante. Par exemple, pour une instance `Context` `C` et une instance `Decimal` `x`, `C.exp(x)` est équivalent à `x.exp(context=C)`. Chaque méthode `Context` accepte un entier Python (une instance de `int`) partout où une instance Decimal est acceptée.

  clear_flags()

    Réinitialise tous les drapeaux à `0`.

  clear_traps()

    Réinitialise toutes les surveillances à `0`.

    Nouveau dans la version 3.3.

  copy()

    Renvoie une copie du contexte.

  copy_decimal(num)

    Renvoie une copie de l'instance `Decimal` num.

  create_decimal(num)

    Crée une nouvelle instance Decimal à partir de num mais en utilisant self comme contexte. Contrairement au constructeur `Decimal`, la précision du contexte, la méthode d'arrondi, les indicateurs et les surveillances sont appliqués à la conversion.

    C'est utile car les constantes sont souvent données avec une précision supérieure à celle requise par l'application. Un autre avantage est que l’arrondi élimine immédiatement les effets involontaires des chiffres au-delà de la précision actuelle. Dans l'exemple suivant, l'utilisation d'entrées non arrondies signifie que l'ajout de zéro à une somme peut modifier le résultat :

        >>> getcontext().prec = 3
        >>> Decimal('3.4445') + Decimal('1.0023')
        Decimal('4.45')
        >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
        Decimal('4.44')

    Cette méthode implémente l'opération to-number de la spécification IBM. Si l’argument est une chaîne, aucun espace ou trait de soulignement de début ou de fin n’est autorisé.

  create_decimal_from_float(f)

    Crée une nouvelle instance Decimal à partir d'un float f mais en arrondissant en utilisant self comme contexte. Contrairement à la méthode de classe `Decimal.from_float()`, la précision du contexte, la méthode d'arrondi, les indicateurs et les surveillances sont appliqués à la 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

    Nouveau dans la version 3.1.

  Etiny()

    Renvoie une valeur égale à `Emin - prec + 1` qui est la valeur minimale de l'exposant pour les résultats avec dépassement inférieur. Lorsqu'un dépassement inférieur se produit, l'exposant est défini sur `Etiny`.

  Etop()

    Renvoie une valeur égale à `Emax - prec + 1`.

  L'approche habituelle pour travailler avec des décimaux consiste à créer des instances `Decimal`, puis à appliquer des opérations arithmétiques qui ont lieu dans le contexte actuel du fil d'exécution actif. Une approche alternative consiste à utiliser des méthodes contextuelles pour calculer dans un contexte spécifique. Les méthodes sont similaires à celles de la classe `Decimal` et ne sont décrites que brièvement ici.

  abs(x)

    Renvoie la valeur absolue de x.

  add(x, y)

    Renvoie la somme de x et y.

  canonical(x)

    Renvoie l'objet Decimal x lui-même.

  compare(x, y)

    Compare x et y numériquement.

  compare_signal(x, y)

    Compare numériquement les valeurs des deux opérandes.

  compare_total(x, y)

    Compare deux opérandes en utilisant leur représentation abstraite.

  compare_total_mag(x, y)

    Compare deux opérandes en utilisant leur représentation abstraite, en ignorant le signe.

  copy_abs(x)

    Renvoie une copie de x avec le signe à 0 (c.-à-d. positif).

  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)

    Renvoie `True` si x est canonique ; `False` sinon.

  is_finite(x)

    Renvoie `True` si x est fini ; `False` sinon.

  is_infinite(x)

    Renvoie `True` si x est infini et `False` sinon.

  is_nan(x)

    Renvoie `True` si x est un NaN (silencieux ou signalisé), `False` sinon.

  is_normal(x)

    Renvoie `True` si x est un nombre normal ; `False` sinon.

  is_qnan(x)

    Renvoie `True` si x est un NaN silencieux, `False` sinon.

  is_signed(x)

    Renvoie `True` si x est négatif et `False` sinon.

  is_snan(x)

    Renvoie `True` si x est un NaN signalisé, `False` sinon.

  is_subnormal(x)

    Renvoie `True` si x est est inférieur à la valeur minimale représentable ; sinon, renvoie `False`.

  is_zero(x)

    Renvoie `True` si x est un zéro et `False` sinon.

  ln(x)

    Renvoie le logarithme naturel (en base e) de x.

  log10(x)

    Renvoie le logarithme en base 10 de x.

  logb(x)

    Renvoie l'exposant correspondant du chiffre de poids fort de la mantisse de l'opérande.

  logical_and(x, y)

    Applique l'opération logique ET entre les chiffres de chaque opérande.

  logical_invert(x)

    Inverse tous les chiffres de x.

  logical_or(x, y)

    Applique l'opération logique OU entre les chiffres de chaque opérande.

  logical_xor(x, y)

    Applique l'opération logique OU EXCLUSIF entre les chiffres de chaque opérande.

  max(x, y)

    Renvoie le maximum entre les deux valeurs numériques.

  max_mag(x, y)

    Compare les valeurs numériquement en ignorant leur signe.

  min(x, y)

    Compare numériquement deux valeurs et renvoie le minimum.

  min_mag(x, y)

    Compare les valeurs numériquement en ignorant leur signe.

  minus(x)

    Correspond à l’opérateur unaire préfixé « moins » en Python.

  multiply(x, y)

    Renvoie la multiplication de x avec y.

  next_minus(x)

    Renvoie le plus grand nombre représentable inférieur à x.

  next_plus(x)

    Renvoie le plus petit nombre représentable supérieur à x.

  next_toward(x, y)

    Renvoie le nombre le plus proche de x, en direction de y.

  normalize(x)

    Réduit x à sa forme la plus simple.

  number_class(x)

    Renvoie une indication de la classe de x.

  plus(x)

    Correspond à l'opérateur unaire préfixé « plus » en Python. Cette opération applique la précision du contexte et l'arrondi, ce n'est donc pas une opération d'identité.

  power(x, y, modulo=None)

    Renvoie `x` à la puissance `y`, réduit modulo `modulo` si celui-ci est donné.

    Avec deux arguments, calcule `x**y`. Si `x` est négatif alors `y` doit être entier. Le résultat est inexact à moins que `y` soit entier et que le résultat soit fini et puisse être exprimé exactement en `precision` chiffres. Le mode d'arrondi du contexte est utilisé. Les résultats sont toujours correctement arrondis à la manière de Python.

    `Decimal(0) ** Decimal(0)` donne `InvalidOperation` et, si `InvalidOperation` n'est pas surveillé, cela donne `Decimal('NaN')`.

    Modifié dans la version 3.3: le module C calcule `power()` en termes de fonctions `exp()` et `ln()` correctement arrondies. Le résultat est bien défini mais seulement « presque toujours correctement arrondi ».

    Avec trois arguments, calcule `(x**y) % modulo`. Pour la forme à trois arguments, les restrictions suivantes sur les arguments s'appliquent :

    - les trois arguments doivent être entiers ;

    - `y` ne doit pas être négatif ;

    - au moins l'un de `x` ou `y` doit être différent de zéro ;

    - `modulo` doit être différent de zéro et avoir au plus `precision` chiffres.

    La valeur résultant de `Context.power(x, y, modulo)` est égale à la valeur qui serait obtenue en calculant `(x**y) % modulo` avec une précision illimitée, mais est calculée plus efficacement. L'exposant du résultat est zéro, quels que soient les exposants de `x`, `y` et `modulo`. Le résultat est toujours exact.

  quantize(x, y)

    Renvoie une valeur égale à x (arrondie), ayant l'exposant de y.

  radix()

    Renvoie 10 car c'est `Decimal`, :)

  remainder(x, y)

    Renvoie le reste de la division entière.

    Le signe du résultat, s'il est différent de zéro, est le même que celui du dividende initial.

  remainder_near(x, y)

    Renvoie `x - y * n`, où n est l'entier le plus proche de la valeur exacte de `x / y` (si le résultat est 0 alors son signe est le signe de x).

  rotate(x, y)

    Renvoie une copie pivotée de x, y fois.

  same_quantum(x, y)

    Renvoie `True` si les deux opérandes ont le même exposant.

  scaleb(x, y)

    Renvoie le premier opérande après avoir ajouté la deuxième valeur à son exp.

  shift(x, y)

    Renvoie une copie décalée de x, y fois.

  sqrt(x)

    Renvoie la racine carrée d'un nombre non négatif avec la précision donnée par le contexte.

  subtract(x, y)

    Renvoie la différence entre x et y.

  to_eng_string(x)

    Convertit 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 en fin de mantisse.

  to_integral_exact(x)

    Arrondit à un entier.

  to_sci_string(x)

    Convertit un nombre en chaîne en utilisant la notation scientifique.

## Constantes

Les constantes de cette section ne sont pertinentes que pour le module implémenté en C. Elles sont incluses dans la version en Python pur pour raison de compatibilité .

| 32-bit | 64-bit
--- | --- | ---
decimal.MAX_PREC | `425000000` | `999999999999999999`
decimal.MAX_EMAX | `425000000` | `999999999999999999`
decimal.MIN_EMIN | `-425000000` | `-999999999999999999`
decimal.MIN_ETINY | `-849999999` | `-1999999999999999997`

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 is `configured using the --without-decimal-contextvar option`, the C version uses a thread-local rather than a coroutine-local context and the value is `False`. This is slightly faster in some nested context scenarios.

Nouveau 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` and `Emax` 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 to `Infinity`. In either case, `Inexact` and `Rounded` 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` to `5.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` and `Subnormal` 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 setting `FloatOperation` in the context flags. Explicit conversions with `from_float()` or `create_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.

[1]

Nouveau dans la version 3.3.

[2]

Modifié dans la version 3.9: This approach now works for all exact results except for non-integer powers.