Repository navigation
Documentation for round() is incorrect. #75123
Description
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = 'https://github.com/lisroach'
closed_at = <Date 2018-05-22.18:16:59.209>
created_at = <Date 2017-07-16.16:51:58.320>
labels = ['easy', '3.7', '3.8', 'docs']
title = 'Documentation for round() is incorrect.'
updated_at = <Date 2018-05-22.18:16:59.208>
user = 'https://bugs.python.org/GeorgeK'bugs.python.org fields:
activity = <Date 2018-05-22.18:16:59.208>
actor = 'serhiy.storchaka'
assignee = 'lisroach'
closed = True
closed_date = <Date 2018-05-22.18:16:59.209>
closer = 'serhiy.storchaka'
components = ['Documentation']
creation = <Date 2017-07-16.16:51:58.320>
creator = 'George K'
dependencies = []
files = []
hgrepos = []
issue_num = 30940
keywords = ['patch', 'easy']
message_count = 20.0
messages = ['298442', '298443', '298462', '298531', '298537', '298538', '298542', '298587', '298595', '298596', '298597', '298704', '299298', '299326', '299545', '299551', '313497', '317173', '317179', '317180']
nosy_count = 10.0
nosy_names = ['rhettinger', 'mark.dickinson', 'ned.deily', 'r.david.murray', 'docs@python', 'serhiy.storchaka', 'steve.dower', 'lisroach', 'George K', 'miss-islington']
pr_nums = ['2824', '3256', '6342', '7009', '7010']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue30940'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']
Activity
GeorgeK commentedon Jul 16, 2017
The documentation for round states "The return value is an integer if called with one argument, otherwise of the same type as number." This is not the case if the second argument is None.
serhiy-storchaka commentedon Jul 16, 2017
In 3.4 round() doesn't accept None as ndigits argument. The behavior was changed by bpo-19933 and bpo-27936. Wasn't this change a mistake? Seems Mark opposed to it.
mdickinson commentedon Jul 17, 2017
[Serhiy]
Shrug. It seemed unnecessary to me to explicitly support
Noneas a second argument, but it's done now; reverting the change at this point would do more harm than good.So indeed there's a minor inaccuracy in the docs here. I'd suggest replacing the sentence identified with:
"The return value is an integer if *ndigits* is omitted or *None*. Otherwise the return value has the same type as *number*."
rhettinger commentedon Jul 17, 2017
Now that it is deployed, it should probably be left alone (it is has to take back an API change), but this should be a cautionary note for arg-clinic enthusiasts to not change existing APIs. When Argument Clinic is too limited to express what Python does for an exiting API, that particular function needs to be skipped.
serhiy-storchaka commentedon Jul 17, 2017
round() was not converted to Argument Clinic. There is a special comment about this:
/* AC: cannot convert yet, as needs PEP-457 group support in inspect
*/
*Now* round() can be converted to Argument Clinic. I prepared a patch for this but wanted to make sure this is a desirable behavior.
rhettinger commentedon Jul 17, 2017
That seems reasonable to me. Mark, what do you think?
mdickinson commentedon Jul 17, 2017
Sure, fine with me to add AC support for round.
serhiy-storchaka commentedon Jul 18, 2017
Could you please make a PR for your suggestion Mark?
bitdancer commentedon Jul 18, 2017
We don't need to burden Mark with doing a PR for this (unless he wants to). This is a good new contributer practice issue :)
mdickinson commentedon Jul 18, 2017
Serhiy: I thought your GitHub PR (#2740) already included the new wording?
mdickinson commentedon Jul 18, 2017
Ah, sorry; I see. That was just for the docstring, not for the docs. My bad.
serhiy-storchaka commentedon Jul 20, 2017
The documentation should be updated before converting round() to Argument Clinic, because this update should be backported to 3.6 and 3.5, while the conversion can be made only in 3.7.
serhiy-storchaka commentedon Jul 27, 2017
In the documentation:
For a general Python object
number,round(number, ndigits)delegates tonumber.__round__(ndigits).Mark, is it worth to mention explicitly that round(number) and round(number, None) delegate to
number.__round__()?
The custom __round__() method should support calling without the argument, but it can not support calling with None.
mdickinson commentedon Jul 27, 2017
[Serhiy]
Yes, if we can find a non-clunky wording that does that. The current wording does seem to misleadingly suggest that the delegation to
__round__only happens for the two-argument version of round.How about just:
serhiy-storchaka commentedon Jul 31, 2017
This also can be not clear. See a discussion in bpo-31042.
mdickinson commentedon Jul 31, 2017
Sure. But if it comes down to a clear, mostly accurate description that helps people understand versus a harder-to-read nitpick-proof statement, I'd rather see the former.
ned-deily commentedon Mar 9, 2018
This issue seems to have slipped through the cracks with a couple of long-standing PR's open. Anyone feel up to finishing it?
serhiy-storchaka commentedon May 20, 2018
New changeset 900c48d by Serhiy Storchaka (Lisa Roach) in branch 'master':
bpo-30940: Updating round() docs. (GH-6342)
900c48d
serhiy-storchaka commentedon May 20, 2018
New changeset 736e3b3 by Serhiy Storchaka (Miss Islington (bot)) in branch '3.7':
bpo-30940: Updating round() docs. (GH-6342) (GH-7009)
736e3b3
miss-islington commentedon May 20, 2018
New changeset 82c9adb by Miss Islington (bot) in branch '3.6':
bpo-30940: Updating round() docs. (GH-6342)
82c9adb