~dkuhlman/python-training-materials/Materials

<h1>9.4. <a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal">decimal</code></a> — Decimal fixed point and floating point arithmetic<a class="headerlink" href="#module-decimal" title="Permalink to this headline">¶</a></h1>

New in version 2.4.

</div>

The <a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal">decimal</code></a> module provides support for decimal floating point

arithmetic. It offers several advantages over the <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> datatype:

<ul>

<li>Decimal “is based on a floating-point model which was designed with people

in mind, and necessarily has a paramount guiding principle – computers must

provide an arithmetic that works in the same way as the arithmetic that

people learn at school.” – excerpt from the decimal arithmetic specification.

</li>

<li>Decimal numbers can be represented exactly. In contrast, numbers like

<code class="xref py py-const docutils literal">1.1</code> and <code class="xref py py-const docutils literal">2.2</code> do not have exact representations in binary

floating point. End users typically would not expect <code class="docutils literal">1.1 + 2.2</code> to display

as <code class="xref py py-const docutils literal">3.3000000000000003</code> as it does with binary floating point.

</li>

<li>The exactness carries over into arithmetic. In decimal floating point, <code class="docutils literal">0.1

+ 0.1 + 0.1 - 0.3</code> is exactly equal to zero. In binary floating point, the result

is <code class="xref py py-const docutils literal">5.5511151231257827e-017</code>. While near to zero, the differences

prevent reliable equality testing and differences can accumulate. For this

reason, decimal is preferred in accounting applications which have strict

100

equality invariants.

101

</li>

102

<li>The decimal module incorporates a notion of significant places so that <code class="docutils literal">1.30

103

+ 1.20</code> is <code class="xref py py-const docutils literal">2.50</code>. The trailing zero is kept to indicate significance.

104

This is the customary presentation for monetary applications. For

105

multiplication, the “schoolbook” approach uses all the figures in the

106

multiplicands. For instance, <code class="docutils literal">1.3 * 1.2</code> gives <code class="xref py py-const docutils literal">1.56</code> while <code class="docutils literal">1.30 *

107

1.20</code> gives <code class="xref py py-const docutils literal">1.5600</code>.

108

</li>

109

<li>Unlike hardware based binary floating point, the decimal module has a user

110

alterable precision (defaulting to 28 places) which can be as large as needed for

111

a given problem:

112

<div class="highlight-python"><div class="highlight"><pre>>>> from decimal import *

113

>>> getcontext().prec = 6

114

>>> Decimal(1) / Decimal(7)

115

Decimal('0.142857')

116

>>> getcontext().prec = 28

117

118

Decimal('0.1428571428571428571428571429')

119

</pre></div>

120

</div>

121

</li>

122

<li>Both binary and decimal floating point are implemented in terms of published

123

standards. While the built-in float type exposes only a modest portion of its

124

capabilities, the decimal module exposes all required parts of the standard.

125

When needed, the programmer has full control over rounding and signal handling.

126

This includes an option to enforce exact arithmetic by using exceptions

127

to block any inexact operations.

128

</li>

129

<li>The decimal module was designed to support “without prejudice, both exact

130

unrounded decimal arithmetic (sometimes called fixed-point arithmetic)

131

and rounded floating-point arithmetic.” – excerpt from the decimal

132

arithmetic specification.

133

</li>

134

</ul>

135

The module design is centered around three concepts: the decimal number, the

136

context for arithmetic, and signals.

137

A decimal number is immutable. It has a sign, coefficient digits, and an

138

exponent. To preserve significance, the coefficient digits do not truncate

139

trailing zeros. Decimals also include special values such as

140

<code class="xref py py-const docutils literal">Infinity</code>, <code class="xref py py-const docutils literal">-Infinity</code>, and <code class="xref py py-const docutils literal">NaN</code>. The standard also

141

differentiates <code class="xref py py-const docutils literal">-0</code> from <code class="xref py py-const docutils literal">+0</code>.

142

The context for arithmetic is an environment specifying precision, rounding

143

rules, limits on exponents, flags indicating the results of operations, and trap

144

enablers which determine whether signals are treated as exceptions. Rounding

145

options include <code class="xref py py-const docutils literal">ROUND_CEILING</code>, <code class="xref py py-const docutils literal">ROUND_DOWN</code>,

146

<code class="xref py py-const docutils literal">ROUND_FLOOR</code>, <code class="xref py py-const docutils literal">ROUND_HALF_DOWN</code>, <code class="xref py py-const docutils literal">ROUND_HALF_EVEN</code>,

147

<code class="xref py py-const docutils literal">ROUND_HALF_UP</code>, <code class="xref py py-const docutils literal">ROUND_UP</code>, and <code class="xref py py-const docutils literal">ROUND_05UP</code>.

148

Signals are groups of exceptional conditions arising during the course of

149

computation. Depending on the needs of the application, signals may be ignored,

150

considered as informational, or treated as exceptions. The signals in the

151

decimal module are: <a class="reference internal" href="#decimal.Clamped" title="decimal.Clamped"><code class="xref py py-const docutils literal">Clamped</code></a>, <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal">InvalidOperation</code></a>,

152

<a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-const docutils literal">DivisionByZero</code></a>, <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal">Inexact</code></a>, <a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal">Rounded</code></a>, <a class="reference internal" href="#decimal.Subnormal" title="decimal.Subnormal"><code class="xref py py-const docutils literal">Subnormal</code></a>,

153

<a class="reference internal" href="#decimal.Overflow" title="decimal.Overflow"><code class="xref py py-const docutils literal">Overflow</code></a>, and <a class="reference internal" href="#decimal.Underflow" title="decimal.Underflow"><code class="xref py py-const docutils literal">Underflow</code></a>.

154

For each signal there is a flag and a trap enabler. When a signal is

155

encountered, its flag is set to one, then, if the trap enabler is

156

set to one, an exception is raised. Flags are sticky, so the user needs to

157

reset them before monitoring a calculation.

158

159

See also

160

161

<li>IBM’s General Decimal Arithmetic Specification, <a class="reference external" href="http://speleotrove.com/decimal/">The General Decimal Arithmetic

162

Specification</a>.</li>

163

</ul>

164

</div>

165

166

<h2>9.4.1. Quick-start Tutorial<a class="headerlink" href="#quick-start-tutorial" title="Permalink to this headline">¶</a></h2>

167

The usual start to using decimals is importing the module, viewing the current

168

context with <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal">getcontext()</code></a> and, if necessary, setting new values for

169

precision, rounding, or enabled traps:

170

171

>>> getcontext()

172

Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,

173

capitals=1, flags=[], traps=[Overflow, DivisionByZero,

174

InvalidOperation])

175

176

>>> getcontext().prec = 7 # Set a new precision

177

</pre></div>

178

</div>

179

Decimal instances can be constructed from integers, strings, floats, or tuples.

180

Construction from an integer or a float performs an exact conversion of the

181

value of that integer or float. Decimal numbers include special values such as

182

<code class="xref py py-const docutils literal">NaN</code> which stands for “Not a number”, positive and negative

183

<code class="xref py py-const docutils literal">Infinity</code>, and <code class="xref py py-const docutils literal">-0</code>.

184

<div class="highlight-python"><div class="highlight"><pre>>>> getcontext().prec = 28

185

>>> Decimal(10)

186

Decimal('10')

187

>>> Decimal('3.14')

188

Decimal('3.14')

189

>>> Decimal(3.14)

190

Decimal('3.140000000000000124344978758017532527446746826171875')

191

>>> Decimal((0, (3, 1, 4), -2))

192

Decimal('3.14')

193

>>> Decimal(str(2.0 ** 0.5))

194

Decimal('1.41421356237')

195

>>> Decimal(2) ** Decimal('0.5')

196

Decimal('1.414213562373095048801688724')

197

>>> Decimal('NaN')

198

Decimal('NaN')

199

>>> Decimal('-Infinity')

200

Decimal('-Infinity')

201

</pre></div>

202

</div>

203

The significance of a new Decimal is determined solely by the number of digits

204

input. Context precision and rounding only come into play during arithmetic

205

operations.

206

207

>>> Decimal('3.0')

208

Decimal('3.0')

209

>>> Decimal('3.1415926535')

210

Decimal('3.1415926535')

211

>>> Decimal('3.1415926535') + Decimal('2.7182818285')

212

Decimal('5.85987')

213

>>> getcontext().rounding = ROUND_UP

214

215

Decimal('5.85988')

216

</pre></div>

217

</div>

218

Decimals interact well with much of the rest of Python. Here is a small decimal

219

floating point flying circus:

220

<div class="highlight-python"><div class="highlight"><pre>>>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())

221

>>> max(data)

222

Decimal('9.25')

223

>>> min(data)

224

Decimal('0.03')

225

>>> sorted(data)

226

[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),

227

Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]

228

>>> sum(data)

229

Decimal('19.29')

230

>>> a,b,c = data[:3]

231

>>> str(a)

232

'1.34'

233

>>> float(a)

234

1.34

235

>>> round(a, 1) # round() first converts to binary floating point

236

1.3

237

>>> int(a)

238

1

239

>>> a * 5

240

Decimal('6.70')

241

>>> a * b

242

Decimal('2.5058')

243

>>> c % a

244

Decimal('0.77')

245

</pre></div>

246

</div>

247

And some mathematical functions are also available to Decimal:

248

249

>>> Decimal(2).sqrt()

250

Decimal('1.414213562373095048801688724')

251

>>> Decimal(1).exp()

252

Decimal('2.718281828459045235360287471')

253

>>> Decimal('10').ln()

254

Decimal('2.302585092994045684017991455')

255

256

Decimal('1')

257

</pre></div>

258

</div>

259

The <code class="xref py py-meth docutils literal">quantize()</code> method rounds a number to a fixed exponent. This method is

260

useful for monetary applications that often round results to a fixed number of

261

places:

262

<div class="highlight-python"><div class="highlight"><pre>>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)

263

Decimal('7.32')

264

>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)

265

Decimal('8')

266

</pre></div>

267

</div>

268

As shown above, the <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal">getcontext()</code></a> function accesses the current context and

269

allows the settings to be changed. This approach meets the needs of most

270

applications.

271

For more advanced work, it may be useful to create alternate contexts using the

272

Context() constructor. To make an alternate active, use the <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal">setcontext()</code></a>

273

function.

274

In accordance with the standard, the <a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal">decimal</code></a> module provides two ready to

275

use standard contexts, <a class="reference internal" href="#decimal.BasicContext" title="decimal.BasicContext"><code class="xref py py-const docutils literal">BasicContext</code></a> and <a class="reference internal" href="#decimal.ExtendedContext" title="decimal.ExtendedContext"><code class="xref py py-const docutils literal">ExtendedContext</code></a>. The

276

former is especially useful for debugging because many of the traps are

277

enabled:

278

<div class="highlight-python"><div class="highlight"><pre>>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)

279

>>> setcontext(myothercontext)

280

281

Decimal('0.142857142857142857142857142857142857142857142857142857142857')

282

283

>>> ExtendedContext

284

Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,

285

capitals=1, flags=[], traps=[])

286

>>> setcontext(ExtendedContext)

287

288

Decimal('0.142857143')

289

>>> Decimal(42) / Decimal(0)

290

Decimal('Infinity')

291

292

>>> setcontext(BasicContext)

293

294

Traceback (most recent call last):

295

File "<pyshell#143>", line 1, in -toplevel-

296

Decimal(42) / Decimal(0)

297

DivisionByZero: x / 0

298

</pre></div>

299

</div>

300

Contexts also have signal flags for monitoring exceptional conditions

301

encountered during computations. The flags remain set until explicitly cleared,

302

so it is best to clear the flags before each set of monitored computations by

303

using the <code class="xref py py-meth docutils literal">clear_flags()</code> method.

304

<div class="highlight-python"><div class="highlight"><pre>>>> setcontext(ExtendedContext)

305

>>> getcontext().clear_flags()

306

>>> Decimal(355) / Decimal(113)

307

Decimal('3.14159292')

308

>>> getcontext()

309

Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,

310

capitals=1, flags=[Rounded, Inexact], traps=[])

311

</pre></div>

312

</div>

313

The flags entry shows that the rational approximation to <code class="xref py py-const docutils literal">Pi</code> was

314

rounded (digits beyond the context precision were thrown away) and that the

315

result is inexact (some of the discarded digits were non-zero).

316

Individual traps are set using the dictionary in the <code class="xref py py-attr docutils literal">traps</code> field of a

317

context:

318

319

320

Decimal('Infinity')

321

>>> getcontext().traps[DivisionByZero] = 1

322

323

Traceback (most recent call last):

324

File "<pyshell#112>", line 1, in -toplevel-

325

Decimal(1) / Decimal(0)

326

DivisionByZero: x / 0

327

</pre></div>

328

</div>

329

Most programs adjust the current context only once, at the beginning of the

330

program. And, in many applications, data is converted to <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> with

331

a single cast inside a loop. With context set and decimals created, the bulk of

332

the program manipulates the data no differently than with other Python numeric

333

types.

334

</div>

335

336

<h2>9.4.2. Decimal objects<a class="headerlink" href="#decimal-objects" title="Permalink to this headline">¶</a></h2>

337

338

339

class <code class="descclassname">decimal.</code><code class="descname">Decimal</code>([value[, context]])<a class="headerlink" href="#decimal.Decimal" title="Permalink to this definition">¶</a></dt>

340

<dd>Construct a new <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> object based from value.

341

value can be an integer, string, tuple, <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a>, or another <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a>

342

object. If no value is given, returns <code class="docutils literal">Decimal('0')</code>. If value is a

343

string, it should conform to the decimal numeric string syntax after leading

344

and trailing whitespace characters are removed:

345

<div class="highlight-python"><div class="highlight"><pre>sign ::= '+' | '-'

346

digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'

347

indicator ::= 'e' | 'E'

348

digits ::= digit [digit]...

349

decimal-part ::= digits '.' [digits] | ['.'] digits

350

exponent-part ::= indicator [sign] digits

351

infinity ::= 'Infinity' | 'Inf'

352

nan ::= 'NaN' [digits] | 'sNaN' [digits]

353

numeric-value ::= decimal-part [exponent-part] | infinity

354

numeric-string ::= [sign] numeric-value | [sign] nan

355

</pre></div>

356

</div>

357

If value is a unicode string then other Unicode decimal digits

358

are also permitted where <code class="docutils literal">digit</code> appears above. These include

359

decimal digits from various other alphabets (for example,

360

Arabic-Indic and Devanāgarī digits) along with the fullwidth digits

361

<code class="docutils literal">u'\uff10'</code> through <code class="docutils literal">u'\uff19'</code>.

362

If value is a <a class="reference internal" href="functions.html#tuple" title="tuple"><code class="xref py py-class docutils literal">tuple</code></a>, it should have three components, a sign

363

(<code class="xref py py-const docutils literal">0</code> for positive or <code class="xref py py-const docutils literal">1</code> for negative), a <a class="reference internal" href="functions.html#tuple" title="tuple"><code class="xref py py-class docutils literal">tuple</code></a> of

364

digits, and an integer exponent. For example, <code class="docutils literal">Decimal((0, (1, 4, 1, 4), -3))</code>

365

returns <code class="docutils literal">Decimal('1.414')</code>.

366

If value is a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a>, the binary floating point value is losslessly

367

converted to its exact decimal equivalent. This conversion can often require

368

53 or more digits of precision. For example, <code class="docutils literal">Decimal(float('1.1'))</code>

369

converts to

370

<code class="docutils literal">Decimal('1.100000000000000088817841970012523233890533447265625')</code>.

371

The context precision does not affect how many digits are stored. That is

372

determined exclusively by the number of digits in value. For example,

373

<code class="docutils literal">Decimal('3.00000')</code> records all five zeros even if the context precision is

374

only three.

375

The purpose of the context argument is determining what to do if value is a

376

malformed string. If the context traps <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal">InvalidOperation</code></a>, an exception

377

is raised; otherwise, the constructor returns a new Decimal with the value of

378

<code class="xref py py-const docutils literal">NaN</code>.

379

Once constructed, <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> objects are immutable.

380

381

Changed in version 2.6: leading and trailing whitespace characters are permitted when

382

creating a Decimal instance from a string.

383

</div>

384

385

Changed in version 2.7: The argument to the constructor is now permitted to be a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> instance.

386

</div>

387

Decimal floating point objects share many properties with the other built-in

388

numeric types such as <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> and <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a>. All of the usual math

389

operations and special methods apply. Likewise, decimal objects can be

390

copied, pickled, printed, used as dictionary keys, used as set elements,

391

compared, sorted, and coerced to another type (such as <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> or

392

<a class="reference internal" href="functions.html#long" title="long"><code class="xref py py-class docutils literal">long</code></a>).

393

There are some small differences between arithmetic on Decimal objects and

394

arithmetic on integers and floats. When the remainder operator <code class="docutils literal">%</code> is

395

applied to Decimal objects, the sign of the result is the sign of the

396

dividend rather than the sign of the divisor:

397

<div class="highlight-python"><div class="highlight"><pre>>>> (-7) % 4

398

1

399

>>> Decimal(-7) % Decimal(4)

400

Decimal('-3')

401

</pre></div>

402

</div>

403

The integer division operator <code class="docutils literal">//</code> behaves analogously, returning the

404

integer part of the true quotient (truncating towards zero) rather than its

405

floor, so as to preserve the usual identity <code class="docutils literal">x == (x // y) * y + x % y</code>:

406

<div class="highlight-python"><div class="highlight"><pre>>>> -7 // 4

407

-2

408

>>> Decimal(-7) // Decimal(4)

409

Decimal('-1')

410

</pre></div>

411

</div>

412

The <code class="docutils literal">%</code> and <code class="docutils literal">//</code> operators implement the <code class="docutils literal">remainder</code> and

413

<code class="docutils literal">divide-integer</code> operations (respectively) as described in the

414

specification.

415

Decimal objects cannot generally be combined with floats in

416

arithmetic operations: an attempt to add a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> to a

417

<a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a>, for example, will raise a <a class="reference internal" href="exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a>.

418

There’s one exception to this rule: it’s possible to use Python’s

419

comparison operators to compare a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> instance <code class="docutils literal">x</code>

420

with a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> instance <code class="docutils literal">y</code>. Without this exception,

421

comparisons between <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> and <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> instances

422

would follow the general rules for comparing objects of different

423

types described in the <a class="reference internal" href="../reference/expressions.html#expressions">Expressions</a> section of the reference

424

manual, leading to confusing results.

425

426

Changed in version 2.7: A comparison between a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> instance <code class="docutils literal">x</code> and a

427

<a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> instance <code class="docutils literal">y</code> now returns a result based on

428

the values of <code class="docutils literal">x</code> and <code class="docutils literal">y</code>. In earlier versions <code class="docutils literal">x < y</code>

429

returned the same (arbitrary) result for any <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a>

430

instance <code class="docutils literal">x</code> and any <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> instance <code class="docutils literal">y</code>.

431

</div>

432

In addition to the standard numeric properties, decimal floating point

433

objects also have a number of specialized methods:

434

435

436

<code class="descname">adjusted</code>()<a class="headerlink" href="#decimal.Decimal.adjusted" title="Permalink to this definition">¶</a></dt>

437

<dd>Return the adjusted exponent after shifting out the coefficient’s

438

rightmost digits until only the lead digit remains:

439

<code class="docutils literal">Decimal('321e+5').adjusted()</code> returns seven. Used for determining the

440

position of the most significant digit with respect to the decimal point.

441

</dd></dl>

442

443

444

445

<code class="descname">as_tuple</code>()<a class="headerlink" href="#decimal.Decimal.as_tuple" title="Permalink to this definition">¶</a></dt>

446

<dd>Return a <a class="reference internal" href="../glossary.html#term-named-tuple">named tuple</a> representation of the number:

447

<code class="docutils literal">DecimalTuple(sign, digits, exponent)</code>.

448

449

Changed in version 2.6: Use a named tuple.

450

</div>

451

</dd></dl>

452

453

454

455

<code class="descname">canonical</code>()<a class="headerlink" href="#decimal.Decimal.canonical" title="Permalink to this definition">¶</a></dt>

456

<dd>Return the canonical encoding of the argument. Currently, the encoding of

457

a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> instance is always canonical, so this operation returns

458

its argument unchanged.

459

460

New in version 2.6.

461

</div>

462

</dd></dl>

463

464

465

466

<code class="descname">compare</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.compare" title="Permalink to this definition">¶</a></dt>

467

<dd>Compare the values of two Decimal instances. This operation behaves in

468

the same way as the usual comparison method <a class="reference internal" href="../reference/datamodel.html#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a>, except that

469

<a class="reference internal" href="#decimal.Decimal.compare" title="decimal.Decimal.compare"><code class="xref py py-meth docutils literal">compare()</code></a> returns a Decimal instance rather than an integer, and if

470

either operand is a NaN then the result is a NaN:

471

<div class="highlight-python"><div class="highlight"><pre>a or b is a NaN ==> Decimal('NaN')

472

a Decimal('-1')

473

a == b ==> Decimal('0')

474

a > b ==> Decimal('1')

475

</pre></div>

476

</div>

477

</dd></dl>

478

479

480

481

<code class="descname">compare_signal</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.compare_signal" title="Permalink to this definition">¶</a></dt>

482

<dd>This operation is identical to the <a class="reference internal" href="#decimal.Decimal.compare" title="decimal.Decimal.compare"><code class="xref py py-meth docutils literal">compare()</code></a> method, except that all

483

NaNs signal. That is, if neither operand is a signaling NaN then any

484

quiet NaN operand is treated as though it were a signaling NaN.

485

486

New in version 2.6.

487

</div>

488

</dd></dl>

489

490

491

492

<code class="descname">compare_total</code>(other)<a class="headerlink" href="#decimal.Decimal.compare_total" title="Permalink to this definition">¶</a></dt>

493

<dd>Compare two operands using their abstract representation rather than their

494

numerical value. Similar to the <a class="reference internal" href="#decimal.Decimal.compare" title="decimal.Decimal.compare"><code class="xref py py-meth docutils literal">compare()</code></a> method, but the result

495

gives a total ordering on <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> instances. Two

496

497

representations compare unequal in this ordering:

498

499

Decimal('-1')

500

</pre></div>

501

</div>

502

Quiet and signaling NaNs are also included in the total ordering. The

503

result of this function is <code class="docutils literal">Decimal('0')</code> if both operands have the same

504

representation, <code class="docutils literal">Decimal('-1')</code> if the first operand is lower in the

505

total order than the second, and <code class="docutils literal">Decimal('1')</code> if the first operand is

506

higher in the total order than the second operand. See the specification

507

for details of the total order.

508

509

New in version 2.6.

510

</div>

511

</dd></dl>

512

513

514

515

<code class="descname">compare_total_mag</code>(other)<a class="headerlink" href="#decimal.Decimal.compare_total_mag" title="Permalink to this definition">¶</a></dt>

516

<dd>Compare two operands using their abstract representation rather than their

517

value as in <a class="reference internal" href="#decimal.Decimal.compare_total" title="decimal.Decimal.compare_total"><code class="xref py py-meth docutils literal">compare_total()</code></a>, but ignoring the sign of each operand.

518

<code class="docutils literal">x.compare_total_mag(y)</code> is equivalent to

519

<code class="docutils literal">x.copy_abs().compare_total(y.copy_abs())</code>.

520

521

New in version 2.6.

522

</div>

523

</dd></dl>

524

525

526

527

<code class="descname">conjugate</code>()<a class="headerlink" href="#decimal.Decimal.conjugate" title="Permalink to this definition">¶</a></dt>

528

<dd>Just returns self, this method is only to comply with the Decimal

529

Specification.

530

531

New in version 2.6.

532

</div>

533

</dd></dl>

534

535

536

537

538

<dd>Return the absolute value of the argument. This operation is unaffected

539

by the context and is quiet: no flags are changed and no rounding is

540

performed.

541

542

New in version 2.6.

543

</div>

544

</dd></dl>

545

546

547

548

<code class="descname">copy_negate</code>()<a class="headerlink" href="#decimal.Decimal.copy_negate" title="Permalink to this definition">¶</a></dt>

549

<dd>Return the negation of the argument. This operation is unaffected by the

550

context and is quiet: no flags are changed and no rounding is performed.

551

552

New in version 2.6.

553

</div>

554

</dd></dl>

555

556

557

558

<code class="descname">copy_sign</code>(other)<a class="headerlink" href="#decimal.Decimal.copy_sign" title="Permalink to this definition">¶</a></dt>

559

<dd>Return a copy of the first operand with the sign set to be the same as the

560

sign of the second operand. For example:

561

562

Decimal('-2.3')

563

</pre></div>

564

</div>

565

This operation is unaffected by the context and is quiet: no flags are

566

changed and no rounding is performed.

567

568

New in version 2.6.

569

</div>

570

</dd></dl>

571

572

573

574

<code class="descname">exp</code>([context])<a class="headerlink" href="#decimal.Decimal.exp" title="Permalink to this definition">¶</a></dt>

575

<dd>Return the value of the (natural) exponential function <code class="docutils literal">e**x</code> at the

576

given number. The result is correctly rounded using the

577

<code class="xref py py-const docutils literal">ROUND_HALF_EVEN</code> rounding mode.

578

579

Decimal('2.718281828459045235360287471')

580

>>> Decimal(321).exp()

581

Decimal('2.561702493119680037517373933E+139')

582

</pre></div>

583

</div>

584

585

New in version 2.6.

586

</div>

587

</dd></dl>

588

589

590

591

<code class="descname">from_float</code>(f)<a class="headerlink" href="#decimal.Decimal.from_float" title="Permalink to this definition">¶</a></dt>

592

<dd>Classmethod that converts a float to a decimal number, exactly.

593

Note <cite>Decimal.from_float(0.1)</cite> is not the same as <cite>Decimal(‘0.1’)</cite>.

594

Since 0.1 is not exactly representable in binary floating point, the

595

value is stored as the nearest representable value which is

596

<cite>0x1.999999999999ap-4</cite>. That equivalent value in decimal is

597

<cite>0.1000000000000000055511151231257827021181583404541015625</cite>.

598

599

Note

600

From Python 2.7 onwards, a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> instance

601

can also be constructed directly from a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a>.

602

</div>

603

<div class="highlight-python"><div class="highlight"><pre>>>> Decimal.from_float(0.1)

604

Decimal('0.1000000000000000055511151231257827021181583404541015625')

605

>>> Decimal.from_float(float('nan'))

606

Decimal('NaN')

607

608

Decimal('Infinity')

609

610

Decimal('-Infinity')

611

</pre></div>

612

</div>

613

614

New in version 2.7.

615

</div>

616

</dd></dl>

617

618

619

620

<code class="descname">fma</code>(other, third[, context])<a class="headerlink" href="#decimal.Decimal.fma" title="Permalink to this definition">¶</a></dt>

621

<dd>Fused multiply-add. Return self*other+third with no rounding of the

622

intermediate product self*other.

623

624

Decimal('11')

625

</pre></div>

626

</div>

627

628

New in version 2.6.

629

</div>

630

</dd></dl>

631

632

633

634

<code class="descname">is_canonical</code>()<a class="headerlink" href="#decimal.Decimal.is_canonical" title="Permalink to this definition">¶</a></dt>

635

<dd>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a> if the argument is canonical and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a>

636

otherwise. Currently, a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> instance is always canonical, so

637

this operation always returns <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a>.

638

639

New in version 2.6.

640

</div>

641

</dd></dl>

642

643

644

645

<code class="descname">is_finite</code>()<a class="headerlink" href="#decimal.Decimal.is_finite" title="Permalink to this definition">¶</a></dt>

646

647

<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> if the argument is an infinity or a NaN.

648

649

New in version 2.6.

650

</div>

651

</dd></dl>

652

653

654

655

<code class="descname">is_infinite</code>()<a class="headerlink" href="#decimal.Decimal.is_infinite" title="Permalink to this definition">¶</a></dt>

656

657

infinity and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> otherwise.

658

659

New in version 2.6.

660

</div>

661

</dd></dl>

662

663

664

665

666

667

<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> otherwise.

668

669

New in version 2.6.

670

</div>

671

</dd></dl>

672

673

674

675

<code class="descname">is_normal</code>()<a class="headerlink" href="#decimal.Decimal.is_normal" title="Permalink to this definition">¶</a></dt>

676

677

number with an adjusted exponent greater than or equal to Emin.

678

Return <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> if the argument is zero, subnormal, infinite or a

679

NaN. Note, the term normal is used here in a different sense with

680

the <a class="reference internal" href="#decimal.Decimal.normalize" title="decimal.Decimal.normalize"><code class="xref py py-meth docutils literal">normalize()</code></a> method which is used to create canonical values.

681

682

New in version 2.6.

683

</div>

684

</dd></dl>

685

686

687

688

689

690

<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> otherwise.

691

692

New in version 2.6.

693

</div>

694

</dd></dl>

695

696

697

698

<code class="descname">is_signed</code>()<a class="headerlink" href="#decimal.Decimal.is_signed" title="Permalink to this definition">¶</a></dt>

699

700

701

702

New in version 2.6.

703

</div>

704

</dd></dl>

705

706

707

708

709

<dd>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a> if the argument is a signaling NaN and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a>

710

otherwise.

711

712

New in version 2.6.

713

</div>

714

</dd></dl>

715

716

717

718

<code class="descname">is_subnormal</code>()<a class="headerlink" href="#decimal.Decimal.is_subnormal" title="Permalink to this definition">¶</a></dt>

719

<dd>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a> if the argument is subnormal, and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a>

720

otherwise. A number is subnormal is if it is nonzero, finite, and has an

721

adjusted exponent less than Emin.

722

723

New in version 2.6.

724

</div>

725

</dd></dl>

726

727

728

729

730

731

<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> otherwise.

732

733

New in version 2.6.

734

</div>

735

</dd></dl>

736

737

738

739

<code class="descname">ln</code>([context])<a class="headerlink" href="#decimal.Decimal.ln" title="Permalink to this definition">¶</a></dt>

740

<dd>Return the natural (base e) logarithm of the operand. The result is

741

correctly rounded using the <code class="xref py py-const docutils literal">ROUND_HALF_EVEN</code> rounding mode.

742

743

New in version 2.6.

744

</div>

745

</dd></dl>

746

747

748

749

<code class="descname">log10</code>([context])<a class="headerlink" href="#decimal.Decimal.log10" title="Permalink to this definition">¶</a></dt>

750

<dd>Return the base ten logarithm of the operand. The result is correctly

751

rounded using the <code class="xref py py-const docutils literal">ROUND_HALF_EVEN</code> rounding mode.

752

753

New in version 2.6.

754

</div>

755

</dd></dl>

756

757

758

759

<code class="descname">logb</code>([context])<a class="headerlink" href="#decimal.Decimal.logb" title="Permalink to this definition">¶</a></dt>

760

<dd>For a nonzero number, return the adjusted exponent of its operand as a

761

762

<code class="docutils literal">Decimal('-Infinity')</code> is returned and the <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-const docutils literal">DivisionByZero</code></a> flag

763

is raised. If the operand is an infinity then <code class="docutils literal">Decimal('Infinity')</code> is

764

returned.

765

766

New in version 2.6.

767

</div>

768

</dd></dl>

769

770

771

772

<code class="descname">logical_and</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.logical_and" title="Permalink to this definition">¶</a></dt>

773

<dd><a class="reference internal" href="#decimal.Decimal.logical_and" title="decimal.Decimal.logical_and"><code class="xref py py-meth docutils literal">logical_and()</code></a> is a logical operation which takes two logical

774

operands (see <a class="reference internal" href="#logical-operands-label">Logical operands</a>). The result is the

775

digit-wise <code class="docutils literal">and</code> of the two operands.

776

777

New in version 2.6.

778

</div>

779

</dd></dl>

780

781

782

783

<code class="descname">logical_invert</code>([context])<a class="headerlink" href="#decimal.Decimal.logical_invert" title="Permalink to this definition">¶</a></dt>

784

<dd><a class="reference internal" href="#decimal.Decimal.logical_invert" title="decimal.Decimal.logical_invert"><code class="xref py py-meth docutils literal">logical_invert()</code></a> is a logical operation. The

785

result is the digit-wise inversion of the operand.

786

787

New in version 2.6.

788

</div>

789

</dd></dl>

790

791

792

793

<code class="descname">logical_or</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.logical_or" title="Permalink to this definition">¶</a></dt>

794

<dd><a class="reference internal" href="#decimal.Decimal.logical_or" title="decimal.Decimal.logical_or"><code class="xref py py-meth docutils literal">logical_or()</code></a> is a logical operation which takes two logical

795

operands (see <a class="reference internal" href="#logical-operands-label">Logical operands</a>). The result is the

796

digit-wise <code class="docutils literal">or</code> of the two operands.

797

798

New in version 2.6.

799

</div>

800

</dd></dl>

801

802

803

804

<code class="descname">logical_xor</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.logical_xor" title="Permalink to this definition">¶</a></dt>

805

<dd><a class="reference internal" href="#decimal.Decimal.logical_xor" title="decimal.Decimal.logical_xor"><code class="xref py py-meth docutils literal">logical_xor()</code></a> is a logical operation which takes two logical

806

operands (see <a class="reference internal" href="#logical-operands-label">Logical operands</a>). The result is the

807

digit-wise exclusive or of the two operands.

808

809

New in version 2.6.

810

</div>

811

</dd></dl>

812

813

814

815

<code class="descname">max</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.max" title="Permalink to this definition">¶</a></dt>

816

<dd>Like <code class="docutils literal">max(self, other)</code> except that the context rounding rule is applied

817

before returning and that <code class="xref py py-const docutils literal">NaN</code> values are either signaled or

818

ignored (depending on the context and whether they are signaling or

819

quiet).

820

</dd></dl>

821

822

823

824

<code class="descname">max_mag</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.max_mag" title="Permalink to this definition">¶</a></dt>

825

<dd>Similar to the <a class="reference internal" href="#decimal.Decimal.max" title="decimal.Decimal.max"><code class="xref py py-meth docutils literal">max()</code></a> method, but the comparison is done using the

826

absolute values of the operands.

827

828

New in version 2.6.

829

</div>

830

</dd></dl>

831

832

833

834

<code class="descname">min</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.min" title="Permalink to this definition">¶</a></dt>

835

<dd>Like <code class="docutils literal">min(self, other)</code> except that the context rounding rule is applied

836

before returning and that <code class="xref py py-const docutils literal">NaN</code> values are either signaled or

837

ignored (depending on the context and whether they are signaling or

838

quiet).

839

</dd></dl>

840

841

842

843

<code class="descname">min_mag</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.min_mag" title="Permalink to this definition">¶</a></dt>

844

<dd>Similar to the <a class="reference internal" href="#decimal.Decimal.min" title="decimal.Decimal.min"><code class="xref py py-meth docutils literal">min()</code></a> method, but the comparison is done using the

845

absolute values of the operands.

846

847

New in version 2.6.

848

</div>

849

</dd></dl>

850

851

852

853

<code class="descname">next_minus</code>([context])<a class="headerlink" href="#decimal.Decimal.next_minus" title="Permalink to this definition">¶</a></dt>

854

<dd>Return the largest number representable in the given context (or in the

855

current thread’s context if no context is given) that is smaller than the

856

given operand.

857

858

New in version 2.6.

859

</div>

860

</dd></dl>

861

862

863

864

<code class="descname">next_plus</code>([context])<a class="headerlink" href="#decimal.Decimal.next_plus" title="Permalink to this definition">¶</a></dt>

865

<dd>Return the smallest number representable in the given context (or in the

866

current thread’s context if no context is given) that is larger than the

867

given operand.

868

869

New in version 2.6.

870

</div>

871

</dd></dl>

872

873

874

875

<code class="descname">next_toward</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.next_toward" title="Permalink to this definition">¶</a></dt>

876

<dd>If the two operands are unequal, return the number closest to the first

877

operand in the direction of the second operand. If both operands are

878

numerically equal, return a copy of the first operand with the sign set to

879

be the same as the sign of the second operand.

880

881

New in version 2.6.

882

</div>

883

</dd></dl>

884

885

886

887

<code class="descname">normalize</code>([context])<a class="headerlink" href="#decimal.Decimal.normalize" title="Permalink to this definition">¶</a></dt>

888

<dd>Normalize the number by stripping the rightmost trailing zeros and

889

converting any result equal to <code class="xref py py-const docutils literal">Decimal('0')</code> to

890

<code class="xref py py-const docutils literal">Decimal('0e0')</code>. Used for producing canonical values for attributes

891

of an equivalence class. For example, <code class="docutils literal">Decimal('32.100')</code> and

892

<code class="docutils literal">Decimal('0.321000e+2')</code> both normalize to the equivalent value

893

<code class="docutils literal">Decimal('32.1')</code>.

894

</dd></dl>

895

896

897

898

<code class="descname">number_class</code>([context])<a class="headerlink" href="#decimal.Decimal.number_class" title="Permalink to this definition">¶</a></dt>

899

<dd>Return a string describing the class of the operand. The returned value

900

is one of the following ten strings.

901

902

<li><code class="docutils literal">"-Infinity"</code>, indicating that the operand is negative infinity.</li>

903

<li><code class="docutils literal">"-Normal"</code>, indicating that the operand is a negative normal number.</li>

904

<li><code class="docutils literal">"-Subnormal"</code>, indicating that the operand is negative and subnormal.</li>

905

<li><code class="docutils literal">"-Zero"</code>, indicating that the operand is a negative zero.</li>

906

<li><code class="docutils literal">"+Zero"</code>, indicating that the operand is a positive zero.</li>

907

<li><code class="docutils literal">"+Subnormal"</code>, indicating that the operand is positive and subnormal.</li>

908

<li><code class="docutils literal">"+Normal"</code>, indicating that the operand is a positive normal number.</li>

909

<li><code class="docutils literal">"+Infinity"</code>, indicating that the operand is positive infinity.</li>

910

<li><code class="docutils literal">"NaN"</code>, indicating that the operand is a quiet NaN (Not a Number).</li>

911

<li><code class="docutils literal">"sNaN"</code>, indicating that the operand is a signaling NaN.</li>

912

</ul>

913

914

New in version 2.6.

915

</div>

916

</dd></dl>

917

918

919

920

<code class="descname">quantize</code>(exp[, rounding[, context[, watchexp]]])<a class="headerlink" href="#decimal.Decimal.quantize" title="Permalink to this definition">¶</a></dt>

921

<dd>Return a value equal to the first operand after rounding and having the

922

exponent of the second operand.

923

924

Decimal('1.414')

925

</pre></div>

926

</div>

927

Unlike other operations, if the length of the coefficient after the

928

quantize operation would be greater than precision, then an

929

<a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal">InvalidOperation</code></a> is signaled. This guarantees that, unless there

930

is an error condition, the quantized exponent is always equal to that of

931

the right-hand operand.

932

Also unlike other operations, quantize never signals Underflow, even if

933

the result is subnormal and inexact.

934

If the exponent of the second operand is larger than that of the first

935

then rounding may be necessary. In this case, the rounding mode is

936

determined by the <code class="docutils literal">rounding</code> argument if given, else by the given

937

<code class="docutils literal">context</code> argument; if neither argument is given the rounding mode of

938

the current thread’s context is used.

939

If watchexp is set (default), then an error is returned whenever the

940

resulting exponent is greater than <code class="xref py py-attr docutils literal">Emax</code> or less than

941

<code class="xref py py-attr docutils literal">Etiny</code>.

942

</dd></dl>

943

944

945

946

<code class="descname">radix</code>()<a class="headerlink" href="#decimal.Decimal.radix" title="Permalink to this definition">¶</a></dt>

947

<dd>Return <code class="docutils literal">Decimal(10)</code>, the radix (base) in which the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a>

948

class does all its arithmetic. Included for compatibility with the

949

specification.

950

951

New in version 2.6.

952

</div>

953

</dd></dl>

954

955

956

957

<code class="descname">remainder_near</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.remainder_near" title="Permalink to this definition">¶</a></dt>

958

<dd>Return the remainder from dividing self by other. This differs from

959

<code class="docutils literal">self % other</code> in that the sign of the remainder is chosen so as to

960

minimize its absolute value. More precisely, the return value is

961

<code class="docutils literal">self - n * other</code> where <code class="docutils literal">n</code> is the integer nearest to the exact

962

value of <code class="docutils literal">self / other</code>, and if two integers are equally near then the

963

even one is chosen.

964

If the result is zero then its sign will be the sign of self.

965

966

Decimal('-2')

967

>>> Decimal(25).remainder_near(Decimal(10))

968

Decimal('5')

969

>>> Decimal(35).remainder_near(Decimal(10))

970

Decimal('-5')

971

</pre></div>

972

</div>

973

</dd></dl>

974

975

976

977

<code class="descname">rotate</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.rotate" title="Permalink to this definition">¶</a></dt>

978

<dd>Return the result of rotating the digits of the first operand by an amount

979

specified by the second operand. The second operand must be an integer in

980

the range -precision through precision. The absolute value of the second

981

operand gives the number of places to rotate. If the second operand is

982

positive then rotation is to the left; otherwise rotation is to the right.

983

The coefficient of the first operand is padded on the left with zeros to

984

length precision if necessary. The sign and exponent of the first operand

985

are unchanged.

986

987

New in version 2.6.

988

</div>

989

</dd></dl>

990

991

992

993

<code class="descname">same_quantum</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.same_quantum" title="Permalink to this definition">¶</a></dt>

994

<dd>Test whether self and other have the same exponent or whether both are

995

<code class="xref py py-const docutils literal">NaN</code>.

996

</dd></dl>

997

998

999

1000

<code class="descname">scaleb</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.scaleb" title="Permalink to this definition">¶</a></dt>

1001

<dd>Return the first operand with exponent adjusted by the second.

1002

Equivalently, return the first operand multiplied by <code class="docutils literal">10**other</code>. The

1003

second operand must be an integer.

1004

1005

New in version 2.6.

1006

</div>

1007

</dd></dl>

1008

1009

1010

1011

<code class="descname">shift</code>(other[, context])<a class="headerlink" href="#decimal.Decimal.shift" title="Permalink to this definition">¶</a></dt>

1012

<dd>Return the result of shifting the digits of the first operand by an amount

1013

specified by the second operand. The second operand must be an integer in

1014

the range -precision through precision. The absolute value of the second

1015

operand gives the number of places to shift. If the second operand is

1016

positive then the shift is to the left; otherwise the shift is to the

1017

right. Digits shifted into the coefficient are zeros. The sign and

1018

exponent of the first operand are unchanged.

1019

1020

New in version 2.6.

1021

</div>

1022

</dd></dl>

1023

1024

1025

1026

<code class="descname">sqrt</code>([context])<a class="headerlink" href="#decimal.Decimal.sqrt" title="Permalink to this definition">¶</a></dt>

1027

<dd>Return the square root of the argument to full precision.

1028

</dd></dl>

1029

1030

1031

1032

<code class="descname">to_eng_string</code>([context])<a class="headerlink" href="#decimal.Decimal.to_eng_string" title="Permalink to this definition">¶</a></dt>

1033

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

1034

Engineering notation has an exponent which is a multiple of 3. This

1035

can leave up to 3 digits to the left of the decimal place and may

1036

require the addition of either one or two trailing zeros.

1037

For example, this converts <code class="docutils literal">Decimal('123E+1')</code> to <code class="docutils literal">Decimal('1.23E+3')</code>.

1038

</dd></dl>

1039

1040

1041

1042

<code class="descname">to_integral</code>([rounding[, context]])<a class="headerlink" href="#decimal.Decimal.to_integral" title="Permalink to this definition">¶</a></dt>

1043

<dd>Identical to the <a class="reference internal" href="#decimal.Decimal.to_integral_value" title="decimal.Decimal.to_integral_value"><code class="xref py py-meth docutils literal">to_integral_value()</code></a> method. The <code class="docutils literal">to_integral</code>

1044

name has been kept for compatibility with older versions.

1045

</dd></dl>

1046

1047

1048

1049

<code class="descname">to_integral_exact</code>([rounding[, context]])<a class="headerlink" href="#decimal.Decimal.to_integral_exact" title="Permalink to this definition">¶</a></dt>

1050

<dd>Round to the nearest integer, signaling <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal">Inexact</code></a> or

1051

<a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal">Rounded</code></a> as appropriate if rounding occurs. The rounding mode is

1052

determined by the <code class="docutils literal">rounding</code> parameter if given, else by the given

1053

<code class="docutils literal">context</code>. If neither parameter is given then the rounding mode of the

1054

current context is used.

1055

1056

New in version 2.6.

1057

</div>

1058

</dd></dl>

1059

1060

1061

1062

<code class="descname">to_integral_value</code>([rounding[, context]])<a class="headerlink" href="#decimal.Decimal.to_integral_value" title="Permalink to this definition">¶</a></dt>

1063

<dd>Round to the nearest integer without signaling <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal">Inexact</code></a> or

1064

<a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal">Rounded</code></a>. If given, applies rounding; otherwise, uses the

1065

rounding method in either the supplied context or the current context.

1066

1067

Changed in version 2.6: renamed from <code class="docutils literal">to_integral</code> to <code class="docutils literal">to_integral_value</code>. The old name

1068

remains valid for compatibility.

1069

</div>

1070

</dd></dl>

1071

1072

</dd></dl>

1073

1074

1075

<h3>9.4.2.1. Logical operands<a class="headerlink" href="#logical-operands" title="Permalink to this headline">¶</a></h3>

1076

The <code class="xref py py-meth docutils literal">logical_and()</code>, <code class="xref py py-meth docutils literal">logical_invert()</code>, <code class="xref py py-meth docutils literal">logical_or()</code>,

1077

and <code class="xref py py-meth docutils literal">logical_xor()</code> methods expect their arguments to be logical

1078

operands. A logical operand is a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> instance whose

1079

exponent and sign are both zero, and whose digits are all either

1080

<code class="xref py py-const docutils literal">0</code> or <code class="xref py py-const docutils literal">1</code>.

1081

</div>

1082

</div>

1083

1084

<h2>9.4.3. Context objects<a class="headerlink" href="#context-objects" title="Permalink to this headline">¶</a></h2>

1085

Contexts are environments for arithmetic operations. They govern precision, set

1086

rules for rounding, determine which signals are treated as exceptions, and limit

1087

the range for exponents.

1088

Each thread has its own current context which is accessed or changed using the

1089

<a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal">getcontext()</code></a> and <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal">setcontext()</code></a> functions:

1090

1091

1092

<code class="descclassname">decimal.</code><code class="descname">getcontext</code>()<a class="headerlink" href="#decimal.getcontext" title="Permalink to this definition">¶</a></dt>

1093

<dd>Return the current context for the active thread.

1094

</dd></dl>

1095

1096

1097

1098

<code class="descclassname">decimal.</code><code class="descname">setcontext</code>(c)<a class="headerlink" href="#decimal.setcontext" title="Permalink to this definition">¶</a></dt>

1099

<dd>Set the current context for the active thread to c.

1100

</dd></dl>

1101

1102

Beginning with Python 2.5, you can also use the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal">with</code></a> statement and

1103

the <a class="reference internal" href="#decimal.localcontext" title="decimal.localcontext"><code class="xref py py-func docutils literal">localcontext()</code></a> function to temporarily change the active context.

1104

1105

1106

<code class="descclassname">decimal.</code><code class="descname">localcontext</code>([c])<a class="headerlink" href="#decimal.localcontext" title="Permalink to this definition">¶</a></dt>

1107

<dd>Return a context manager that will set the current context for the active thread

1108

to a copy of c on entry to the with-statement and restore the previous context

1109

when exiting the with-statement. If no context is specified, a copy of the

1110

current context is used.

1111

1112

New in version 2.5.

1113

</div>

1114

For example, the following code sets the current decimal precision to 42 places,

1115

performs a calculation, and then automatically restores the previous context:

1116

<div class="highlight-python"><div class="highlight"><pre>from decimal import localcontext

1117

1118

with localcontext() as ctx:

1119

ctx.prec = 42 # Perform a high precision calculation

1120

s = calculate_something()

1121

s = +s # Round the final result back to the default precision

1122

1123

with localcontext(BasicContext): # temporarily use the BasicContext

1124

print Decimal(1) / Decimal(7)

1125

print Decimal(355) / Decimal(113)

1126

</pre></div>

1127

</div>

1128

</dd></dl>

1129

1130

New contexts can also be created using the <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a> constructor

1131

described below. In addition, the module provides three pre-made contexts:

1132

1133

1134

class <code class="descclassname">decimal.</code><code class="descname">BasicContext</code><a class="headerlink" href="#decimal.BasicContext" title="Permalink to this definition">¶</a></dt>

1135

<dd>This is a standard context defined by the General Decimal Arithmetic

1136

Specification. Precision is set to nine. Rounding is set to

1137

<code class="xref py py-const docutils literal">ROUND_HALF_UP</code>. All flags are cleared. All traps are enabled (treated

1138

as exceptions) except <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal">Inexact</code></a>, <a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal">Rounded</code></a>, and

1139

<a class="reference internal" href="#decimal.Subnormal" title="decimal.Subnormal"><code class="xref py py-const docutils literal">Subnormal</code></a>.

1140

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

1141

</dd></dl>

1142

1143

1144

1145

class <code class="descclassname">decimal.</code><code class="descname">ExtendedContext</code><a class="headerlink" href="#decimal.ExtendedContext" title="Permalink to this definition">¶</a></dt>

1146

<dd>This is a standard context defined by the General Decimal Arithmetic

1147

Specification. Precision is set to nine. Rounding is set to

1148

<code class="xref py py-const docutils literal">ROUND_HALF_EVEN</code>. All flags are cleared. No traps are enabled (so that

1149

exceptions are not raised during computations).

1150

Because the traps are disabled, this context is useful for applications that

1151

prefer to have result value of <code class="xref py py-const docutils literal">NaN</code> or <code class="xref py py-const docutils literal">Infinity</code> instead of

1152

raising exceptions. This allows an application to complete a run in the

1153

presence of conditions that would otherwise halt the program.

1154

</dd></dl>

1155

1156

1157

1158

class <code class="descclassname">decimal.</code><code class="descname">DefaultContext</code><a class="headerlink" href="#decimal.DefaultContext" title="Permalink to this definition">¶</a></dt>

1159

<dd>This context is used by the <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a> constructor as a prototype for new

1160

contexts. Changing a field (such a precision) has the effect of changing the

1161

default for new contexts created by the <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a> constructor.

1162

This context is most useful in multi-threaded environments. Changing one of the

1163

fields before threads are started has the effect of setting system-wide

1164

defaults. Changing the fields after threads have started is not recommended as

1165

it would require thread synchronization to prevent race conditions.

1166

In single threaded environments, it is preferable to not use this context at

1167

all. Instead, simply create contexts explicitly as described below.

1168

The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled traps

1169

for Overflow, InvalidOperation, and DivisionByZero.

1170

</dd></dl>

1171

1172

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

1173

<a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a> constructor.

1174

1175

1176

class <code class="descclassname">decimal.</code><code class="descname">Context</code>(prec=None, rounding=None, traps=None, flags=None, Emin=None, Emax=None, capitals=1)<a class="headerlink" href="#decimal.Context" title="Permalink to this definition">¶</a></dt>

1177

<dd>Creates a new context. If a field is not specified or is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>, the

1178

default values are copied from the <a class="reference internal" href="#decimal.DefaultContext" title="decimal.DefaultContext"><code class="xref py py-const docutils literal">DefaultContext</code></a>. If the flags

1179

field is not specified or is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>, all flags are cleared.

1180

The prec field is a positive integer that sets the precision for arithmetic

1181

operations in the context.

1182

The rounding option is one of:

1183

1184

<li><code class="xref py py-const docutils literal">ROUND_CEILING</code> (towards <code class="xref py py-const docutils literal">Infinity</code>),</li>

1185

<li><code class="xref py py-const docutils literal">ROUND_DOWN</code> (towards zero),</li>

1186

<li><code class="xref py py-const docutils literal">ROUND_FLOOR</code> (towards <code class="xref py py-const docutils literal">-Infinity</code>),</li>

1187

<li><code class="xref py py-const docutils literal">ROUND_HALF_DOWN</code> (to nearest with ties going towards zero),</li>

1188

<li><code class="xref py py-const docutils literal">ROUND_HALF_EVEN</code> (to nearest with ties going to nearest even integer),</li>

1189

<li><code class="xref py py-const docutils literal">ROUND_HALF_UP</code> (to nearest with ties going away from zero), or</li>

1190

<li><code class="xref py py-const docutils literal">ROUND_UP</code> (away from zero).</li>

1191

<li><code class="xref py py-const docutils literal">ROUND_05UP</code> (away from zero if last digit after rounding towards zero

1192

would have been 0 or 5; otherwise towards zero)</li>

1193

</ul>

1194

The traps and flags fields list any signals to be set. Generally, new

1195

contexts should only set traps and leave the flags clear.

1196

The Emin and Emax fields are integers specifying the outer limits allowable

1197

for exponents.

1198

The capitals field is either <code class="xref py py-const docutils literal">0</code> or <code class="xref py py-const docutils literal">1</code> (the default). If set to

1199

<code class="xref py py-const docutils literal">1</code>, exponents are printed with a capital <code class="xref py py-const docutils literal">E</code>; otherwise, a

1200

lowercase <code class="xref py py-const docutils literal">e</code> is used: <code class="xref py py-const docutils literal">Decimal('6.02e+23')</code>.

1201

1202

Changed in version 2.6: The <code class="xref py py-const docutils literal">ROUND_05UP</code> rounding mode was added.

1203

</div>

1204

The <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a> class defines several general purpose methods as well as

1205

a large number of methods for doing arithmetic directly in a given context.

1206

In addition, for each of the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> methods described above (with

1207

the exception of the <code class="xref py py-meth docutils literal">adjusted()</code> and <code class="xref py py-meth docutils literal">as_tuple()</code> methods) there is

1208

a corresponding <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a> method. For example, for a <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a>

1209

instance <code class="docutils literal">C</code> and <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> instance <code class="docutils literal">x</code>, <code class="docutils literal">C.exp(x)</code> is

1210

equivalent to <code class="docutils literal">x.exp(context=C)</code>. Each <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a> method accepts a

1211

Python integer (an instance of <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a> or <a class="reference internal" href="functions.html#long" title="long"><code class="xref py py-class docutils literal">long</code></a>) anywhere that a

1212

Decimal instance is accepted.

1213

1214

1215

<code class="descname">clear_flags</code>()<a class="headerlink" href="#decimal.Context.clear_flags" title="Permalink to this definition">¶</a></dt>

1216

<dd>Resets all of the flags to <code class="xref py py-const docutils literal">0</code>.

1217

</dd></dl>

1218

1219

1220

1221

1222

<dd>Return a duplicate of the context.

1223

</dd></dl>

1224

1225

1226

1227

<code class="descname">copy_decimal</code>(num)<a class="headerlink" href="#decimal.Context.copy_decimal" title="Permalink to this definition">¶</a></dt>

1228

<dd>Return a copy of the Decimal instance num.

1229

</dd></dl>

1230

1231

1232

1233

<code class="descname">create_decimal</code>(num)<a class="headerlink" href="#decimal.Context.create_decimal" title="Permalink to this definition">¶</a></dt>

1234

<dd>Creates a new Decimal instance from num but using self as

1235

context. Unlike the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> constructor, the context precision,

1236

rounding method, flags, and traps are applied to the conversion.

1237

This is useful because constants are often given to a greater precision

1238

than is needed by the application. Another benefit is that rounding

1239

immediately eliminates unintended effects from digits beyond the current

1240

precision. In the following example, using unrounded inputs means that

1241

adding zero to a sum can change the result:

1242

1243

1244

Decimal('4.45')

1245

>>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')

1246

Decimal('4.44')

1247

</pre></div>

1248

</div>

1249

This method implements the to-number operation of the IBM specification.

1250

If the argument is a string, no leading or trailing whitespace is

1251

permitted.

1252

</dd></dl>

1253

1254

1255

1256

<code class="descname">create_decimal_from_float</code>(f)<a class="headerlink" href="#decimal.Context.create_decimal_from_float" title="Permalink to this definition">¶</a></dt>

1257

<dd>Creates a new Decimal instance from a float f but rounding using self

1258

as the context. Unlike the <a class="reference internal" href="#decimal.Decimal.from_float" title="decimal.Decimal.from_float"><code class="xref py py-meth docutils literal">Decimal.from_float()</code></a> class method,

1259

the context precision, rounding method, flags, and traps are applied to

1260

the conversion.

1261

<div class="highlight-python"><div class="highlight"><pre>>>> context = Context(prec=5, rounding=ROUND_DOWN)

1262

>>> context.create_decimal_from_float(math.pi)

1263

Decimal('3.1415')

1264

>>> context = Context(prec=5, traps=[Inexact])

1265

1266

Traceback (most recent call last):

1267

...

1268

Inexact: None

1269

</pre></div>

1270

</div>

1271

1272

New in version 2.7.

1273

</div>

1274

</dd></dl>

1275

1276

1277

1278

<code class="descname">Etiny</code>()<a class="headerlink" href="#decimal.Context.Etiny" title="Permalink to this definition">¶</a></dt>

1279

<dd>Returns a value equal to <code class="docutils literal">Emin - prec + 1</code> which is the minimum exponent

1280

value for subnormal results. When underflow occurs, the exponent is set

1281

to <a class="reference internal" href="#decimal.Context.Etiny" title="decimal.Context.Etiny"><code class="xref py py-const docutils literal">Etiny</code></a>.

1282

</dd></dl>

1283

1284

1285

1286

1287

<dd>Returns a value equal to <code class="docutils literal">Emax - prec + 1</code>.

1288

</dd></dl>

1289

1290

The usual approach to working with decimals is to create <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a>

1291

instances and then apply arithmetic operations which take place within the

1292

current context for the active thread. An alternative approach is to use

1293

context methods for calculating within a specific context. The methods are

1294

similar to those for the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> class and are only briefly

1295

recounted here.

1296

1297

1298

1299

<dd>Returns the absolute value of x.

1300

</dd></dl>

1301

1302

1303

1304

1305

<dd>Return the sum of x and y.

1306

</dd></dl>

1307

1308

1309

1310

<code class="descname">canonical</code>(x)<a class="headerlink" href="#decimal.Context.canonical" title="Permalink to this definition">¶</a></dt>

1311

<dd>Returns the same Decimal object x.

1312

</dd></dl>

1313

1314

1315

1316

<code class="descname">compare</code>(x, y)<a class="headerlink" href="#decimal.Context.compare" title="Permalink to this definition">¶</a></dt>

1317

<dd>Compares x and y numerically.

1318

</dd></dl>

1319

1320

1321

1322

<code class="descname">compare_signal</code>(x, y)<a class="headerlink" href="#decimal.Context.compare_signal" title="Permalink to this definition">¶</a></dt>

1323

<dd>Compares the values of the two operands numerically.

1324

</dd></dl>

1325

1326

1327

1328

<code class="descname">compare_total</code>(x, y)<a class="headerlink" href="#decimal.Context.compare_total" title="Permalink to this definition">¶</a></dt>

1329

<dd>Compares two operands using their abstract representation.

1330

</dd></dl>

1331

1332

1333

1334

<code class="descname">compare_total_mag</code>(x, y)<a class="headerlink" href="#decimal.Context.compare_total_mag" title="Permalink to this definition">¶</a></dt>

1335

<dd>Compares two operands using their abstract representation, ignoring sign.

1336

</dd></dl>

1337

1338

1339

1340

1341

<dd>Returns a copy of x with the sign set to 0.

1342

</dd></dl>

1343

1344

1345

1346

<code class="descname">copy_negate</code>(x)<a class="headerlink" href="#decimal.Context.copy_negate" title="Permalink to this definition">¶</a></dt>

1347

<dd>Returns a copy of x with the sign inverted.

1348

</dd></dl>

1349

1350

1351

1352

1353

<dd>Copies the sign from y to x.

1354

</dd></dl>

1355

1356

1357

1358

<code class="descname">divide</code>(x, y)<a class="headerlink" href="#decimal.Context.divide" title="Permalink to this definition">¶</a></dt>

1359

<dd>Return x divided by y.

1360

</dd></dl>

1361

1362

1363

1364

<code class="descname">divide_int</code>(x, y)<a class="headerlink" href="#decimal.Context.divide_int" title="Permalink to this definition">¶</a></dt>

1365

<dd>Return x divided by y, truncated to an integer.

1366

</dd></dl>

1367

1368

1369

1370

<code class="descname">divmod</code>(x, y)<a class="headerlink" href="#decimal.Context.divmod" title="Permalink to this definition">¶</a></dt>

1371

<dd>Divides two numbers and returns the integer part of the result.

1372

</dd></dl>

1373

1374

1375

1376

1377

<dd>Returns <cite>e ** x</cite>.

1378

</dd></dl>

1379

1380

1381

1382

1383

<dd>Returns x multiplied by y, plus z.

1384

</dd></dl>

1385

1386

1387

1388

<code class="descname">is_canonical</code>(x)<a class="headerlink" href="#decimal.Context.is_canonical" title="Permalink to this definition">¶</a></dt>

1389

<dd>Returns <code class="docutils literal">True</code> if x is canonical; otherwise returns <code class="docutils literal">False</code>.

1390

</dd></dl>

1391

1392

1393

1394

<code class="descname">is_finite</code>(x)<a class="headerlink" href="#decimal.Context.is_finite" title="Permalink to this definition">¶</a></dt>

1395

<dd>Returns <code class="docutils literal">True</code> if x is finite; otherwise returns <code class="docutils literal">False</code>.

1396

</dd></dl>

1397

1398

1399

1400

<code class="descname">is_infinite</code>(x)<a class="headerlink" href="#decimal.Context.is_infinite" title="Permalink to this definition">¶</a></dt>

1401

<dd>Returns <code class="docutils literal">True</code> if x is infinite; otherwise returns <code class="docutils literal">False</code>.

1402

</dd></dl>

1403

1404

1405

1406

1407

<dd>Returns <code class="docutils literal">True</code> if x is a qNaN or sNaN; otherwise returns <code class="docutils literal">False</code>.

1408

</dd></dl>

1409

1410

1411

1412

<code class="descname">is_normal</code>(x)<a class="headerlink" href="#decimal.Context.is_normal" title="Permalink to this definition">¶</a></dt>

1413

<dd>Returns <code class="docutils literal">True</code> if x is a normal number; otherwise returns <code class="docutils literal">False</code>.

1414

</dd></dl>

1415

1416

1417

1418

1419

<dd>Returns <code class="docutils literal">True</code> if x is a quiet NaN; otherwise returns <code class="docutils literal">False</code>.

1420

</dd></dl>

1421

1422

1423

1424

<code class="descname">is_signed</code>(x)<a class="headerlink" href="#decimal.Context.is_signed" title="Permalink to this definition">¶</a></dt>

1425

<dd>Returns <code class="docutils literal">True</code> if x is negative; otherwise returns <code class="docutils literal">False</code>.

1426

</dd></dl>

1427

1428

1429

1430

1431

<dd>Returns <code class="docutils literal">True</code> if x is a signaling NaN; otherwise returns <code class="docutils literal">False</code>.

1432

</dd></dl>

1433

1434

1435

1436

<code class="descname">is_subnormal</code>(x)<a class="headerlink" href="#decimal.Context.is_subnormal" title="Permalink to this definition">¶</a></dt>

1437

<dd>Returns <code class="docutils literal">True</code> if x is subnormal; otherwise returns <code class="docutils literal">False</code>.

1438

</dd></dl>

1439

1440

1441

1442

1443

<dd>Returns <code class="docutils literal">True</code> if x is a zero; otherwise returns <code class="docutils literal">False</code>.

1444

</dd></dl>

1445

1446

1447

1448

1449

<dd>Returns the natural (base e) logarithm of x.

1450

</dd></dl>

1451

1452

1453

1454

1455

<dd>Returns the base 10 logarithm of x.

1456

</dd></dl>

1457

1458

1459

1460

1461

<dd>Returns the exponent of the magnitude of the operand’s MSD.

1462

</dd></dl>

1463

1464

1465

1466

<code class="descname">logical_and</code>(x, y)<a class="headerlink" href="#decimal.Context.logical_and" title="Permalink to this definition">¶</a></dt>

1467

<dd>Applies the logical operation and between each operand’s digits.

1468

</dd></dl>

1469

1470

1471

1472

<code class="descname">logical_invert</code>(x)<a class="headerlink" href="#decimal.Context.logical_invert" title="Permalink to this definition">¶</a></dt>

1473

<dd>Invert all the digits in x.

1474

</dd></dl>

1475

1476

1477

1478

<code class="descname">logical_or</code>(x, y)<a class="headerlink" href="#decimal.Context.logical_or" title="Permalink to this definition">¶</a></dt>

1479

<dd>Applies the logical operation or between each operand’s digits.

1480

</dd></dl>

1481

1482

1483

1484

<code class="descname">logical_xor</code>(x, y)<a class="headerlink" href="#decimal.Context.logical_xor" title="Permalink to this definition">¶</a></dt>

1485

<dd>Applies the logical operation xor between each operand’s digits.

1486

</dd></dl>

1487

1488

1489

1490

1491

<dd>Compares two values numerically and returns the maximum.

1492

</dd></dl>

1493

1494

1495

1496

1497

<dd>Compares the values numerically with their sign ignored.

1498

</dd></dl>

1499

1500

1501

1502

1503

<dd>Compares two values numerically and returns the minimum.

1504

</dd></dl>

1505

1506

1507

1508

1509

<dd>Compares the values numerically with their sign ignored.

1510

</dd></dl>

1511

1512

1513

1514

<code class="descname">minus</code>(x)<a class="headerlink" href="#decimal.Context.minus" title="Permalink to this definition">¶</a></dt>

1515

<dd>Minus corresponds to the unary prefix minus operator in Python.

1516

</dd></dl>

1517

1518

1519

1520

<code class="descname">multiply</code>(x, y)<a class="headerlink" href="#decimal.Context.multiply" title="Permalink to this definition">¶</a></dt>

1521

<dd>Return the product of x and y.

1522

</dd></dl>

1523

1524

1525

1526

<code class="descname">next_minus</code>(x)<a class="headerlink" href="#decimal.Context.next_minus" title="Permalink to this definition">¶</a></dt>

1527

<dd>Returns the largest representable number smaller than x.

1528

</dd></dl>

1529

1530

1531

1532

1533

<dd>Returns the smallest representable number larger than x.

1534

</dd></dl>

1535

1536

1537

1538

<code class="descname">next_toward</code>(x, y)<a class="headerlink" href="#decimal.Context.next_toward" title="Permalink to this definition">¶</a></dt>

1539

<dd>Returns the number closest to x, in direction towards y.

1540

</dd></dl>

1541

1542

1543

1544

<code class="descname">normalize</code>(x)<a class="headerlink" href="#decimal.Context.normalize" title="Permalink to this definition">¶</a></dt>

1545

<dd>Reduces x to its simplest form.

1546

</dd></dl>

1547

1548

1549

1550

<code class="descname">number_class</code>(x)<a class="headerlink" href="#decimal.Context.number_class" title="Permalink to this definition">¶</a></dt>

1551

<dd>Returns an indication of the class of x.

1552

</dd></dl>

1553

1554

1555

1556

1557

<dd>Plus corresponds to the unary prefix plus operator in Python. This

1558

operation applies the context precision and rounding, so it is not an

1559

identity operation.

1560

</dd></dl>

1561

1562

1563

1564

<code class="descname">power</code>(x, y[, modulo])<a class="headerlink" href="#decimal.Context.power" title="Permalink to this definition">¶</a></dt>

1565

<dd>Return <code class="docutils literal">x</code> to the power of <code class="docutils literal">y</code>, reduced modulo <code class="docutils literal">modulo</code> if given.

1566

With two arguments, compute <code class="docutils literal">x**y</code>. If <code class="docutils literal">x</code> is negative then <code class="docutils literal">y</code>

1567

must be integral. The result will be inexact unless <code class="docutils literal">y</code> is integral and

1568

the result is finite and can be expressed exactly in ‘precision’ digits.

1569

The result should always be correctly rounded, using the rounding mode of

1570

the current thread’s context.

1571

With three arguments, compute <code class="docutils literal">(x**y) % modulo</code>. For the three argument

1572

form, the following restrictions on the arguments hold:

1573

1574

1575

<li>all three arguments must be integral</li>

1576

<li><code class="docutils literal">y</code> must be nonnegative</li>

1577

<li>at least one of <code class="docutils literal">x</code> or <code class="docutils literal">y</code> must be nonzero</li>

1578

<li><code class="docutils literal">modulo</code> must be nonzero and have at most ‘precision’ digits</li>

1579

</ul>

1580

</div></blockquote>

1581

The value resulting from <code class="docutils literal">Context.power(x, y, modulo)</code> is

1582

equal to the value that would be obtained by computing <code class="docutils literal">(x**y)

1583

% modulo</code> with unbounded precision, but is computed more

1584

efficiently. The exponent of the result is zero, regardless of

1585

the exponents of <code class="docutils literal">x</code>, <code class="docutils literal">y</code> and <code class="docutils literal">modulo</code>. The result is

1586

always exact.

1587

1588

Changed in version 2.6: <code class="docutils literal">y</code> may now be nonintegral in <code class="docutils literal">x**y</code>.

1589

Stricter requirements for the three-argument version.

1590

</div>

1591

</dd></dl>

1592

1593

1594

1595

<code class="descname">quantize</code>(x, y)<a class="headerlink" href="#decimal.Context.quantize" title="Permalink to this definition">¶</a></dt>

1596

<dd>Returns a value equal to x (rounded), having the exponent of y.

1597

</dd></dl>

1598

1599

1600

1601

<code class="descname">radix</code>()<a class="headerlink" href="#decimal.Context.radix" title="Permalink to this definition">¶</a></dt>

1602

<dd>Just returns 10, as this is Decimal, :)

1603

</dd></dl>

1604

1605

1606

1607

<code class="descname">remainder</code>(x, y)<a class="headerlink" href="#decimal.Context.remainder" title="Permalink to this definition">¶</a></dt>

1608

<dd>Returns the remainder from integer division.

1609

The sign of the result, if non-zero, is the same as that of the original

1610

dividend.

1611

</dd></dl>

1612

1613

1614

1615

<code class="descname">remainder_near</code>(x, y)<a class="headerlink" href="#decimal.Context.remainder_near" title="Permalink to this definition">¶</a></dt>

1616

<dd>Returns <code class="docutils literal">x - y * n</code>, where n is the integer nearest the exact value

1617

of <code class="docutils literal">x / y</code> (if the result is 0 then its sign will be the sign of x).

1618

</dd></dl>

1619

1620

1621

1622

<code class="descname">rotate</code>(x, y)<a class="headerlink" href="#decimal.Context.rotate" title="Permalink to this definition">¶</a></dt>

1623

<dd>Returns a rotated copy of x, y times.

1624

</dd></dl>

1625

1626

1627

1628

<code class="descname">same_quantum</code>(x, y)<a class="headerlink" href="#decimal.Context.same_quantum" title="Permalink to this definition">¶</a></dt>

1629

<dd>Returns <code class="docutils literal">True</code> if the two operands have the same exponent.

1630

</dd></dl>

1631

1632

1633

1634

<code class="descname">scaleb</code>(x, y)<a class="headerlink" href="#decimal.Context.scaleb" title="Permalink to this definition">¶</a></dt>

1635

<dd>Returns the first operand after adding the second value its exp.

1636

</dd></dl>

1637

1638

1639

1640

<code class="descname">shift</code>(x, y)<a class="headerlink" href="#decimal.Context.shift" title="Permalink to this definition">¶</a></dt>

1641

<dd>Returns a shifted copy of x, y times.

1642

</dd></dl>

1643

1644

1645

1646

1647

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

1648

</dd></dl>

1649

1650

1651

1652

<code class="descname">subtract</code>(x, y)<a class="headerlink" href="#decimal.Context.subtract" title="Permalink to this definition">¶</a></dt>

1653

<dd>Return the difference between x and y.

1654

</dd></dl>

1655

1656

1657

1658

<code class="descname">to_eng_string</code>(x)<a class="headerlink" href="#decimal.Context.to_eng_string" title="Permalink to this definition">¶</a></dt>

1659

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

1660

Engineering notation has an exponent which is a multiple of 3. This

1661

can leave up to 3 digits to the left of the decimal place and may

1662

require the addition of either one or two trailing zeros.

1663

</dd></dl>

1664

1665

1666

1667

<code class="descname">to_integral_exact</code>(x)<a class="headerlink" href="#decimal.Context.to_integral_exact" title="Permalink to this definition">¶</a></dt>

1668

<dd>Rounds to an integer.

1669

</dd></dl>

1670

1671

1672

1673

<code class="descname">to_sci_string</code>(x)<a class="headerlink" href="#decimal.Context.to_sci_string" title="Permalink to this definition">¶</a></dt>

1674

<dd>Converts a number to a string using scientific notation.

1675

</dd></dl>

1676

1677

</dd></dl>

1678

1679

</div>

1680

1681

<h2>9.4.4. Signals<a class="headerlink" href="#signals" title="Permalink to this headline">¶</a></h2>

1682

Signals represent conditions that arise during computation. Each corresponds to

1683

one context flag and one context trap enabler.

1684

The context flag is set whenever the condition is encountered. After the

1685

computation, flags may be checked for informational purposes (for instance, to

1686

determine whether a computation was exact). After checking the flags, be sure to

1687

clear all flags before starting the next computation.

1688

If the context’s trap enabler is set for the signal, then the condition causes a

1689

Python exception to be raised. For example, if the <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-class docutils literal">DivisionByZero</code></a> trap

1690

is set, then a <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-exc docutils literal">DivisionByZero</code></a> exception is raised upon encountering the

1691

condition.

1692

1693

1694

class <code class="descclassname">decimal.</code><code class="descname">Clamped</code><a class="headerlink" href="#decimal.Clamped" title="Permalink to this definition">¶</a></dt>

1695

<dd>Altered an exponent to fit representation constraints.

1696

Typically, clamping occurs when an exponent falls outside the context’s

1697

<code class="xref py py-attr docutils literal">Emin</code> and <code class="xref py py-attr docutils literal">Emax</code> limits. If possible, the exponent is reduced to

1698

fit by adding zeros to the coefficient.

1699

</dd></dl>

1700

1701

1702

1703

class <code class="descclassname">decimal.</code><code class="descname">DecimalException</code><a class="headerlink" href="#decimal.DecimalException" title="Permalink to this definition">¶</a></dt>

1704

<dd>Base class for other signals and a subclass of <a class="reference internal" href="exceptions.html#exceptions.ArithmeticError" title="exceptions.ArithmeticError"><code class="xref py py-exc docutils literal">ArithmeticError</code></a>.

1705

</dd></dl>

1706

1707

1708

1709

class <code class="descclassname">decimal.</code><code class="descname">DivisionByZero</code><a class="headerlink" href="#decimal.DivisionByZero" title="Permalink to this definition">¶</a></dt>

1710

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

1711

Can occur with division, modulo division, or when raising a number to a negative

1712

power. If this signal is not trapped, returns <code class="xref py py-const docutils literal">Infinity</code> or

1713

<code class="xref py py-const docutils literal">-Infinity</code> with the sign determined by the inputs to the calculation.

1714

</dd></dl>

1715

1716

1717

1718

class <code class="descclassname">decimal.</code><code class="descname">Inexact</code><a class="headerlink" href="#decimal.Inexact" title="Permalink to this definition">¶</a></dt>

1719

<dd>Indicates that rounding occurred and the result is not exact.

1720

Signals when non-zero digits were discarded during rounding. The rounded result

1721

is returned. The signal flag or trap is used to detect when results are

1722

inexact.

1723

</dd></dl>

1724

1725

1726

1727

class <code class="descclassname">decimal.</code><code class="descname">InvalidOperation</code><a class="headerlink" href="#decimal.InvalidOperation" title="Permalink to this definition">¶</a></dt>

1728

<dd>An invalid operation was performed.

1729

Indicates that an operation was requested that does not make sense. If not

1730

trapped, returns <code class="xref py py-const docutils literal">NaN</code>. Possible causes include:

1731

<div class="highlight-python"><div class="highlight"><pre>Infinity - Infinity

1732

0 * Infinity

1733

Infinity / Infinity

1734

x % 0

1735

Infinity % x

1736

x._rescale( non-integer )

1737

sqrt(-x) and x > 0

1738

0 ** 0

1739

x ** (non-integer)

1740

x ** Infinity

1741

</pre></div>

1742

</div>

1743

</dd></dl>

1744

1745

1746

1747

class <code class="descclassname">decimal.</code><code class="descname">Overflow</code><a class="headerlink" href="#decimal.Overflow" title="Permalink to this definition">¶</a></dt>

1748

<dd>Numerical overflow.

1749

Indicates the exponent is larger than <code class="xref py py-attr docutils literal">Emax</code> after rounding has

1750

occurred. If not trapped, the result depends on the rounding mode, either

1751

pulling inward to the largest representable finite number or rounding outward

1752

to <code class="xref py py-const docutils literal">Infinity</code>. In either case, <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-class docutils literal">Inexact</code></a> and <a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-class docutils literal">Rounded</code></a>

1753

are also signaled.

1754

</dd></dl>

1755

1756

1757

1758

class <code class="descclassname">decimal.</code><code class="descname">Rounded</code><a class="headerlink" href="#decimal.Rounded" title="Permalink to this definition">¶</a></dt>

1759

<dd>Rounding occurred though possibly no information was lost.

1760

Signaled whenever rounding discards digits; even if those digits are zero

1761

(such as rounding <code class="xref py py-const docutils literal">5.00</code> to <code class="xref py py-const docutils literal">5.0</code>). If not trapped, returns

1762

the result unchanged. This signal is used to detect loss of significant

1763

digits.

1764

</dd></dl>

1765

1766

1767

1768

class <code class="descclassname">decimal.</code><code class="descname">Subnormal</code><a class="headerlink" href="#decimal.Subnormal" title="Permalink to this definition">¶</a></dt>

1769

<dd>Exponent was lower than <code class="xref py py-attr docutils literal">Emin</code> prior to rounding.

1770

Occurs when an operation result is subnormal (the exponent is too small). If

1771

not trapped, returns the result unchanged.

1772

</dd></dl>

1773

1774

1775

1776

class <code class="descclassname">decimal.</code><code class="descname">Underflow</code><a class="headerlink" href="#decimal.Underflow" title="Permalink to this definition">¶</a></dt>

1777

<dd>Numerical underflow with result rounded to zero.

1778

Occurs when a subnormal result is pushed to zero by rounding. <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-class docutils literal">Inexact</code></a>

1779

and <a class="reference internal" href="#decimal.Subnormal" title="decimal.Subnormal"><code class="xref py py-class docutils literal">Subnormal</code></a> are also signaled.

1780

</dd></dl>

1781

1782

The following table summarizes the hierarchy of signals:

1783

<div class="highlight-python"><div class="highlight"><pre>exceptions.ArithmeticError(exceptions.StandardError)

1784

DecimalException

1785

Clamped

1786

DivisionByZero(DecimalException, exceptions.ZeroDivisionError)

1787

Inexact

1788

Overflow(Inexact, Rounded)

1789

Underflow(Inexact, Rounded, Subnormal)

1790

InvalidOperation

1791

Rounded

1792

Subnormal

1793

</pre></div>

1794

</div>

1795

</div>

1796

1797

<h2>9.4.5. Floating Point Notes<a class="headerlink" href="#floating-point-notes" title="Permalink to this headline">¶</a></h2>

1798

1799

<h3>9.4.5.1. Mitigating round-off error with increased precision<a class="headerlink" href="#mitigating-round-off-error-with-increased-precision" title="Permalink to this headline">¶</a></h3>

1800

The use of decimal floating point eliminates decimal representation error

1801

(making it possible to represent <code class="xref py py-const docutils literal">0.1</code> exactly); however, some operations

1802

can still incur round-off error when non-zero digits exceed the fixed precision.

1803

The effects of round-off error can be amplified by the addition or subtraction

1804

of nearly offsetting quantities resulting in loss of significance. Knuth

1805

provides two instructive examples where rounded floating point arithmetic with

1806

insufficient precision causes the breakdown of the associative and distributive

1807

properties of addition:

1808

<div class="highlight-python"><div class="highlight"><pre># Examples from Seminumerical Algorithms, Section 4.2.2.

1809

>>> from decimal import Decimal, getcontext

1810

>>> getcontext().prec = 8

1811

1812

>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')

1813

>>> (u + v) + w

1814

Decimal('9.5111111')

1815

>>> u + (v + w)

1816

Decimal('10')

1817

1818

>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')

1819

>>> (u*v) + (u*w)

1820

Decimal('0.01')

1821

>>> u * (v+w)

1822

Decimal('0.0060000')

1823

</pre></div>

1824

</div>

1825

1826

expanding the precision sufficiently to avoid loss of significance:

1827

1828

>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')

1829

>>> (u + v) + w

1830

Decimal('9.51111111')

1831

>>> u + (v + w)

1832

Decimal('9.51111111')

1833

>>>

1834

>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')

1835

>>> (u*v) + (u*w)

1836

Decimal('0.0060000')

1837

>>> u * (v+w)

1838

Decimal('0.0060000')

1839

</pre></div>

1840

</div>

1841

</div>

1842

1843

<h3>9.4.5.2. Special values<a class="headerlink" href="#special-values" title="Permalink to this headline">¶</a></h3>

1844

The number system for the <a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal">decimal</code></a> module provides special values

1845

including <code class="xref py py-const docutils literal">NaN</code>, <code class="xref py py-const docutils literal">sNaN</code>, <code class="xref py py-const docutils literal">-Infinity</code>, <code class="xref py py-const docutils literal">Infinity</code>,

1846

and two zeros, <code class="xref py py-const docutils literal">+0</code> and <code class="xref py py-const docutils literal">-0</code>.

1847

Infinities can be constructed directly with: <code class="docutils literal">Decimal('Infinity')</code>. Also,

1848

they can arise from dividing by zero when the <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-exc docutils literal">DivisionByZero</code></a> signal is

1849

not trapped. Likewise, when the <a class="reference internal" href="#decimal.Overflow" title="decimal.Overflow"><code class="xref py py-exc docutils literal">Overflow</code></a> signal is not trapped, infinity

1850

can result from rounding beyond the limits of the largest representable number.

1851

The infinities are signed (affine) and can be used in arithmetic operations

1852

where they get treated as very large, indeterminate numbers. For instance,

1853

adding a constant to infinity gives another infinite result.

1854

Some operations are indeterminate and return <code class="xref py py-const docutils literal">NaN</code>, or if the

1855

<a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-exc docutils literal">InvalidOperation</code></a> signal is trapped, raise an exception. For example,

1856

<code class="docutils literal">0/0</code> returns <code class="xref py py-const docutils literal">NaN</code> which means “not a number”. This variety of

1857

<code class="xref py py-const docutils literal">NaN</code> is quiet and, once created, will flow through other computations

1858

always resulting in another <code class="xref py py-const docutils literal">NaN</code>. This behavior can be useful for a

1859

series of computations that occasionally have missing inputs — it allows the

1860

calculation to proceed while flagging specific results as invalid.

1861

A variant is <code class="xref py py-const docutils literal">sNaN</code> which signals rather than remaining quiet after every

1862

operation. This is a useful return value when an invalid result needs to

1863

interrupt a calculation for special handling.

1864

The behavior of Python’s comparison operators can be a little surprising where a

1865

<code class="xref py py-const docutils literal">NaN</code> is involved. A test for equality where one of the operands is a

1866

quiet or signaling <code class="xref py py-const docutils literal">NaN</code> always returns <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> (even when doing

1867

<code class="docutils literal">Decimal('NaN')==Decimal('NaN')</code>), while a test for inequality always returns

1868

<a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a>. An attempt to compare two Decimals using any of the <code class="docutils literal"><</code>,

1869

<code class="docutils literal"><=</code>, <code class="docutils literal">></code> or <code class="docutils literal">>=</code> operators will raise the <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-exc docutils literal">InvalidOperation</code></a> signal

1870

if either operand is a <code class="xref py py-const docutils literal">NaN</code>, and return <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> if this signal is

1871

not trapped. Note that the General Decimal Arithmetic specification does not

1872

specify the behavior of direct comparisons; these rules for comparisons

1873

involving a <code class="xref py py-const docutils literal">NaN</code> were taken from the IEEE 854 standard (see Table 3 in

1874

section 5.7). To ensure strict standards-compliance, use the <code class="xref py py-meth docutils literal">compare()</code>

1875

and <code class="xref py py-meth docutils literal">compare-signal()</code> methods instead.

1876

The signed zeros can result from calculations that underflow. They keep the sign

1877

that would have resulted if the calculation had been carried out to greater

1878

precision. Since their magnitude is zero, both positive and negative zeros are

1879

treated as equal and their sign is informational.

1880

In addition to the two signed zeros which are distinct yet equal, there are

1881

various representations of zero with differing precisions yet equivalent in

1882

value. This takes a bit of getting used to. For an eye accustomed to

1883

normalized floating point representations, it is not immediately obvious that

1884

the following calculation returns a value equal to zero:

1885

<div class="highlight-python"><div class="highlight"><pre>>>> 1 / Decimal('Infinity')

1886

Decimal('0E-1000000026')

1887

</pre></div>

1888

</div>

1889

</div>

1890

</div>

1891

1892

<h2>9.4.6. Working with threads<a class="headerlink" href="#working-with-threads" title="Permalink to this headline">¶</a></h2>

1893

The <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal">getcontext()</code></a> function accesses a different <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal">Context</code></a> object for

1894

each thread. Having separate thread contexts means that threads may make

1895

changes (such as <code class="docutils literal">getcontext.prec=10</code>) without interfering with other threads.

1896

Likewise, the <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal">setcontext()</code></a> function automatically assigns its target to

1897

the current thread.

1898

If <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal">setcontext()</code></a> has not been called before <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal">getcontext()</code></a>, then

1899

1900

current thread.

1901

The new context is copied from a prototype context called DefaultContext. To

1902

control the defaults so that each thread will use the same values throughout the

1903

application, directly modify the DefaultContext object. This should be done

1904

before any threads are started so that there won’t be a race condition between

1905

threads calling <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal">getcontext()</code></a>. For example:

1906

<div class="highlight-python"><div class="highlight"><pre># Set applicationwide defaults for all threads about to be launched

1907

DefaultContext.prec = 12

1908

DefaultContext.rounding = ROUND_DOWN

1909

DefaultContext.traps = ExtendedContext.traps.copy()

1910

DefaultContext.traps[InvalidOperation] = 1

1911

setcontext(DefaultContext)

1912

1913

# Afterwards, the threads can be started

1914

t1.start()

1915

t2.start()

1916

t3.start()

1917

. . .

1918

</pre></div>

1919

</div>

1920

</div>

1921

1922

<h2>9.4.7. Recipes<a class="headerlink" href="#recipes" title="Permalink to this headline">¶</a></h2>

1923

Here are a few recipes that serve as utility functions and that demonstrate ways

1924

to work with the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a> class:

1925

<div class="highlight-python"><div class="highlight"><pre>def moneyfmt(value, places=2, curr='', sep=',', dp='.',

1926

pos='', neg='-', trailneg=''):

1927

"""Convert Decimal to a money formatted string.

1928

1929

places: required number of places after the decimal point

1930

curr: optional currency symbol before the sign (may be blank)

1931

sep: optional grouping separator (comma, period, space, or blank)

1932

dp: decimal point indicator (comma or period)

1933

only specify as blank when places is zero

1934

pos: optional sign for positive numbers: '+', space or blank

1935

neg: optional sign for negative numbers: '-', '(', space or blank

1936

trailneg:optional trailing minus indicator: '-', ')', space or blank

1937

1938

>>> d = Decimal('-1234567.8901')

1939

>>> moneyfmt(d, curr='$')

1940

'-$1,234,567.89'

1941

>>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')

1942

'1.234.568-'

1943

>>> moneyfmt(d, curr='$', neg='(', trailneg=')')

1944

'($1,234,567.89)'

1945

>>> moneyfmt(Decimal(123456789), sep=' ')

1946

'123 456 789.00'

1947

>>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')

1948

'<0.02>'

1949

1950

"""

1951

q = Decimal(10) ** -places # 2 places --> '0.01'

1952

sign, digits, exp = value.quantize(q).as_tuple()

1953

result = []

1954

digits = map(str, digits)

1955

build, next = result.append, digits.pop

1956

if sign:

1957

build(trailneg)

1958

for i in range(places):

1959

build(next() if digits else '0')

1960

build(dp)

1961

if not digits:

1962

build('0')

1963

i = 0

1964

while digits:

1965

build(next())

1966

i += 1

1967

if i == 3 and digits:

1968

i = 0

1969

build(sep)

1970

build(curr)

1971

build(neg if sign else pos)

1972

return ''.join(reversed(result))

1973

1974

def pi():

1975

"""Compute Pi to the current precision.

1976

1977

>>> print pi()

1978

3.141592653589793238462643383

1979

1980

"""

1981

getcontext().prec += 2 # extra digits for intermediate steps

1982

three = Decimal(3) # substitute "three=3.0" for regular floats

1983

lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24

1984

while s != lasts:

1985

lasts = s

1986

n, na = n+na, na+8

1987

d, da = d+da, da+32

1988

t = (t * n) / d

1989

s += t

1990

getcontext().prec -= 2

1991

return +s # unary plus applies the new precision

1992

1993

def exp(x):

1994

"""Return e raised to the power of x. Result type matches input type.

1995

1996

>>> print exp(Decimal(1))

1997

2.718281828459045235360287471

1998

>>> print exp(Decimal(2))

1999

7.389056098930650227230427461

2000

>>> print exp(2.0)

2001

7.38905609893

2002

>>> print exp(2+0j)

2003

(7.38905609893+0j)

2004

2005

"""

2006

getcontext().prec += 2

2007

i, lasts, s, fact, num = 0, 0, 1, 1, 1

2008

while s != lasts:

2009

lasts = s

2010

i += 1

2011

fact *= i

2012

num *= x

2013

s += num / fact

2014

getcontext().prec -= 2

2015

return +s

2016

2017

def cos(x):

2018

"""Return the cosine of x as measured in radians.

2019

2020

>>> print cos(Decimal('0.5'))

2021

0.8775825618903727161162815826

2022

>>> print cos(0.5)

2023

0.87758256189

2024

>>> print cos(0.5+0j)

2025

(0.87758256189+0j)

2026

2027

"""

2028

getcontext().prec += 2

2029

i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1

2030

while s != lasts:

2031

lasts = s

2032

i += 2

2033

fact *= i * (i-1)

2034

num *= x * x

2035

sign *= -1

2036

s += num / fact * sign

2037

getcontext().prec -= 2

2038

return +s

2039

2040

def sin(x):

2041

"""Return the sine of x as measured in radians.

2042

2043

>>> print sin(Decimal('0.5'))

2044

0.4794255386042030002732879352

2045

>>> print sin(0.5)

2046

0.479425538604

2047

>>> print sin(0.5+0j)

2048

(0.479425538604+0j)

2049

2050

"""

2051

getcontext().prec += 2

2052

i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1

2053

while s != lasts:

2054

lasts = s

2055

i += 2

2056

2057

num *= x * x

2058

sign *= -1

2059

s += num / fact * sign

2060

getcontext().prec -= 2

2061

return +s

2062

</pre></div>

2063

</div>

2064

</div>

2065

2066

<h2>9.4.8. Decimal FAQ<a class="headerlink" href="#decimal-faq" title="Permalink to this headline">¶</a></h2>

2067

Q. It is cumbersome to type <code class="docutils literal">decimal.Decimal('1234.5')</code>. Is there a way to

2068

minimize typing when using the interactive interpreter?

2069

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

2070

<div class="highlight-python"><div class="highlight"><pre>>>> D = decimal.Decimal

2071

>>> D('1.23') + D('3.45')

2072

Decimal('4.68')

2073

</pre></div>

2074

</div>

2075

Q. In a fixed-point application with two decimal places, some inputs have many

2076

places and need to be rounded. Others are not supposed to have excess digits

2077

and need to be validated. What methods should be used?

2078

A. The <code class="xref py py-meth docutils literal">quantize()</code> method rounds to a fixed number of decimal places. If

2079

the <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal">Inexact</code></a> trap is set, it is also useful for validation:

2080

<div class="highlight-python"><div class="highlight"><pre>>>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')

2081

</pre></div>

2082

</div>

2083

<div class="highlight-python"><div class="highlight"><pre>>>> # Round to two places

2084

>>> Decimal('3.214').quantize(TWOPLACES)

2085

Decimal('3.21')

2086

</pre></div>

2087

</div>

2088

<div class="highlight-python"><div class="highlight"><pre>>>> # Validate that a number does not exceed two places

2089

>>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))

2090

Decimal('3.21')

2091

</pre></div>

2092

</div>

2093

<div class="highlight-python"><div class="highlight"><pre>>>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))

2094

Traceback (most recent call last):

2095

...

2096

Inexact: None

2097

</pre></div>

2098

</div>

2099

Q. Once I have valid two place inputs, how do I maintain that invariant

2100

throughout an application?

2101

A. Some operations like addition, subtraction, and multiplication by an integer

2102

will automatically preserve fixed point. Others operations, like division and

2103

non-integer multiplication, will change the number of decimal places and need to

2104

be followed-up with a <code class="xref py py-meth docutils literal">quantize()</code> step:

2105

<div class="highlight-python"><div class="highlight"><pre>>>> a = Decimal('102.72') # Initial fixed-point values

2106

>>> b = Decimal('3.17')

2107

>>> a + b # Addition preserves fixed-point

2108

Decimal('105.89')

2109

>>> a - b

2110

Decimal('99.55')

2111

>>> a * 42 # So does integer multiplication

2112

Decimal('4314.24')

2113

>>> (a * b).quantize(TWOPLACES) # Must quantize non-integer multiplication

2114

Decimal('325.62')

2115

>>> (b / a).quantize(TWOPLACES) # And quantize division

2116

Decimal('0.03')

2117

</pre></div>

2118

</div>

2119

In developing fixed-point applications, it is convenient to define functions

2120

to handle the <code class="xref py py-meth docutils literal">quantize()</code> step:

2121

<div class="highlight-python"><div class="highlight"><pre>>>> def mul(x, y, fp=TWOPLACES):

2122

... return (x * y).quantize(fp)

2123

>>> def div(x, y, fp=TWOPLACES):

2124

... return (x / y).quantize(fp)

2125

</pre></div>

2126

</div>

2127

<div class="highlight-python"><div class="highlight"><pre>>>> mul(a, b) # Automatically preserve fixed-point

2128

Decimal('325.62')

2129

>>> div(b, a)

2130

Decimal('0.03')

2131

</pre></div>

2132

</div>

2133

Q. There are many ways to express the same value. The numbers <code class="xref py py-const docutils literal">200</code>,

2134

<code class="xref py py-const docutils literal">200.000</code>, <code class="xref py py-const docutils literal">2E2</code>, and <code class="xref py py-const docutils literal">02E+4</code> all have the same value at

2135

various precisions. Is there a way to transform them to a single recognizable

2136

canonical value?

2137

A. The <code class="xref py py-meth docutils literal">normalize()</code> method maps all equivalent values to a single

2138

representative:

2139

<div class="highlight-python"><div class="highlight"><pre>>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())

2140

>>> [v.normalize() for v in values]

2141

[Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]

2142

</pre></div>

2143

</div>

2144

Q. Some decimal values always print with exponential notation. Is there a way

2145

to get a non-exponential representation?

2146

A. For some values, exponential notation is the only way to express the number

2147

of significant places in the coefficient. For example, expressing

2148

<code class="xref py py-const docutils literal">5.0E+3</code> as <code class="xref py py-const docutils literal">5000</code> keeps the value constant but cannot show the

2149

original’s two-place significance.

2150

If an application does not care about tracking significance, it is easy to

2151

remove the exponent and trailing zeros, losing significance, but keeping the

2152

value unchanged:

2153

<div class="highlight-python"><div class="highlight"><pre>def remove_exponent(d):

2154

'''Remove exponent and trailing zeros.

2155

2156

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

2157

Decimal('5000')

2158

2159

'''

2160

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

2161

</pre></div>

2162

</div>

2163

Q. Is there a way to convert a regular float to a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal">Decimal</code></a>?

2164

A. Yes, any binary floating point number can be exactly expressed as a

2165

Decimal though an exact conversion may take more precision than intuition would

2166

suggest:

2167

2168

Decimal('3.141592653589793115997963468544185161590576171875')

2169

</pre></div>

2170

</div>

2171

Q. Within a complex calculation, how can I make sure that I haven’t gotten a

2172

spurious result because of insufficient precision or rounding anomalies.

2173

A. The decimal module makes it easy to test results. A best practice is to

2174

re-run calculations using greater precision and with various rounding modes.

2175

Widely differing results indicate insufficient precision, rounding mode issues,

2176

ill-conditioned inputs, or a numerically unstable algorithm.

2177

Q. I noticed that context precision is applied to the results of operations but

2178

not to the inputs. Is there anything to watch out for when mixing values of

2179

different precisions?

2180

A. Yes. The principle is that all values are considered to be exact and so is

2181

the arithmetic on those values. Only the results are rounded. The advantage

2182

for inputs is that “what you type is what you get”. A disadvantage is that the

2183

results can look odd if you forget that the inputs haven’t been rounded:

2184

2185

2186

Decimal('5.21')

2187

>>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')

2188

Decimal('5.20')

2189

</pre></div>

2190

</div>

2191

The solution is either to increase precision or to force rounding of inputs

2192

using the unary plus operation:

2193

2194

>>> +Decimal('1.23456789') # unary plus triggers rounding

2195

Decimal('1.23')

2196

</pre></div>

2197

</div>

2198

Alternatively, inputs can be rounded upon creation using the

2199

<a class="reference internal" href="#decimal.Context.create_decimal" title="decimal.Context.create_decimal"><code class="xref py py-meth docutils literal">Context.create_decimal()</code></a> method:

2200

<div class="highlight-python"><div class="highlight"><pre>>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')

2201

Decimal('1.2345')

2202

</pre></div>

2203

</div>

2204

</div>

2205

</div>

2206

2207

2208

</div>

2209

</div>

2210

</div>

2211

2212

2213

<h3><a href="../contents.html">Table Of Contents</a></h3>

2214

<ul>

2215

<li><a class="reference internal" href="#">9.4. <code class="docutils literal">decimal</code> — Decimal fixed point and floating point arithmetic</a><ul>

2216

<li><a class="reference internal" href="#quick-start-tutorial">9.4.1. Quick-start Tutorial</a></li>

2217

<li><a class="reference internal" href="#decimal-objects">9.4.2. Decimal objects</a><ul>

2218

<li><a class="reference internal" href="#logical-operands">9.4.2.1. Logical operands</a></li>

2219

</ul>

2220

</li>

2221

<li><a class="reference internal" href="#context-objects">9.4.3. Context objects</a></li>

2222

<li><a class="reference internal" href="#signals">9.4.4. Signals</a></li>

2223

<li><a class="reference internal" href="#floating-point-notes">9.4.5. Floating Point Notes</a><ul>

2224

<li><a class="reference internal" href="#mitigating-round-off-error-with-increased-precision">9.4.5.1. Mitigating round-off error with increased precision</a></li>

2225

<li><a class="reference internal" href="#special-values">9.4.5.2. Special values</a></li>

2226

</ul>

2227

</li>

2228

<li><a class="reference internal" href="#working-with-threads">9.4.6. Working with threads</a></li>

2229

<li><a class="reference internal" href="#recipes">9.4.7. Recipes</a></li>

2230

<li><a class="reference internal" href="#decimal-faq">9.4.8. Decimal FAQ</a></li>

2231

</ul>

2232

</li>

2233

</ul>

2234

2235

<h4>Previous topic</h4>

2236

<a href="cmath.html"

2237

title="previous chapter">9.3. <code class="docutils literal">cmath</code> — Mathematical functions for complex numbers</a>

2238

<h4>Next topic</h4>

2239

<a href="fractions.html"

2240

title="next chapter">9.5. <code class="docutils literal">fractions</code> — Rational numbers</a>

2241

2242

2243

<li><a href="../bugs.html">Report a Bug</a></li>

2244

<li><a href="../_sources/library/decimal.txt"

2245

rel="nofollow">Show Source</a></li>

2246

</ul>

2247

2248

2249

<h3>Quick search</h3>

2250

2251

2252

2253

2254

2255

</form>

2256

2257

Enter search terms or a module, class or function name.

2258

2259

</div>

2260

2261

</div>

2262

</div>

2263

2264

</div>

2265

2266

<h3>Navigation</h3>

2267

<ul>

2268

2269

<a href="../genindex.html" title="General Index"

2270

>index</a></li>

2271

2272

<a href="../py-modindex.html" title="Python Module Index"

2273

>modules</a> |</li>

2274

2275

<a href="fractions.html" title="9.5. fractions — Rational numbers"

2276

>next</a> |</li>

2277

2278

<a href="cmath.html" title="9.3. cmath — Mathematical functions for complex numbers"

2279

>previous</a> |</li>

2280

<li><img src="../_static/py.png" alt=""

2281

style="vertical-align: middle; margin-top: -1px"/></li>

2282

<li><a href="https://www.python.org/">Python</a> »</li>

2283

<li>

2284

2.7.12

2285

<a href="../index.html">Documentation</a> »

2286

</li>

2287

2288

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

2289

<li class="nav-item nav-item-2"><a href="numeric.html" >9. Numeric and Mathematical Modules</a> »</li>

2290

</ul>

2291

</div>

2292

2293

2294

2295

The Python Software Foundation is a non-profit corporation.

2296

<a href="https://www.python.org/psf/donations/">Please donate.</a>

2297

2298

Last updated on Sep 20, 2016.

2299

<a href="../bugs.html">Found a bug</a>?

2300

2301

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

2302

</div>

2303

2304

</body>

2305

</html>

b'\\ No newline at end of file'

Older »