decimal – арифметика с фиксированной и плавающей запятой¶decimal – Decimal fixed point and floating point arithmetic

Быстрый старт¶Quick-start Tutorial

Обычно для работы с десятичными числами модуль импортируют, просматривают текущий контекст с помощью getcontext() и, при необходимости, устанавливают новые значения точности, округления или включённых ловушек:

>>> from decimal import *
>>> getcontext()
Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
        capitals=1, flags=[], traps=[Overflow, DivisionByZero,
        InvalidOperation])

>>> getcontext().prec = 7       # Установить новую точность

Экземпляры Decimal можно создавать из целых чисел, строк или кортежей. Чтобы создать Decimal из float, сначала преобразуйте его в строку. Это служит явным напоминанием о деталях преобразования (включая ошибку представления). Десятичные числа включают специальные значения, такие как NaN, что означает «Не число», положительную и отрицательную Infinity, а также -0.

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

Значимость нового Decimal определяется исключительно количеством введённых цифр. Точность контекста и округление вступают в силу только во время арифметических операций.

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

Десятичные числа хорошо взаимодействуют с остальной частью Python. Вот небольшой пример разнообразия десятичной арифметики с плавающей точкой:

>>> 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.3400000000000001
>>> round(a, 1)     # round() сначала преобразует в двоичное число с плавающей точкой.
1.3
>>> int(a)
1
>>> a * 5
Decimal('6.70')
>>> a * b
Decimal('2.5058')
>>> c % a
Decimal('0.77')

Также некоторые математические функции доступны для 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')

Метод quantize() округляет число до заданного показателя степени. Этот метод полезен для денежных приложений, которые часто округляют результаты до фиксированного количества знаков:

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

Как показано выше, функция getcontext() обращается к текущему контексту и позволяет изменять настройки. Такой подход удовлетворяет потребности большинства приложений.

Для более сложной работы может быть полезно создавать альтернативные контексты с помощью конструктора Context(). Чтобы сделать альтернативный контекст активным, используйте функцию setcontext().

In accordance with the standard, the Decimal module provides two ready to use standard contexts, BasicContext and ExtendedContext. The former is especially useful for debugging because many of the traps are enabled:

>>> 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=-999999999, Emax=999999999,
        capitals=1, 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

Контексты также имеют флаги сигналов для отслеживания исключительных ситуаций, возникающих во время вычислений. Флаги остаются установленными до явного сброса, поэтому лучше всего сбрасывать флаги перед каждой серией отслеживаемых вычислений с помощью метода clear_flags().

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

Запись flags показывает, что рациональное приближение к Pi было округлено (цифры за пределами точности контекста были отброшены) и что результат неточен (некоторые отброшенные цифры были ненулевыми).

Отдельные ловушки устанавливаются с помощью словаря в поле traps контекста:

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

Большинство программ настраивают текущий контекст только один раз, в начале программы. И во многих приложениях данные преобразуются в Decimal с помощью одного приведения в цикле. После установки контекста и создания десятичных чисел основная часть программы манипулирует данными точно так же, как и с другими числовыми типами Python.

Объекты Decimal¶Decimal objects

class decimal.Decimal([value[, context]])¶

Создаёт новый объект Decimal на основе value.

value может быть целым числом, строкой, кортежем или другим объектом Decimal. Если value не указано, возвращается Decimal('0'). Если value является строкой, она должна соответствовать синтаксису десятичной числовой строки после удаления начальных и конечных пробелов:

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

Если value является tuple, он должен иметь три компонента: знак (0 для положительного или 1 для отрицательного), tuple цифр и целочисленный показатель степени. Например, Decimal((0, (1, 4, 1, 4), -3)) возвращает Decimal('1.414').

Точность context не влияет на количество сохраняемых цифр. Оно определяется исключительно количеством цифр в value. Например, Decimal('3.00000') сохраняет все пять нулей, даже если точность контекста равна только трём.

Назначение аргумента context – определить, что делать, если value является некорректной строкой. Если контекст перехватывает сигнал InvalidOperation, вызывается исключение; в противном случае конструктор возвращает новый Decimal со значением NaN.

После создания объекты Decimal являются неизменяемыми.

Объекты Decimal с плавающей запятой имеют много общих свойств с другими встроенными числовыми типами, такими как float и int. К ним применимы все обычные математические операции и специальные методы. Кроме того, объекты Decimal можно копировать, сериализовать, выводить на печать, использовать в качестве ключей словаря, элементов множества, сравнивать, сортировать и приводить к другому типу (например, float или long).

В дополнение к стандартным числовым свойствам десятичные объекты с плавающей точкой также имеют ряд специализированных методов:

adjusted()¶

Возвращает скорректированный показатель степени после удаления крайних правых цифр коэффициента, пока не останется только старшая цифра: Decimal('321e+5').adjusted() возвращает семь. Используется для определения положения самой значащей цифры относительно десятичной точки.

as_tuple()¶

Возвращает представление числа в виде именованного кортежа: DecimalTuple(sign, digits, exponent).

canonical()¶

Возвращает каноническую кодировку аргумента. В настоящее время кодировка экземпляра Decimal всегда канонична, поэтому эта операция возвращает свой аргумент без изменений.

compare(other[, context])¶

Сравнивает значения двух экземпляров Decimal. compare() возвращает экземпляр Decimal, и если любой из операндов является NaN, то результатом будет 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])¶

Эта операция идентична методу compare(), за исключением того, что все NaN сигнализируют. То есть, если ни один операнд не является сигнальным NaN, то любой тихий NaN обрабатывается так, как если бы он был сигнальным NaN.

compare_total(other)¶

Сравнивает два операнда, используя их абстрактное представление, а не числовое значение. Аналогично методу compare(), но результат даёт полное упорядочение экземпляров Decimal. Два экземпляра Decimal с одинаковым числовым значением, но разными представлениями сравниваются как неравные в этом упорядочении:

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

Тихие и сигнальные NaN также включены в полное упорядочение. Результат этой функции равен Decimal('0'), если оба операнда имеют одинаковое представление, Decimal('-1'), если первый операнд находится ниже в полном порядке, чем второй, и Decimal('1'), если первый операнд находится выше в полном порядке, чем второй операнд. Подробнее о полном порядке см. в спецификации.

compare_total_mag(other)¶

Сравнивает два операнда, используя их абстрактное представление, а не их значение, как в compare_total(), но игнорируя знак каждого операнда. x.compare_total_mag(y) эквивалентно x.copy_abs().compare_total(y.copy_abs()).

conjugate()¶

Просто возвращает self; этот метод существует только для соответствия спецификации Decimal.

copy_abs()¶

Возвращает абсолютное значение аргумента. Эта операция не зависит от контекста и является тихой: флаги не изменяются и округление не выполняется.

copy_negate()¶

Возвращает отрицание аргумента. Эта операция не зависит от контекста и является тихой: флаги не изменяются и округление не выполняется.

copy_sign(other)¶

Возвращает копию первого операнда со знаком, установленным таким же, как знак второго операнда. Например:

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

Эта операция не зависит от контекста и является тихой: никакие флаги не изменяются и округление не выполняется.

exp([context])¶

Возвращает значение (натуральной) показательной функции e**x для заданного числа. Результат правильно округляется с использованием режима округления ROUND_HALF_EVEN.

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

fma(other, third[, context])¶

Совмещённое умножение-сложение. Возвращает self*other+third без округления промежуточного произведения self*other.

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

is_canonical()¶

Возвращает True, если аргумент каноничен, и False в противном случае. В настоящее время экземпляр Decimal всегда каноничен, поэтому эта операция всегда возвращает True.

is_finite()¶

Возвращает True, если аргумент является конечным числом, и False, если аргумент является бесконечностью или NaN.

is_infinite()¶

Возвращает True, если аргумент – положительная или отрицательная бесконечность, и False в противном случае.

is_nan()¶

Возвращает True, если аргумент – тихий или сигнализирующий NaN, и False в противном случае.

is_normal()¶

Возвращает True, если аргумент – нормальное конечное число. Возвращает False, если аргумент – ноль, субнормальное число, бесконечность или NaN.

is_qnan()¶

Возвращает True, если аргумент – тихий NaN, и False в противном случае.

is_signed()¶

Возвращает True, если аргумент имеет отрицательный знак, и False в противном случае. Обратите внимание, что нули и NaN могут иметь знак.

is_snan()¶

Возвращает True, если аргумент – сигнализирующий NaN, и False в противном случае.

is_subnormal()¶

Возвращает True, если аргумент субнормальный, и False в противном случае.

is_zero()¶

Возвращает True, если аргумент – (положительный или отрицательный) ноль, и False в противном случае.

ln([context])¶

Возвращает натуральный (по основанию e) логарифм операнда. Результат правильно округляется с использованием режима округления ROUND_HALF_EVEN.

log10([context])¶

Возвращает десятичный логарифм операнда. Результат корректно округляется с использованием режима округления ROUND_HALF_EVEN.

logb([context])¶

Для ненулевого числа возвращает скорректированный порядок операнда в виде экземпляра Decimal. Если операнд – ноль, то возвращается Decimal('-Infinity') и поднимается флаг DivisionByZero. Если операнд – бесконечность, то возвращается Decimal('Infinity').

logical_and(other[, context])¶

logical_and() – логическая операция, принимающая два логических операнда (см. Логические операнды). Результатом является поразрядное И двух операндов.

logical_invert(other[, context])¶

logical_invert() – логическая операция. Аргумент должен быть логическим операндом (см. Логические операнды). Результат представляет собой поразрядную инверсию операнда.

logical_or(other[, context])¶

logical_or() – логическая операция, принимающая два логических операнда (см. Логические операнды). Результатом является поразрядное ИЛИ двух операндов.

logical_xor(other[, context])¶

logical_xor() – логическая операция, принимающая два логических операнда (см. Логические операнды). Результатом является поразрядное исключающее ИЛИ двух операндов.

max(other[, context])¶

Подобно max(self, other), за исключением того, что правило округления контекста применяется перед возвратом, и что значения NaN либо сигнализируются, либо игнорируются (в зависимости от контекста и от того, являются ли они сигнализирующими или тихими).

max_mag(other[, context])¶

Похож на метод max(), но сравнение выполняется с использованием абсолютных значений операндов.

min(other[, context])¶

Как и min(self, other), но с одним отличием: правило округления контекста применяется перед возвратом результата, а значения NaN либо сигнализируются, либо игнорируются (в зависимости от контекста и от того, являются ли они сигнальными или тихими).

min_mag(other[, context])¶

Похож на метод min(), но сравнение выполняется с использованием абсолютных значений операндов.

next_minus([context])¶

Возвращает наибольшее число, представимое в заданном контексте (или в контексте текущего потока, если контекст не задан), которое меньше заданного операнда.

next_plus([context])¶

Возвращает наименьшее число, представимое в заданном контексте (или в контексте текущего потока, если контекст не задан), которое больше заданного операнда.

next_toward(other[, context])¶

Если два операнда не равны, возвращает число, ближайшее к первому операнду в направлении второго операнда. Если оба операнда численно равны, возвращает копию первого операнда со знаком, установленным таким же, как знак второго операнда.

normalize([context])¶

Нормализует число, удаляя крайние правые конечные нули и преобразуя любой результат, равный Decimal('0'), в Decimal('0e0'). Используется для получения канонических значений членов класса эквивалентности. Например, Decimal('32.100') и Decimal('0.321000e+2') нормализуются до эквивалентного значения Decimal('32.1').

number_class([context])¶

Возвращает строку, описывающую класс операнда. Возвращаемое значение является одной из следующих десяти строк.

• "-Infinity" – указывает, что операнд является отрицательной бесконечностью.
• "-Normal" – указывает, что операнд является отрицательным нормальным числом.
• "-Subnormal" – указывает, что операнд отрицателен и является субнормальным.
• "-Zero" – указывает, что операнд является отрицательным нулём.
• "+Zero" – указывает, что операнд является положительным нулём.
• "+Subnormal" – указывает, что операнд положителен и является субнормальным.
• "+Normal" – указывает, что операнд является положительным нормальным числом.
• "+Infinity" – указывает, что операнд является положительной бесконечностью.
• "NaN" – указывает, что операнд является тихим NaN (не числом).
• "sNaN" – указывает, что операнд является сигнальным NaN.

quantize(exp[, rounding[, context[, watchexp]]])¶

Возвращает значение, равное первому операнду после округления и имеющее экспоненту второго операнда.

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

В отличие от других операций, если длина коэффициента после операции quantize превышает точность, то сигнализируется InvalidOperation. Это гарантирует, что при отсутствии ошибки квантованный порядок всегда равен порядку правого операнда.

Также, в отличие от других операций, quantize никогда не сигнализирует Underflow, даже если результат субнормален и неточен.

Если порядок второго операнда больше порядка первого, то может потребоваться округление. В этом случае режим округления определяется аргументом rounding, если он задан, иначе – аргументом context; если не задан ни один аргумент, используется режим округления контекста текущего потока.

Если watchexp установлен (по умолчанию), то ошибка возвращается всякий раз, когда результирующий порядок больше Emax или меньше Etiny.

radix()¶

Возвращает Decimal(10) – основание системы счисления (базу), в которой класс Decimal выполняет все свои арифметические операции. Включён для совместимости со спецификацией.

remainder_near(other[, context])¶

Вычисляет модуль как положительное или отрицательное значение в зависимости от того, что ближе к нулю. Например, Decimal(10).remainder_near(6) возвращает Decimal('-2'), что ближе к нулю, чем Decimal('4').

Если оба одинаково близки, выбранное значение будет иметь тот же знак, что и self.

rotate(other[, context])¶

Возвращает результат вращения цифр первого операнда на величину, заданную вторым операндом. Второй операнд должен быть целым числом в диапазоне от -precision до precision. Абсолютное значение второго операнда задаёт количество позиций для вращения. Если второй операнд положителен, вращение выполняется влево; в противном случае вращение выполняется вправо. Коэффициент первого операнда при необходимости дополняется слева нулями до длины precision. Знак и экспонента первого операнда не изменяются.

same_quantum(other[, context])¶

Проверяет, имеют ли self и other одинаковую экспоненту или оба являются NaN.

scaleb(other[, context])¶

Возвращает первый операнд с экспонентой, скорректированной на второй. Эквивалентно умножению первого операнда на 10**other. Второй операнд должен быть целым числом.

shift(other[, context])¶

Возвращает результат сдвига цифр первого операнда на величину, заданную вторым операндом. Второй операнд должен быть целым числом в диапазоне от -precision до precision. Абсолютное значение второго операнда задаёт количество позиций для сдвига. Если второй операнд положителен, сдвиг выполняется влево; в противном случае сдвиг выполняется вправо. Вдвигаемые в коэффициент цифры являются нулями. Знак и экспонента первого операнда не изменяются.

sqrt([context])¶

Возвращает квадратный корень аргумента с полной точностью.

to_eng_string([context])¶

Преобразует в строку инженерного типа.

В инженерной нотации показатель степени кратен 3, поэтому слева от десятичной запятой может быть до 3 цифр. Например, преобразует Decimal('123E+1') в Decimal('1.23E+3')

to_integral([rounding[, context]])¶

Идентичен методу to_integral_value(). Имя to_integral сохранено для совместимости со старыми версиями.

to_integral_exact([rounding[, context]])¶

Округляет до ближайшего целого, сигнализируя Inexact или Rounded в зависимости от того, произошло ли округление. Режим округления определяется параметром rounding, если он задан, иначе – заданным context. Если ни один параметр не задан, используется режим округления текущего контекста.

to_integral_value([rounding[, context]])¶

Округляет до ближайшего целого без сигнализации Inexact или Rounded. Если задан, применяет rounding; в противном случае использует метод округления из предоставленного context или текущего контекста.

Объекты контекста¶Context objects

Контексты – это среды для арифметических операций. Они управляют точностью, задают правила округления, определяют, какие сигналы обрабатываются как исключения, и ограничивают диапазон для экспонент.

Каждый поток имеет свой собственный текущий контекст, доступ к которому осуществляется или изменяется с помощью функций getcontext() и setcontext().

decimal.getcontext()¶

Возвращает текущий контекст активного потока.

decimal.setcontext(c)¶

Устанавливает текущий контекст активного потока в c.

Также можно использовать оператор with и функцию localcontext() для временного изменения активного контекста.

decimal.localcontext([c])¶

Возвращает менеджер контекста, который устанавливает текущий контекст для активного потока в копию c при входе в оператор with и восстанавливает предыдущий контекст при выходе из оператора with. Если контекст не указан, используется копия текущего контекста.

Например, следующий код устанавливает текущую точность десятичных чисел в 42 знака, выполняет вычисление и затем автоматически восстанавливает предыдущий контекст:

from decimal import localcontext

with localcontext() as ctx:
    ctx.prec = 42   # Выполнить вычисление с высокой точностью
    s = calculate_something()
s = +s  # Округлить конечный результат до стандартной точности

Новые контексты также можно создавать с помощью конструктора Context, описанного ниже. Кроме того, модуль предоставляет три готовых контекста:

class decimal.BasicContext¶

Это стандартный контекст, определённый в спецификации General Decimal Arithmetic. Точность установлена в девять. Округление установлено в ROUND_HALF_UP. Все флаги сброшены. Все ловушки включены (обрабатываются как исключения), за исключением Inexact, Rounded и Subnormal.

Поскольку многие ловушки включены, этот контекст полезен для отладки.

class decimal.ExtendedContext¶

Это стандартный контекст, определённый в спецификации General Decimal Arithmetic. Точность установлена в девять. Округление установлено в ROUND_HALF_EVEN. Все флаги сброшены. Ловушки не включены (так что исключения не возбуждаются при вычислениях).

Поскольку ловушки отключены, этот контекст полезен для приложений, которые предпочитают получать значение NaN или Infinity вместо вызова исключений. Это позволяет приложению завершить выполнение при наличии условий, которые в противном случае остановили бы программу.

class decimal.DefaultContext¶

Этот контекст используется конструктором Context как прототип для новых контекстов. Изменение поля (например, точности) приводит к изменению значений по умолчанию для новых контекстов, создаваемых конструктором Context.

Этот контекст наиболее полезен в многопоточных средах. Изменение одного из полей до запуска потоков приводит к установке общесистемных значений по умолчанию. Изменять поля после запуска потоков не рекомендуется, так как это потребовало бы синхронизации потоков для предотвращения состояний гонки.

В однопоточных средах лучше вообще не использовать этот контекст. Вместо этого просто создавайте контексты явно, как описано ниже.

Значения по умолчанию: precision=28, rounding=ROUND_HALF_EVEN, включены ловушки для Overflow, InvalidOperation и DivisionByZero.

В дополнение к трём предоставленным контекстам новые контексты можно создавать с помощью конструктора Context.

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

Создаёт новый контекст. Если поле не указано или равно None, значения по умолчанию копируются из DefaultContext. Если поле flags не указано или равно None, все флаги сбрасываются.

Поле prec – это положительное целое число, которое задаёт точность арифметических операций в контексте.

Параметр rounding может принимать одно из следующих значений:

• ROUND_CEILING (в сторону Infinity),
• ROUND_DOWN (в сторону нуля),
• ROUND_FLOOR (в сторону -Infinity),
• ROUND_HALF_DOWN (к ближайшему, при равенстве – в сторону нуля),
• ROUND_HALF_EVEN (к ближайшему, при равенстве – к ближайшему чётному целому),
• ROUND_HALF_UP (к ближайшему, при равенстве – от нуля), или
• ROUND_UP (от нуля).
• ROUND_05UP (от нуля, если последняя цифра после округления в сторону нуля была бы 0 или 5; в противном случае – к нулю)

Поля traps и flags содержат список сигналов, которые необходимо установить. Как правило, для новых контекстов следует задавать только ловушки (traps), а флаги (flags) оставлять сброшенными.

Поля Emin и Emax – это целые числа, задающие допустимые внешние границы для показателей степени.

Поле capitals может быть равно 0 или 1 (по умолчанию). Если установлено в 1, показатели степени выводятся с заглавной E; в противном случае используется строчная e: Decimal('6.02e+23').

Класс Context определяет несколько методов общего назначения, а также большое количество методов для выполнения арифметических операций непосредственно в заданном контексте. Кроме того, для каждого из описанных выше методов Decimal (за исключением методов adjusted() и as_tuple()) существует соответствующий метод Context. Например, C.exp(x) эквивалентно x.exp(context=C).

clear_flags()¶

Сбрасывает все флаги в 0.

copy()¶

Возвращает копию контекста.

copy_decimal(num)¶

Возвращает копию экземпляра Decimal num.

create_decimal(num)¶

Создаёт новый экземпляр Decimal из num, используя self в качестве контекста. В отличие от конструктора Decimal, при преобразовании применяются точность контекста, метод округления, флаги и ловушки.

Это полезно, поскольку константы часто задаются с большей точностью, чем требуется приложению. Ещё одно преимущество в том, что округление немедленно устраняет нежелательные эффекты от цифр за пределами текущей точности. В следующем примере использование неокруглённых входных данных означает, что добавление нуля к сумме может изменить результат:

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

Этот метод реализует операцию преобразования в число из спецификации IBM. Если аргумент – строка, начальные и конечные пробелы не допускаются.

Etiny()¶

Возвращает значение, равное Emin - prec + 1, которое является минимальным значением показателя степени для субнормальных результатов. В случае антипереполнения (underflow) показатель степени устанавливается равным Etiny.

Etop()¶

Возвращает значение, равное Emax - prec + 1.

Обычный подход к работе с десятичными числами – создавать экземпляры Decimal, а затем применять арифметические операции, которые выполняются в текущем контексте активного потока. Альтернативный подход – использовать методы контекста для вычислений в заданном контексте. Эти методы аналогичны методам класса Decimal и здесь лишь кратко перечислены.

abs(x)¶

Возвращает абсолютное значение x.

add(x, y)¶

Возвращает сумму x и y.

canonical(x)¶

Возвращает тот же объект Decimal x.

compare(x, y)¶

Сравнивает x и y численно.

compare_signal(x, y)¶

Сравнивает значения двух операндов численно.

compare_total(x, y)¶

Сравнивает два операнда по их абстрактному представлению.

compare_total_mag(x, y)¶

Сравнивает два операнда по их абстрактному представлению, игнорируя знак.

copy_abs(x)¶

Возвращает копию x с установленным в 0 знаком.

copy_negate(x)¶

Возвращает копию x с инвертированным знаком.

copy_sign(x, y)¶

Копирует знак из y в x.

divide(x, y)¶

Возвращает x, делённое на y.

divide_int(x, y)¶

Возвращает x, делённое на y, с усечением до целого.

divmod(x, y)¶

Делит два числа и возвращает целую часть результата.

exp(x)¶

Возвращает e ** x.

fma(x, y, z)¶

Возвращает x, умноженное на y, плюс z.

is_canonical(x)¶

Возвращает True, если x – каноническое число; иначе False.

is_finite(x)¶

Возвращает True, если x – конечное число; иначе False.

is_infinite(x)¶

Возвращает True, если x – бесконечность; иначе False.

is_nan(x)¶

Возвращает True, если x – qNaN или sNaN; иначе False.

is_normal(x)¶

Возвращает True, если x – нормальное число; иначе False.

is_qnan(x)¶

Возвращает True, если x – тихий NaN; иначе False.

is_signed(x)¶

Возвращает True, если x – отрицательное число; иначе False.

is_snan(x)¶

Возвращает True, если x – сигнальный NaN; иначе False.

is_subnormal(x)¶

Возвращает True, если x – субнормальное число; иначе возвращает False.

is_zero(x)¶

Возвращает True, если x – ноль; иначе возвращает False.

ln(x)¶

Возвращает натуральный (по основанию e) логарифм x.

log10(x)¶

Возвращает десятичный логарифм x.

logb(x)¶

Возвращает показатель степени величины старшего разряда операнда.

logical_and(x, y)¶

Применяет логическую операцию and к соответствующим цифрам операндов.

logical_invert(x)¶

Инвертирует все цифры в x.

logical_or(x, y)¶

Применяет логическую операцию or к соответствующим цифрам операндов.

logical_xor(x, y)¶

Применяет логическую операцию xor к соответствующим цифрам операндов.

max(x, y)¶

Сравнивает два числа и возвращает наибольшее.

max_mag(x, y)¶

Сравнивает числа по модулю (игнорируя знак).

min(x, y)¶

Сравнивает два числа и возвращает наименьшее.

min_mag(x, y)¶

Сравнивает числа по модулю (игнорируя знак).

minus(x)¶

Минус соответствует унарному префиксному оператору минус в Python.

multiply(x, y)¶

Возвращает произведение x и y.

next_minus(x)¶

Возвращает наибольшее представимое число, меньшее чем x.

next_plus(x)¶

Возвращает наименьшее представимое число, большее чем x.

next_toward(x, y)¶

Возвращает число, ближайшее к x в направлении к y.

normalize(x)¶

Приводит x к простейшей форме.

number_class(x)¶

Возвращает указание на класс x.

plus(x)¶

Plus соответствует унарному префиксному оператору плюс в Python. Эта операция применяет точность и округление контекста, поэтому она не является тождественной операцией.

power(x, y[, modulo])¶

Возвращает x, возведённое в степень y, с приведением по модулю modulo, если он задан.

С двумя аргументами вычисляет x**y. Если x отрицательно, то y должно быть целым. Результат будет неточным, если только y не является целым и результат конечен и может быть точно выражен в цифрах 'precision'. Результат всегда должен быть правильно округлён в соответствии с режимом округления контекста текущего потока.

С тремя аргументами вычисляется (x**y) % modulo. Для формы с тремя аргументами действуют следующие ограничения:

• все три аргумента должны быть целыми
• y должно быть неотрицательным
• по крайней мере одно из x или y должно быть ненулевым
• modulo должно быть ненулевым и содержать не более 'precision' цифр

Результат Context.power(x, y, modulo) идентичен результату, который был бы получен при вычислении (x**y) % modulo с неограниченной точностью, но вычисляется более эффективно. Он всегда точен.

quantize(x, y)¶

Возвращает значение, равное x (с округлением), с экспонентой y.

radix()¶

Просто возвращает 10, так как это Decimal, :)

remainder(x, y)¶

Возвращает остаток от целочисленного деления.

Знак результата, если он не равен нулю, совпадает со знаком исходного делимого.

remainder_near(x, y)¶

Возвращает x - y * n, где n – целое число, ближайшее к точному значению x / y (если результат равен 0, его знак будет знаком x).

rotate(x, y)¶

Возвращает циклически сдвинутую копию x на y раз.

same_quantum(x, y)¶

Возвращает True, если два операнда имеют одинаковую экспоненту.

scaleb(x, y)¶

Возвращает первый операнд после добавления второго значения к его экспоненте.

shift(x, y)¶

Возвращает сдвинутую копию x на y раз.

sqrt(x)¶

Квадратный корень неотрицательного числа с точностью контекста.

subtract(x, y)¶

Возвращает разность x и y.

to_eng_string(x)¶

Преобразует число в строку, используя научную нотацию.

to_integral_exact(x)¶

Округляет до целого.

to_sci_string(x)¶

Преобразует число в строку, используя научную запись.

Сигналы¶Signals

Сигналы представляют условия, возникающие во время вычислений. Каждый соответствует одному флагу контекста и одному включателю ловушки контекста.

Флаг контекста устанавливается при возникновении условия. После вычисления флаги могут быть проверены в информационных целях (например, чтобы определить, было ли вычисление точным). После проверки флагов необходимо очистить все флаги перед началом следующего вычисления.

Если для сигнала включён ловушечный переключатель контекста, то условие вызывает возбуждение исключения Python. Например, если установлена ловушка DivisionByZero, то при возникновении условия возбуждается исключение DivisionByZero.

class decimal.Clamped¶

Изменён показатель степени для соответствия ограничениям представления.

Обычно усечение (clamping) происходит, когда показатель степени выходит за пределы контекста Emin и Emax. Если возможно, показатель уменьшается до допустимого значения путём добавления нулей к коэффициенту.

class decimal.DecimalException¶

Базовый класс для остальных сигналов и подкласс ArithmeticError.

class decimal.DivisionByZero¶

Сигнализирует о делении небесконечного числа на ноль.

Может возникнуть при делении, делении по модулю или возведении числа в отрицательную степень. Если эта ловушка не включена, возвращается Infinity или -Infinity, знак определяется входными данными вычисления.

class decimal.Inexact¶

Указывает, что произошло округление и результат не является точным.

Сигнализирует, когда при округлении были отброшены ненулевые цифры. Возвращается округлённый результат. Флаг сигнала или ловушка используется для обнаружения неточных результатов.

class decimal.InvalidOperation¶

Выполнена недопустимая операция.

Указывает на то, что была запрошена бессмысленная операция. Если ловушка не включена, возвращается NaN. Возможные причины включают:

Infinity - Infinity
0 * Infinity
Infinity / Infinity
x % 0
Infinity % x
x._rescale( non-integer )
sqrt(-x) and x > 0
0 ** 0
x ** (non-integer)
x ** Infinity

class decimal.Overflow¶

Числовое переполнение.

Указывает, что показатель степени превышает Emax после округления. Если ловушка не включена, результат зависит от режима округления: либо округление внутрь до наибольшего представимого конечного числа, либо округление наружу до Infinity. В любом случае также сигнализируются Inexact и Rounded.

class decimal.Rounded¶

Произошло округление, хотя, возможно, информация не была потеряна.

Срабатывает при каждом округлении, отбрасывающем цифры, даже если эти цифры нулевые (например, при округлении 5.00 до 5.0). Если не перехвачено, возвращает результат без изменений. Этот сигнал используется для обнаружения потери значащих цифр.

class decimal.Subnormal¶

Exponent was lower than Emin prior to rounding.

Возникает, когда результат операции является субнормальным (экспонента слишком мала). Если не перехвачено, возвращает результат без изменений.

class decimal.Underflow¶

Числовое исчерпание с округлением результата до нуля.

Occurs when a subnormal result is pushed to zero by rounding. Inexact and Subnormal are also signaled.

В следующей таблице приведена иерархия сигналов:

exceptions.ArithmeticError(exceptions.Exception)
    DecimalException
        Clamped
        DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
        Inexact
            Overflow(Inexact, Rounded)
            Underflow(Inexact, Rounded, Subnormal)
        InvalidOperation
        Rounded
        Subnormal

Примечания по числам с плавающей запятой¶Floating Point Notes

# Примеры из Seminumerical Algorithms, раздел 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')

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

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

Работа с потоками¶Working with threads

Функция getcontext() обращается к другому объекту Context для\nкаждого потока. Наличие отдельных контекстов для потоков означает, что потоки могут вносить\nизменения (например, getcontext.prec=10) без помех для других потоков.

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:

# Установить глобальные настройки по умолчанию для всех потоков, которые будут запущены
DefaultContext.prec = 12
DefaultContext.rounding = ROUND_DOWN
DefaultContext.traps = ExtendedContext.traps.copy()
DefaultContext.traps[InvalidOperation] = 1
setcontext(DefaultContext)

# После этого потоки можно запускать
t1.start()
t2.start()
t3.start()
 . . .

Рецепты¶Recipes

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=''):
    """Преобразовать Decimal в строку, отформатированную как денежная сумма.

    places:  обязательное количество знаков после десятичной точки
    curr:    необязательный символ валюты перед знаком (может быть пустым)
    sep:     необязательный разделитель групп (запятая, точка, пробел или пусто)
    dp:      указатель десятичной точки (запятая или точка)
             указывать пустым только при places=0
    pos:     необязательный знак для положительных чисел: '+', пробел или пусто
    neg:     необязательный знак для отрицательных чисел: '-', '(', пробел или пусто
    trailneg:необязательный завершающий знак минуса: '-', ')', пробел или пусто

    >>> 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 знака после запятой --> '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')
    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():
    """Вычислить число Пи с текущей точностью.

    >>> print(pi())
    3.141592653589793238462643383

    """
    getcontext().prec += 2  # дополнительные цифры для промежуточных шагов
    three = Decimal(3)      # подставить "three=3.0" вместо обычных чисел с плавающей точкой
    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               # унарный плюс применяет новую точность

def exp(x):
    """Возвращает e, возведённое в степень x. Тип результата соответствует типу входного значения.

    >>> 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):
    """Возвращает косинус x, измеренного в радианах.

    >>> 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):
    """Возвращает синус угла x, заданного в радианах.

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

Вопросы и ответы по Decimal¶Decimal FAQ

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

Ответ. Некоторые пользователи сокращают конструктор до одной буквы:

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

Вопрос. В приложении с фиксированной запятой с двумя десятичными знаками некоторые входные данные имеют много знаков и нуждаются в округлении. Другие не должны содержать лишних цифр и требуют проверки. Какие методы следует использовать?

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       # то же, что Decimal('0.01')

>>> # Округлить до двух знаков
>>> Decimal('3.214').quantize(TWOPLACES)
Decimal('3.21')

>>> # Проверка, что число не выходит за пределы двух знаков
>>> 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

Вопрос. Получив корректные входные данные с двумя знаками, как поддерживать этот инвариант во всём приложении?

A. Some operations like addition, subtraction, and multiplication by an integer will automatically preserve fixed point. Others operations, like division and non-integer multiplication, will change the number of decimal places and need to be followed-up with a quantize() step:

>>> a = Decimal('102.72')           # Начальные значения чисел с фиксированной точкой
>>> b = Decimal('3.17')
>>> a + b                           # Сложение сохраняет фиксированную точку
Decimal('105.89')
>>> a - b
Decimal('99.55')
>>> a * 42                          # Умножение на целое число – тоже
Decimal('4314.24')
>>> (a * b).quantize(TWOPLACES)     # Результат умножения на нецелое число нужно квантовать
Decimal('325.62')
>>> (b / a).quantize(TWOPLACES)     # И квантовать результат деления
Decimal('0.03')

In developing fixed-point applications, it is convenient to define functions to handle the quantize() step:

>>> 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)                       # Автоматически сохранять фиксированную точку
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')]

Вопрос. Некоторые значения decimal всегда выводятся в экспоненциальной записи. Есть ли способ получить неэкспоненциальное представление?

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.

Если приложению не важно отслеживать значимость, можно легко удалить экспоненту и хвостовые нули, потеряв значимость, но сохранив значение:

>>> 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. Да, все двоичные числа с плавающей запятой могут быть точно представлены как Decimal. Точное преобразование может потребовать большей точности, чем можно предположить интуитивно, поэтому мы перехватываем Inexact, чтобы сигнализировать о необходимости большей точности:

def float_to_decimal(f):
    "Convert a floating point number to a Decimal with no loss of information"
    n, d = f.as_integer_ratio()
    with localcontext() as ctx:
        ctx.traps[Inexact] = True
        while True:
            try:
               return Decimal(n) / Decimal(d)
            except Inexact:
                ctx.prec += 1

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

Q. Почему функция float_to_decimal() не включена в модуль?

A. Ведутся споры о том, стоит ли смешивать двоичные и десятичные числа с плавающей запятой. Кроме того, ее использование требует осторожности, чтобы избежать проблем представления, связанных с двоичной плавающей запятой:

>>> float_to_decimal(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')

Вопрос. В сложном вычислении как я могу убедиться, что не получил ложный результат из-за недостаточной точности или аномалий округления?

Ответ. Модуль decimal упрощает проверку результатов. Рекомендуется перезапускать вычисления с большей точностью и различными режимами округления. Сильно различающиеся результаты указывают на недостаточную точность, проблемы с режимом округления, плохо обусловленные входные данные или численно неустойчивый алгоритм.

Вопрос. Я заметил, что точность контекста применяется к результатам операций, но не к входным данным. Есть ли что-то, на что следует обращать внимание при смешивании значений разной точности?

Ответ. Да. Принцип заключается в том, что все значения считаются точными, как и арифметические операции с ними. Округляются только результаты. Преимущество для входных данных в том, что «что ввёл, то и получил». Недостаток в том, что результаты могут выглядеть странно, если забыть, что входные данные не округлены:

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

Решение – либо увеличить точность, либо принудительно округлить входные данные с помощью унарного плюса:

>>> getcontext().prec = 3
>>> +Decimal('1.23456789')      # Унарный плюс вызывает округление
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')