Skip to content

Commit 7aceaf1

Browse files
furkanonderfurkanonder
committed
Sync-up docstrings in C version of the the decimal module
1 parent a1e051a commit 7aceaf1

2 files changed

Lines changed: 1153 additions & 184 deletions

File tree

‎Lib/_pydecimal.py‎

Lines changed: 115 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -471,6 +471,26 @@ def setcontext(context):
471471
def localcontext(ctx=None, **kwargs):
472472
"""Return a context manager for a copy of the supplied context
473473
474+
Uses a copy of the current context if no context is specified
475+
The returned context manager creates a local decimal context
476+
in a with statement:
477+
def sin(x):
478+
with localcontext() as ctx:
479+
ctx.prec += 2
480+
# Rest of sin calculation algorithm
481+
# uses a precision 2 greater than normal
482+
return +s # Convert result to normal precision
483+
484+
def sin(x):
485+
with localcontext(ExtendedContext):
486+
# Rest of sin calculation algorithm
487+
# uses the Extended Context from the
488+
# General Decimal Arithmetic Specification
489+
return +s # Convert result to normal context
490+
491+
>>> setcontext(DefaultContext)
492+
>>> print(getcontext().prec) # Return a context manager for a copy of the supplied context
493+
474494
Uses a copy of the current context if no context is specified
475495
The returned context manager creates a local decimal context
476496
in a with statement:
@@ -503,6 +523,18 @@ def sin(x):
503523
9
504524
>>> print(getcontext().prec)
505525
28
526+
>>> with localcontext():
527+
... ctx = getcontext()
528+
... ctx.prec += 2
529+
... print(ctx.prec)
530+
...
531+
30
532+
>>> with localcontext(ExtendedContext):
533+
... print(getcontext().prec)
534+
...
535+
9
536+
>>> print(getcontext().prec)
537+
28
506538
"""
507539
if ctx is None:
508540
ctx = getcontext()
@@ -540,7 +572,7 @@ def __new__(cls, value="0", context=None):
540572
Decimal('314')
541573
>>> Decimal(Decimal(314)) # another decimal instance
542574
Decimal('314')
543-
>>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay
575+
>>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay
544576
Decimal('3.14')
545577
"""
546578

@@ -977,17 +1009,18 @@ def __hash__(self):
9771009
return -2 if ans == -1 else ans
9781010

9791011
def as_tuple(self):
980-
"""Represents the number as a triple tuple.
981-
982-
To show the internals exactly as they are.
1012+
"""Represents the number as a triple tuple, to show the internals
1013+
exactly as they are.
9831014
"""
9841015
return DecimalTuple(self._sign, tuple(map(int, self._int)), self._exp)
9851016

9861017
def as_integer_ratio(self):
9871018
"""Express a finite Decimal instance in the form n / d.
9881019
989-
Returns a pair (n, d) of integers. When called on an infinity
990-
or NaN, raises OverflowError or ValueError respectively.
1020+
Return a pair (n, d) of integers, whose ratio is exactly equal to the
1021+
original Decimal and with a positive denominator. The ratio is in
1022+
lowest terms. Raise OverflowError on infinities and a ValueError
1023+
on NaNs.
9911024
9921025
>>> Decimal('3.14').as_integer_ratio()
9931026
(157, 50)
@@ -2915,18 +2948,21 @@ def _iseven(self):
29152948
return self._int[-1+self._exp] in '02468'
29162949

29172950
def adjusted(self):
2918-
"""Return the adjusted exponent of self"""
2951+
"""Return the adjusted exponent of self.
2952+
2953+
Defined as exp + digits - 1.
2954+
"""
29192955
try:
29202956
return self._exp + len(self._int) - 1
29212957
# If NaN or Infinity, self._exp is string
29222958
except TypeError:
29232959
return 0
29242960

29252961
def canonical(self):
2926-
"""Returns the same Decimal object.
2962+
"""Return the canonical encoding of the argument.
29272963
2928-
As we do not have different encodings for the same number, the
2929-
received object already is in its canonical form.
2964+
Currently, the encoding of a Decimal instance is always canonical,
2965+
so this operation returns its argument unchanged.
29302966
"""
29312967
return self
29322968

@@ -3067,7 +3103,7 @@ def exp(self, context=None):
30673103
return Decimal(self)
30683104

30693105
# the result is now guaranteed to be inexact (the true
3070-
# mathematical result is transcendental). There's no need to
3106+
# mathematical is transcendental). There's no need to
30713107
# raise Rounded and Inexact here---they'll always be raised as
30723108
# a result of the call to _fix.
30733109
p = context.prec
@@ -4212,6 +4248,11 @@ def compare(self, a, b):
42124248
subtraction: '-1' if the result is less than zero, '0' if the result is
42134249
zero or negative zero, or '1' if the result is greater than zero.
42144250
4251+
a or b is a NaN ==> Decimal('NaN')
4252+
a < b ==> Decimal('-1')
4253+
a == b ==> Decimal('0')
4254+
a > b ==> Decimal('1')
4255+
42154256
>>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
42164257
Decimal('-1')
42174258
>>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
@@ -4230,6 +4271,8 @@ def compare(self, a, b):
42304271
Decimal('-1')
42314272
>>> ExtendedContext.compare(1, Decimal(2))
42324273
Decimal('-1')
4274+
>>> ExtendedContext.compare(Decimal('2'), Decimal('NaN'))
4275+
Decimal('NaN')
42334276
"""
42344277
a = _convert_other(a, raiseit=True)
42354278
return a.compare(b, context=self)
@@ -4240,41 +4283,50 @@ def compare_signal(self, a, b):
42404283
It's pretty much like compare(), but all NaNs signal, with signaling
42414284
NaNs taking precedence over quiet NaNs.
42424285
4243-
>>> c = ExtendedContext
4244-
>>> c.compare_signal(Decimal('2.1'), Decimal('3'))
4286+
>>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('3'))
42454287
Decimal('-1')
4246-
>>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
4288+
>>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('2.1'))
42474289
Decimal('0')
4248-
>>> c.flags[InvalidOperation] = 0
4249-
>>> print(c.flags[InvalidOperation])
4290+
>>> ExtendedContext.flags[InvalidOperation] = 0
4291+
>>> print(ExtendedContext.flags[InvalidOperation])
42504292
0
4251-
>>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
4293+
>>> ExtendedContext.compare_signal(Decimal('NaN'), Decimal('2.1'))
42524294
Decimal('NaN')
4253-
>>> print(c.flags[InvalidOperation])
4295+
>>> print(ExtendedContext.flags[InvalidOperation])
42544296
1
4255-
>>> c.flags[InvalidOperation] = 0
4256-
>>> print(c.flags[InvalidOperation])
4297+
>>> ExtendedContext.flags[InvalidOperation] = 0
4298+
>>> print(ExtendedContext.flags[InvalidOperation]
42574299
0
4258-
>>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
4300+
>>> ExtendedContext.compare_signal(Decimal('sNaN'), Decimal('2.1'))
42594301
Decimal('NaN')
4260-
>>> print(c.flags[InvalidOperation])
4302+
>>> print(ExtendedContext.flags[InvalidOperation])
42614303
1
4262-
>>> c.compare_signal(-1, 2)
4304+
>>> ExtendedContext.compare_signal(-1, 2)
42634305
Decimal('-1')
4264-
>>> c.compare_signal(Decimal(-1), 2)
4306+
>>> ExtendedContext.compare_signal(Decimal(-1), 2)
42654307
Decimal('-1')
4266-
>>> c.compare_signal(-1, Decimal(2))
4308+
>>> ExtendedContext.compare_signal(-1, Decimal(2))
42674309
Decimal('-1')
42684310
"""
42694311
a = _convert_other(a, raiseit=True)
42704312
return a.compare_signal(b, context=self)
42714313

42724314
def compare_total(self, a, b):
4273-
"""Compares two operands using their abstract representation.
4315+
"""Compares two operands using their abstract representation rather
4316+
than their numerical value.
42744317
4275-
This is not like the standard compare, which use their numerical
4276-
value. Note that a total ordering is defined for all possible abstract
4277-
representations.
4318+
Similar to the compare() method, but the result gives a total ordering
4319+
on Decimal instances.
4320+
4321+
Quiet and signaling NaNs are also included in the total ordering.
4322+
The result of this function is Decimal('0') if both operands have the
4323+
same representation, Decimal('-1') if the first operand is lower in
4324+
the total order than the second, and Decimal('1') if the first
4325+
operand is higher in the total order than the second operand. See
4326+
the specification for details of the total order.
4327+
4328+
This operation is unaffected by context and is quiet: no flags are
4329+
changed and no rounding is performed.
42784330
42794331
>>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
42804332
Decimal('-1')
@@ -4299,10 +4351,16 @@ def compare_total(self, a, b):
42994351
return a.compare_total(b)
43004352

43014353
def compare_total_mag(self, a, b):
4302-
"""Compares two operands using their abstract representation ignoring sign.
4354+
"""Compares two operands using their abstract representation rather
4355+
than their numerical value and with their sign ignored.
43034356
4304-
Like compare_total, but with operand's sign ignored and assumed to be 0.
4305-
"""
4357+
Like compare_total, but with operand's sign ignored and assumed to be
4358+
0.
4359+
4360+
x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs())
4361+
This operation is unaffected by context and is quiet: no flags are
4362+
changed and no rounding is performed.
4363+
"""
43064364
a = _convert_other(a, raiseit=True)
43074365
return a.compare_total_mag(b)
43084366

@@ -4346,10 +4404,8 @@ def copy_negate(self, a):
43464404
return a.copy_negate()
43474405

43484406
def copy_sign(self, a, b):
4349-
"""Copies the second operand's sign to the first one.
4350-
4351-
In detail, it returns a copy of the first operand with the sign
4352-
equal to the sign of the second operand.
4407+
"""Returns a copy of the first operand with the sign equal to the second
4408+
operand.
43534409
43544410
>>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
43554411
Decimal('1.50')
@@ -4365,6 +4421,9 @@ def copy_sign(self, a, b):
43654421
Decimal('-1')
43664422
>>> ExtendedContext.copy_sign(1, Decimal(-2))
43674423
Decimal('-1')
4424+
4425+
This operation is unaffected by context and is quiet: no flags are
4426+
changed and no rounding is performed.
43684427
"""
43694428
a = _convert_other(a, raiseit=True)
43704429
return a.copy_sign(b)
@@ -4451,7 +4510,8 @@ def divmod(self, a, b):
44514510
return r
44524511

44534512
def exp(self, a):
4454-
"""Returns e ** a.
4513+
"""The function always uses the ROUND_HALF_EVEN mode and the result
4514+
is correctly rounded.
44554515
44564516
>>> c = ExtendedContext.copy()
44574517
>>> c.Emin = -999
@@ -4477,8 +4537,8 @@ def exp(self, a):
44774537
def fma(self, a, b, c):
44784538
"""Returns a multiplied by b, plus c.
44794539
4480-
The first two operands are multiplied together, using multiply,
4481-
the third operand is then added to the result of that
4540+
Fused multiple-add. The first two operands are multiplied together,
4541+
using multiply, the third operand is then added to the result of that
44824542
multiplication, using add, all with only one final rounding.
44834543
44844544
>>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
@@ -4548,8 +4608,8 @@ def is_infinite(self, a):
45484608
return a.is_infinite()
45494609

45504610
def is_nan(self, a):
4551-
"""Return True if the operand is a qNaN or sNaN;
4552-
otherwise return False.
4611+
"""Return True if the operand is a (quiet or signaling) NaN or NaN;
4612+
otherwise return False.
45534613
45544614
>>> ExtendedContext.is_nan(Decimal('2.50'))
45554615
False
@@ -4604,6 +4664,8 @@ def is_qnan(self, a):
46044664
def is_signed(self, a):
46054665
"""Return True if the operand is negative; otherwise return False.
46064666
4667+
Note that both zeros and NaNs can carry signs.
4668+
46074669
>>> ExtendedContext.is_signed(Decimal('2.50'))
46084670
False
46094671
>>> ExtendedContext.is_signed(Decimal('-12'))
@@ -4637,6 +4699,9 @@ def is_snan(self, a):
46374699
def is_subnormal(self, a):
46384700
"""Return True if the operand is subnormal; otherwise return False.
46394701
4702+
A number is subnormal if it is non-zero, finite, and has an adjusted
4703+
exponent less than Emin.
4704+
46404705
>>> c = ExtendedContext.copy()
46414706
>>> c.Emin = -999
46424707
>>> c.Emax = 999
@@ -4676,6 +4741,9 @@ def is_zero(self, a):
46764741
def ln(self, a):
46774742
"""Returns the natural (base e) logarithm of the operand.
46784743
4744+
The function always uses the ROUND_HALF_EVEN mode and the result is
4745+
correctly rounded.
4746+
46794747
>>> c = ExtendedContext.copy()
46804748
>>> c.Emin = -999
46814749
>>> c.Emax = 999
@@ -4698,6 +4766,9 @@ def ln(self, a):
46984766
def log10(self, a):
46994767
"""Returns the base 10 logarithm of the operand.
47004768
4769+
The function always uses the ROUND_HALF_EVEN mode and the result
4770+
is correctly rounded.
4771+
47014772
>>> c = ExtendedContext.copy()
47024773
>>> c.Emin = -999
47034774
>>> c.Emax = 999
@@ -4724,7 +4795,7 @@ def log10(self, a):
47244795
return a.log10(context=self)
47254796

47264797
def logb(self, a):
4727-
""" Returns the exponent of the magnitude of the operand's MSD.
4798+
"""Returns the exponent of the magnitude of the operand's MSD.
47284799
47294800
The result is the integer which is the exponent of the magnitude
47304801
of the most significant digit of the operand (as though the
@@ -5291,7 +5362,8 @@ def quantize(self, a, b):
52915362
return a.quantize(b, context=self)
52925363

52935364
def radix(self):
5294-
"""Just returns 10, as this is Decimal, :)
5365+
"""Return Decimal(10), the radix (base) in which the Decimal class does
5366+
all its arithmetic. Included for compatibility with the specification.
52955367
52965368
>>> ExtendedContext.radix()
52975369
Decimal('10')

0 commit comments

Comments
 (0)