classification
Title: Documentation for round() is incorrect.
Type: Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: George K, docs@python, mark.dickinson, r.david.murray, rhettinger, serhiy.storchaka, steve.dower
Priority: normal Keywords: easy

Created on 2017-07-16 16:51 by George K, last changed 2017-07-23 12:54 by daxlab.

Pull Requests
URL Status Linked Edit
PR 2824 open daxlab, 2017-07-23 12:54
Messages (12)
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.
History
Date User Action Args
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