Repository navigation
Document the behaviour of Decimal.__round__ #101575
Description
Documentation
The documentation is missing a description of the behaviour of round on Decimal objects. It's worth documenting, since the behaviour (particularly with respect to the context) is non-obvious.
Of particular note:
- two-argument
roundrespects the rounding mode from theDecimalcontext. - single-argument
roundalways does round-ties-to-even, ignoring information from the context
Python 3.12.0a4 (main, Jan 20 2023, 16:04:05) [Clang 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from decimal import Decimal, getcontext, ROUND_DOWN
>>> getcontext().rounding = ROUND_DOWN
>>> round(Decimal('3.7')) # round-ties-to-even; context rounding ignored
4
>>> round(Decimal('3.7'), 0) # uses the context rounding
Decimal('3')
Activity
mdickinson commentedon Feb 5, 2023
The effect of the current context precision is also worth noting:
picnixz commentedon Feb 5, 2023
I agree that this should be documented, although it is hinted in the pure Python implementation but not in the online documentation:
Footnotes
https://github.com/python/cpython/blob/cf89c16486a4cc297413e17d32082ec4f389d725/Lib/_pydecimal.py#L1843 ↩
https://github.com/python/cpython/blob/cf89c16486a4cc297413e17d32082ec4f389d725/Lib/_pydecimal.py#L1868 ↩
OTheDev commentedon Feb 8, 2023
@mdickinson Where do you think it should be documented? Create a new entry for the
__round__()method in theDecimalclass documentation or write a note under the documentation for theround()builtin?mdickinson commentedon Feb 8, 2023
@OTheDev I was thinking of the
decimalmodule documentation, underDecimal.__round__. That's the approach that the fractions module has taken for the various dunders. E.g., https://docs.python.org/3/library/fractions.html#fractions.Fraction.__round__newbie-02 commentedon Oct 15, 2023
May I suggest first adjusting the behavior and then cementing it in the documentation? A different behavior for ~round() versus ~round(0) or round(Decimal(x),) vs. round(Decimal(x),0) or more generally having a 'context' steering something and sometimes ignoring it is trapping on a high level. Math and computers are complex enough, users need clear and consistent functionalities as good as possible.
I am aware that this is a problem for backwards compatibility, but also aware that backwards compatibility is a funbrake for progress.
( In other words: mankind brain isn't wide enough to store actual programming documentation, checking documentation for each line of code is much too slow, thus users use programs and programmers use languages first and check the docs after failure ... a little late. )
I see some more inconsistency:
normally rounding shouldn't change type, but round(Decimal(x)) returns int ( users who want that should use int( Decimal ... ) )
I am! aware that similar applies to round( float ), but consider that the same problem, a function silently performing a type conversion not requested by the user.
serhiy-storchaka commentedon Jan 16, 2024
Users are not expected to use
__round__()directly. They are expected to useround(). While in other places some dunder methods may be directly documented, I think that it is a bad practice. Instead we should document what operations are supported by the class. For example, instead of adding entries for__enter__()and__exit__()method, say that it can be used as a context manager and describe semantic, instead of adding an entry for__iter__()method, say that it is iterable and produces something.In addition to
round(), Decimal supports alsomath.ceil(),math.floor(),math.trunc(),pow(),abs(),divmod(). None of this is documented here.Index entries for both
round()andDecimal.__round__()should refer to the description of Decimal support ofround().gh-101575: document Decimal.__round__() (GH-101737)
pythongh-101575: document Decimal.__round__() (pythonGH-101737)
pythongh-101575: document Decimal.__round__() (pythonGH-101737)
[3.13] gh-101575: document Decimal.__round__() (GH-101737) (GH-120394)
[3.12] gh-101575: document Decimal.__round__() (GH-101737) (GH-120395)
encukou commentedon Jun 13, 2024
Thanks @OTheDev for the PR. As merged, it documents
round(Decimal(...)).Before the PR, I didn't know that
rounduses the context rounding mode only if it gets an argument :)PRs to document support of the other functions are welcome, but as far as I know they don't have similarly “interesting” behaviour.
pythongh-101575: document Decimal.__round__() (pythonGH-101737)
pythongh-101575: document Decimal.__round__() (pythonGH-101737)
pythongh-101575: document Decimal.__round__() (pythonGH-101737)