This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Documentation for round() is incorrect.
Type: Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: lisroach Nosy List: George K, docs@python, lisroach, mark.dickinson, miss-islington, ned.deily, r.david.murray, rhettinger, serhiy.storchaka, steve.dower
Priority: normal Keywords: easy, patch

Created on 2017-07-16 16:51 by George K, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 2824 closed daxlab, 2017-07-23 12:54
PR 3256 closed python-dev, 2017-08-31 18:32
PR 6342 merged lisroach, 2018-04-02 00:55
PR 7009 merged miss-islington, 2018-05-20 15:01
PR 7010 merged miss-islington, 2018-05-20 15:02
Messages (20)
msg298442 - (view) Author: George K (George K) Date: 2017-07-16 16:51
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.
msg298443 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-07-16 17:16
In 3.4 round() doesn't accept None as ndigits argument. The behavior was changed by issue19933 and issue27936. Wasn't this change a mistake? Seems Mark opposed to it.
msg298462 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-17 07:17
[Serhiy]
> Wasn't this change a mistake? Seems Mark opposed to it.

Shrug. It seemed unnecessary to me to explicitly support `None` as 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*."
msg298531 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-07-17 14:35
> Wasn't this change a mistake? 

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.
msg298537 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-07-17 15:33
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
 *     or a semantic change to accept None for "ndigits"
 */

*Now* round() can be converted to Argument Clinic. I prepared a patch for this but wanted to make sure this is a desirable behavior.
msg298538 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-07-17 15:39
> I prepared a patch for this but wanted to make sure this is a desirable behavior.

That seems reasonable to me.  Mark, what do you think?
msg298542 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-17 17:11
Sure, fine with me to add AC support for round.
msg298587 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-07-18 13:47
Could you please make a PR for your suggestion Mark?
msg298595 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-07-18 15:21
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 :)
msg298596 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-18 15:24
Serhiy: I thought your GitHub PR (https://github.com/python/cpython/pull/2740) already included the new wording?
msg298597 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-18 15:25
Ah, sorry; I see. That was just for the docstring, not for the docs. My bad.
msg298704 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-07-20 04:24
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.
msg299298 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-07-27 09:34
In the documentation:

   For a general Python object ``number``, ``round(number, ndigits)`` delegates to
   ``number.__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.
msg299326 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-27 17:08
[Serhiy]
> is it worth to mention explicitly that round(number) and round(number, None) > delegate to number.__round__()?

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:

> For a general Python object ``number``, ``round`` delegates to
> ``number.__round__``.
msg299545 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-07-31 09:11
> For a general Python object ``number``, ``round`` delegates to
> ``number.__round__``.

This also can be not clear. See a discussion in issue31042.
msg299551 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-31 11:56
> This also can be not clear.

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.
msg313497 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-03-09 20:20
This issue seems to have slipped through the cracks with a couple of long-standing PR's open.  Anyone feel up to finishing it?
msg317173 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-05-20 15:00
New changeset 900c48dba3f3eb8fb03ea766a5646f81c3bf3e9c by Serhiy Storchaka (Lisa Roach) in branch 'master':
bpo-30940: Updating round() docs. (GH-6342)
https://github.com/python/cpython/commit/900c48dba3f3eb8fb03ea766a5646f81c3bf3e9c
msg317179 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-05-20 15:28
New changeset 736e3b32194b52b1779ce88a2c13862f0f913a7a by Serhiy Storchaka (Miss Islington (bot)) in branch '3.7':
bpo-30940: Updating round() docs. (GH-6342) (GH-7009)
https://github.com/python/cpython/commit/736e3b32194b52b1779ce88a2c13862f0f913a7a
msg317180 - (view) Author: miss-islington (miss-islington) Date: 2018-05-20 15:29
New changeset 82c9adb3f94e5d889f03205d03a76a5ff0928531 by Miss Islington (bot) in branch '3.6':
bpo-30940: Updating round() docs. (GH-6342)
https://github.com/python/cpython/commit/82c9adb3f94e5d889f03205d03a76a5ff0928531
History
Date User Action Args
2022-04-11 14:58:49adminsetgithub: 75123
2018-05-22 18:16:59serhiy.storchakasetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-05-20 15:29:47miss-islingtonsetnosy: + miss-islington
messages: + msg317180
2018-05-20 15:28:18serhiy.storchakasetmessages: + msg317179
2018-05-20 15:02:27miss-islingtonsetpull_requests: + pull_request6660
2018-05-20 15:01:27miss-islingtonsetpull_requests: + pull_request6659
2018-05-20 15:00:24serhiy.storchakasetmessages: + msg317173
2018-04-02 00:55:27lisroachsetkeywords: + patch
pull_requests: + pull_request6053
2018-03-16 19:27:09rhettingersetassignee: docs@python -> lisroach

nosy: + lisroach
2018-03-09 20:20:17ned.deilysetversions: + Python 3.8, - Python 3.5
nosy: + ned.deily

messages: + msg313497

stage: needs patch -> patch review
2017-11-15 15:51:50serhiy.storchakaunlinkissue30950 dependencies
2017-08-31 18:32:43python-devsetpull_requests: + pull_request3300
2017-07-31 11:56:35mark.dickinsonsetmessages: + msg299551
2017-07-31 09:11:12serhiy.storchakasetmessages: + msg299545
2017-07-27 17:08:47mark.dickinsonsetmessages: + msg299326
2017-07-27 09:34:25serhiy.storchakasetmessages: + msg299298
2017-07-23 12:54:41daxlabsetpull_requests: + pull_request2876
2017-07-20 04:24:38serhiy.storchakasetkeywords: + easy

messages: + msg298704
stage: needs patch
2017-07-18 15:25:50mark.dickinsonsetmessages: + msg298597
2017-07-18 15:24:54mark.dickinsonsetmessages: + msg298596
2017-07-18 15:21:12r.david.murraysetnosy: + r.david.murray
messages: + msg298595
2017-07-18 13:47:28serhiy.storchakasetmessages: + msg298587
2017-07-17 17:11:19mark.dickinsonsetmessages: + msg298542
2017-07-17 15:50:59serhiy.storchakalinkissue30950 dependencies
2017-07-17 15:39:44rhettingersetmessages: + msg298538
2017-07-17 15:33:17serhiy.storchakasetmessages: + msg298537
2017-07-17 14:35:03rhettingersetmessages: + msg298531
2017-07-17 07:17:00mark.dickinsonsetmessages: + msg298462
2017-07-16 17:16:36serhiy.storchakasetnosy: + serhiy.storchaka, rhettinger, mark.dickinson, steve.dower

messages: + msg298443
versions: + Python 3.7
2017-07-16 16:51:58George Kcreate