Содержание страницы

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

Новое в версии 2.4.

Модуль decimal поддерживает десятичную арифметику с плавающей точкой. Он даёт несколько преимуществ по сравнению с типом данных float:

Decimal «основан на модели с плавающей запятой, разработанной с учетом человеческих потребностей, и имеет первостепенный руководящий принцип – компьютеры должны обеспечивать арифметику, работающую так же, как арифметика, которой люди учатся в школе». – отрывок из спецификации десятичной арифметики.
Десятичные числа можно представить точно. В отличие от них, такие числа, как 1.1 и 2.2, не имеют точного представления в двоичной плавающей арифметике. Конечные пользователи обычно не ожидают, что 1.1 + 2.2 отобразится как 3.3000000000000003, как это происходит с двоичной плавающей точкой.
Точность распространяется и на арифметику. В десятичной арифметике с плавающей запятой 0.1 + 0.1 + 0.1 - 0.3 точно равно нулю. В двоичной арифметике с плавающей запятой результат равен 5.5511151231257827e-017. Хотя он близок к нулю, эти различия препятствуют надёжной проверке на равенство и могут накапливаться. По этой причине десятичная арифметика предпочтительна в бухгалтерских приложениях, где существуют строгие инварианты равенства.
Модуль decimal включает понятие значащих разрядов, так что 1.30 + 1.20 равно 2.50. Замыкающий ноль сохраняется для указания значимости. Это стандартное представление для финансовых приложений. Для умножения «школьный» подход использует все цифры множителей. Например, 1.3 * 1.2 даёт 1.56, а 1.30 * 1.20 даёт 1.5600.
В отличие от аппаратно реализованной двоичной арифметики с плавающей запятой, модуль decimal имеет настраиваемую точность (по умолчанию 28 знаков), которая может быть сколь угодно большой для данной задачи:
```
>>> from decimal import *
>>> getcontext().prec = 6
>>> Decimal(1) / Decimal(7)
Decimal('0.142857')
>>> getcontext().prec = 28
>>> Decimal(1) / Decimal(7)
Decimal('0.1428571428571428571428571429')
```
Как двоичная, так и десятичная арифметика с плавающей запятой реализованы в соответствии с опубликованными стандартами. В то время как встроенный тип float предоставляет лишь скромную часть своих возможностей, модуль decimal предоставляет все необходимые части стандарта. При необходимости программист имеет полный контроль над округлением и обработкой сигналов. Это включает возможность принудительного точного выполнения арифметики с помощью исключений для блокировки любых неточных операций.
Модуль decimal был разработан для поддержки «без каких-либо предпочтений как точной неокруглённой десятичной арифметики (иногда называемой арифметикой с фиксированной запятой), так и округлённой арифметики с плавающей запятой.» – выдержка из спецификации десятичной арифметики.

Дизайн модуля сосредоточен на трёх концепциях: десятичное число, контекст арифметики и сигналы.

Десятичное число неизменяемо. Оно имеет знак, цифры коэффициента и показатель степени. Для сохранения значимости цифры коэффициента не отбрасывают замыкающие нули. Десятичные числа также включают специальные значения, такие как Infinity, -Infinity и NaN. Стандарт также различает -0 и +0.

Контекст арифметики – это окружение, задающее точность, правила округления, ограничения на показатели степени, флаги, указывающие на результаты операций, и активаторы ловушек, которые определяют, обрабатываются ли сигналы как исключения. Варианты округления включают ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_HALF_UP, ROUND_UP и ROUND_05UP.

Сигналы – это группы исключительных ситуаций, возникающих в ходе вычислений. В зависимости от потребностей приложения сигналы можно игнорировать, рассматривать как информацию или обрабатывать как исключения. Сигналы в модуле decimal: Clamped, InvalidOperation, DivisionByZero, Inexact, Rounded, Subnormal, Overflow и Underflow.

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

См. также

Спецификация общей десятичной арифметики IBM, Общая спецификация десятичной арифметики.

9.4.1. Краткое руководство¶Quick-start Tutorial

Обычно работа с десятичными числами начинается с импорта модуля decimal, просмотра текущего контекста с помощью 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 можно создавать из целых чисел, строк, чисел с плавающей точкой или кортежей. Создание из целого числа или числа с плавающей точкой выполняет точное преобразование значения этого целого или числа с плавающей точкой. Десятичные числа включают специальные значения, такие как NaN («не число»), положительная и отрицательная Infinity, а также -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.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 = 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)     # 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().

В соответствии со стандартом модуль decimal предоставляет два готовых к использованию стандартных контекста: BasicContext и ExtendedContext. Первый особенно полезен для отладки, так как многие ловушки в нём включены:

>>> 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=[Rounded, Inexact], 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.

9.4.2. Объекты Decimal¶Decimal objects

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

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

value может быть целым числом, строкой, кортежем, float или другим объектом 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 является строкой Unicode, то в местах, где выше указано digit, также допускаются другие десятичные цифры Unicode. К ним относятся десятичные цифры из различных других алфавитов (например, арабо-индийские и деванагари), а также полноширинные цифры от u'\uff10' до u'\uff19'.

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

Если value – это float, двоичное значение с плавающей точкой без потерь преобразуется в точный десятичный эквивалент. Для такого преобразования часто требуется 53 или более знаков точности. Например, Decimal(float('1.1')) преобразуется в Decimal('1.100000000000000088817841970012523233890533447265625').

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

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

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

Изменено в версии 2.6: при создании экземпляра Decimal из строки допускаются начальные и конечные пробельные символы.

Изменено в версии 2.7: аргумент конструктора теперь может быть экземпляром float.

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

Существуют небольшие различия между арифметикой над объектами Decimal и арифметикой над целыми числами и числами с плавающей запятой. Когда оператор остатка % применяется к объектам Decimal, знак результата совпадает со знаком dividend, а не со знаком делителя:

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

Оператор целочисленного деления // ведёт себя аналогично: возвращает целую часть истинного частного (отсечение к нулю), а не его пол, чтобы сохранить обычное тождество x == (x // y) * y + x % y:

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

Операторы % и // реализуют операции remainder и divide-integer (соответственно), как описано в спецификации.

Объекты Decimal обычно нельзя комбинировать с числами с плавающей точкой в арифметических операциях: например, попытка сложить Decimal и float вызовет TypeError. Из этого правила есть одно исключение: операторы сравнения Python можно использовать для сравнения экземпляра float x с экземпляром Decimal y. Без этого исключения сравнения между экземплярами Decimal и float следовали бы общим правилам сравнения объектов разных типов, описанным в разделе Выражения справочного руководства, что приводило бы к запутанным результатам.

Изменено в версии 2.7: сравнение между экземпляром float x и экземпляром Decimal y теперь возвращает результат на основе значений x и y. В более ранних версиях x < y возвращало одинаковый (произвольный) результат для любого экземпляра Decimal x и любого экземпляра float y.

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

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

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

Изменено в версии 2.6: используется именованный кортеж.

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

Новое в версии 2.6.

compare(other[, context])¶

Сравнивает значения двух экземпляров Decimal. Эта операция ведёт себя так же, как обычный метод сравнения __cmp__(), за исключением того, что 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.

Новое в версии 2.6.

compare_total(other)¶

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

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

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

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

copy_sign(other)¶

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

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

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

Новое в версии 2.6.

exp([context])¶

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

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

Новое в версии 2.6.

from_float(f)¶

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

Примечание: Decimal.from_float(0.1) не то же самое, что Decimal('0.1'). Поскольку 0.1 нельзя точно представить в двоичной арифметике с плавающей точкой, значение хранится как ближайшее представимое значение, равное 0x1.999999999999ap-4. Эквивалентное десятичное значение – это 0.1000000000000000055511151231257827021181583404541015625.

Примечание

Начиная с Python 2.7, экземпляр Decimal можно также создать напрямую из 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')

Новое в версии 2.7.

fma(other, third[, context])¶

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

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

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

is_normal()¶: Возвращает True, если аргумент является нормальным конечным ненулевым числом со скорректированной экспонентой, большей или равной Emin. Возвращает False, если аргумент – ноль, субнормальное число, бесконечность или NaN. Обратите внимание, что термин нормальный используется здесь в ином смысле по сравнению с методом normalize(), который служит для создания канонических значений.

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

is_subnormal()¶: Возвращает True, если аргумент субнормальный, и False в противном случае. Число является субнормальным, если оно ненулевое, конечное и имеет скорректированную экспоненту меньше Emin.

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

log10([context])¶: Возвращает десятичный логарифм операнда. Результат правильно округляется с использованием режима округления ROUND_HALF_EVEN.

Новое в версии 2.6.

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

Новое в версии 2.6.

logical_and(other[, context])¶: logical_and() – логическая операция, которая принимает два логических операнда (см. Логические операнды). Результат – поразрядное and двух операндов.

Новое в версии 2.6.

logical_invert([context])¶: logical_invert() – логическая операция. Результат – поразрядная инверсия операнда.

Новое в версии 2.6.

logical_or(other[, context])¶: logical_or() – логическая операция, которая принимает два логических операнда (см. Логические операнды). Результат – поразрядное or двух операндов.

Новое в версии 2.6.

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

Новое в версии 2.6.

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

max_mag(other[, context])¶: Подобно методу max(), но сравнение выполняется с использованием абсолютных значений операндов.

Новое в версии 2.6.

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

min_mag(other[, context])¶: Подобно методу min(), но сравнение выполняется с использованием абсолютных значений операндов.

Новое в версии 2.6.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

next_toward(other[, context])¶: Если два операнда не равны, возвращает число, ближайшее к первому операнду в направлении второго операнда. Если оба операнда численно равны, возвращает копию первого операнда со знаком, установленным таким же, как знак второго операнда.

Новое в версии 2.6.

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.

Новое в версии 2.6.

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 выполняет все арифметические операции. Включено для совместимости со спецификацией.

Новое в версии 2.6.

remainder_near(other[, context])¶

Возвращает остаток от деления self на other. Отличается от self % other тем, что знак остатка выбирается так, чтобы минимизировать его абсолютное значение. Точнее, возвращаемое значение равно self - n * other, где n – целое число, ближайшее к точному значению self / other, а если два целых числа одинаково близки, выбирается чётное.

Если результат равен нулю, его знак будет знаком 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])¶: Возвращает результат вращения цифр первого операнда на величину, заданную вторым операндом. Второй операнд должен быть целым числом в диапазоне от -precision до precision. Абсолютное значение второго операнда задаёт количество позиций для вращения. Если второй операнд положителен, вращение выполняется влево; в противном случае вращение выполняется вправо. Коэффициент первого операнда при необходимости дополняется слева нулями до длины precision. Знак и экспонента первого операнда не изменяются.

Новое в версии 2.6.

same_quantum(other[, context])¶: Проверяет, имеют ли self и other одинаковую экспоненту или оба равны NaN.

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

Новое в версии 2.6.

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

Новое в версии 2.6.

sqrt([context])¶: Возвращает квадратный корень аргумента с полной точностью.

to_eng_string([context])¶

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

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

Например, это преобразует 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. Если ни один из параметров не передан, используется режим округления текущего контекста.

Новое в версии 2.6.

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

Изменено в версии 2.6: переименовано из to_integral в to_integral_value. Старое имя остаётся действительным для совместимости.

9.4.2.1. Логические операнды¶Logical operands

Методы logical_and(), logical_invert(), logical_or() и logical_xor() ожидают, что их аргументы будут логическими операндами. Логический операнд – это экземпляр Decimal, у которого экспонента и знак равны нулю, а все цифры равны либо 0, либо 1.

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

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

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

decimal.getcontext()¶: Возвращает текущий контекст активного потока.

decimal.setcontext(c)¶: Устанавливает текущий контекст активного потока в c.

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

decimal.localcontext([c])¶

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

Новое в версии 2.5.

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

from decimal import localcontext

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

with localcontext(BasicContext):      # временно использовать BasicContext
    print Decimal(1) / Decimal(7)
    print Decimal(355) / Decimal(113)

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

class decimal.BasicContext¶

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

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

class decimal.ExtendedContext¶

Это стандартный контекст, определённый спецификацией General Decimal Arithmetic Specification. Точность установлена в девять. Округление установлено в 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').

Изменено в версии 2.6: добавлен режим округления ROUND_05UP.

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

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. Если аргумент – строка, начальные и конечные пробелы не допускаются.

create_decimal_from_float(f)¶

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

>>> 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):
    ...
Inexact: None

Новое в версии 2.7.

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 с неограниченной точностью, но вычисляется более эффективно. Показатель степени результата равен нулю, независимо от показателей степени x, y и modulo. Результат всегда точен.

Изменено в версии 2.6: y теперь может быть нецелым в x**y. Более строгие требования для версии с тремя аргументами.

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)¶: Преобразует число в строку, используя научную запись.

9.4.4. Сигналы¶Signals

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

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

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

class decimal.Clamped¶

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

Обычно усечение происходит, когда показатель степени выходит за пределы ограничений контекста 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¶

Экспонента была меньше Emin перед округлением.

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

class decimal.Underflow¶

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

Возникает, когда субнормальный результат округляется до нуля. Также срабатывают сигналы Inexact и Subnormal.

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

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

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

9.4.5.1. Уменьшение ошибки округления за счёт повышенной точности¶Mitigating round-off error with increased precision

Использование десятичной арифметики с плавающей запятой устраняет ошибку десятичного представления (позволяя точно представить 0.1); однако некоторые операции всё ещё могут приводить к ошибке округления, когда ненулевые цифры превышают фиксированную точность.

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

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

Модуль decimal позволяет восстановить эти свойства за счёт достаточного увеличения точности, чтобы избежать потери значимости:

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

9.4.5.2. Специальные значения¶Special values

Система чисел модуля decimal предоставляет особые значения, включая NaN, sNaN, -Infinity, Infinity, а также два нуля: +0 и -0.

Бесконечности можно создать напрямую с помощью Decimal('Infinity'). Также, они могут возникать при делении на ноль, если сигнал DivisionByZero не перехвачен. Аналогично, если не перехвачен сигнал Overflow, бесконечность может получиться при округлении за пределами наибольшего представимого числа.

Бесконечности являются знаковыми (аффинными) и могут использоваться в арифметических операциях, где они трактуются как очень большие неопределённые числа. Например, прибавление константы к бесконечности даёт другой бесконечный результат.

Некоторые операции являются неопределёнными и возвращают NaN, или, если сигнал InvalidOperation перехвачен, возбуждают исключение. Например, 0/0 возвращает NaN, что означает «не число». Этот вид NaN является тихим и, будучи созданным, будет распространяться через другие вычисления, всегда давая в результате NaN. Такое поведение может быть полезно для серии вычислений, в которых иногда отсутствуют входные данные – оно позволяет продолжить вычисления, помечая конкретные результаты как недействительные.

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

Поведение операторов сравнения Python может быть несколько неожиданным, когда NaN участвует в сравнении. Проверка на равенство, где один из операндов является тихим или сигнальным NaN, всегда возвращает False (даже при выполнении Decimal('NaN')==Decimal('NaN')), а проверка на неравенство всегда возвращает True. Попытка сравнить два Decimal с помощью любого из операторов <, <=, > или >= возбуждает сигнал InvalidOperation, если хотя бы один операнд является NaN, и возвращает False, если этот сигнал не перехвачен. Обратите внимание, что спецификация General Decimal Arithmetic не определяет поведение прямых сравнений; эти правила для сравнений, включающих NaN, взяты из стандарта IEEE 854 (см. Таблицу 3 в разделе 5.7). Для обеспечения строгого соответствия стандартам используйте вместо этого методы compare() и compare-signal().

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

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

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

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

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

Аналогично, функция setcontext() автоматически назначает свою цель текущему потоку.

Если setcontext() не был вызван до getcontext(), то getcontext() автоматически создаст новый контекст для использования в текущем потоке.

Новый контекст копируется из прототипа контекста под названием DefaultContext. Чтобы управлять значениями по умолчанию так, чтобы каждый поток использовал одни и те же значения во всём приложении, напрямую измените объект DefaultContext. Это следует сделать до запуска любых потоков, чтобы не возникло состояния гонки между потоками, вызывающими getcontext(). Например:

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

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

9.4.7. Рецепты¶Recipes

Вот несколько рецептов, которые служат вспомогательными функциями и демонстрируют способы работы с классом Decimal:

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

9.4.8. Часто задаваемые вопросы по Decimal¶Decimal FAQ

Вопрос. Вводить decimal.Decimal('1234.5') неудобно. Есть ли способ сократить набор при работе в интерактивном интерпретаторе?

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

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

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

Ответ. Метод quantize() округляет до заданного числа десятичных знаков. Если установлен перехват Inexact, он также полезен для проверки:

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

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

Ответ. Некоторые операции, такие как сложение, вычитание и умножение на целое число, автоматически сохраняют фиксированную точку. Другие операции, например деление и умножение на нецелое число, изменяют количество десятичных знаков, и после них требуется шаг quantize():

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

При разработке приложений с фиксированной запятой удобно определить функции для обработки шага 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)                       # Автоматически сохранять фиксированную точку
Decimal('325.62')
>>> div(b, a)
Decimal('0.03')

Вопрос. Существует много способов выразить одно и то же значение. Числа 200, 200.000, 2E2 и 02E+4 при различной точности имеют одно и то же значение. Есть ли способ преобразовать их в единое узнаваемое каноническое значение?

Ответ. Метод normalize() отображает все эквивалентные значения в единого представителя:

>>> 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 всегда выводятся в экспоненциальной записи. Есть ли способ получить неэкспоненциальное представление?

Ответ. Для некоторых значений экспоненциальная запись – единственный способ выразить количество значащих цифр в коэффициенте. Например, представление 5.0E+3 в виде 5000 сохраняет значение, но не может показать двухзначную точность оригинала.

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

def remove_exponent(d):
    '''Удалить экспоненту и конечные нули.

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

    '''
    return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()

Вопрос. Есть ли способ преобразовать обычный float в Decimal?

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

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

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

Ответ. Модуль 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')

В качестве альтернативы входные данные можно округлить при создании с помощью метода Context.create_decimal():

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

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

9.4.1. Краткое руководство¶Quick-start Tutorial

9.4.2. Объекты Decimal¶Decimal objects

9.4.2.1. Логические операнды¶Logical operands

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

9.4.4. Сигналы¶Signals

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

9.4.5.1. Уменьшение ошибки округления за счёт повышенной точности¶Mitigating round-off error with increased precision

9.4.5.2. Специальные значения¶Special values

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

9.4.7. Рецепты¶Recipes

9.4.8. Часто задаваемые вопросы по Decimal¶Decimal FAQ

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