classification
Title: Make int() and str() docstrings correct
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: asvetlov, chris.jerdonek, cvrebert, docs@python, eric.araujo, ezio.melotti, georg.brandl, python-dev, rhettinger, serhiy.storchaka, terry.reedy, tshepang
Priority: low Keywords: easy, needs review, patch

Created on 2012-05-11 15:50 by terry.reedy, last changed 2012-12-10 02:25 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue14783.diff ezio.melotti, 2012-08-31 17:59 Patch against 3.2.
issue-14783-1-default.patch chris.jerdonek, 2012-10-01 07:33 review
Messages (22)
msg160416 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-05-11 15:50
int.__doc__ starts "int(x[, base]) -> integer". That is not exactly correct as x is not required and base is only allowed if x is a string. The 3.3 manual fixes both problems with "int([number | string[, base]])"

I actually think the rest of the docstring might be replaced with the more accurate and informative manual entry. It might be condensed, but I am not sure what might be omitted.
msg169252 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-08-28 05:59
The 3.3 version has the virtue of being accurate and the vice of being confusing.  In a way, it has made the docs worse for the average user of common cases.

Is there a way to stack the alternative signatures rather than mush the various used into a single pile of mush?

    int(x=0) --> integer coercion
    int(str, base=10) --> integer converted from string in a given base
msg169279 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-08-28 13:21
.. function:: int(n=0)
              int(s, base=10)

should do the trick.
+1 on using this instead of int([number | string[, base]])
msg169567 - (view) Author: √Čric Araujo (eric.araujo) * (Python committer) Date: 2012-08-31 17:09
+1!  This notation helps clearing up how int, str and other constructors work.
msg169573 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-08-31 17:59
Here's a patch for the signature.
msg169577 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-08-31 19:36
The large issue is documenting complex signatures that do not really fit in any of the standard one-line patterns.

I was initially puzzled by Raymond describing the 3.3 line as 'confusing', but putting on 'newbie glasses' I see now that correctly parsing
    int([number | string[, base]])
requires knowing that '[, option]' binds tighter than '|'. Since ',' normally has the lowest binding priority, someone who does not know the signature already (ie, a target audience member) could parse it as
    int([ (number | string) [, base]])
rather than as intended:
    int([number | (string[, base]) ])
So I agree that the two stacked lines in the doc patch are clearer.

However, this issue is about the docstring. Leave it incorrect? Change it to the hard-to-parse one liner? Change it to a two-line signature also? I noticed this issue while working on IDLE tooltips, using int as a test case. They currently use only the first line of the docstring, but I have decided that they should get more when needed for C functions. (For Python functions, tooltips use inspect for the actual signature and the first docstring line only for a description.) 

The first line of the str docstring is also incorrect in that the optional parameters are only valid for first arguments that are strings.
    str(string[, encoding[, errors]]) -> str
It needs either a '|' construction like int or another line:
    str(object)
I prefer the latter. I revised the title to add str.__doc__ to the issue.

While we are at it, how about
    range(stop)
    range(start, stop, [step])
instead of the current doc and docstring signature
    range([start,] stop[, step])
? The current docstring is inaccurate and confusing to some. (How can there be an optional first arg and required second ? -- Answer: there can't.) The technically accurate signature is
    range(start_or_stop[, stop[, step]])
but that has been rejected as confusing.

The bytes and bytearrays docstrings have 5 signature lines!. (The manual gives just one which does not quite cover all cases.) So (a) there is precedent for multiple signatures in docstrings and (b) tooltips already need to grab multiple signature lines. So I think int and str (and maybe range) should use a couple of clear lines.

If the new inspect.signature function were to give signatures for C functions, there would be no problem for tooltips, but it does not. (Can signature objects even handle multiple (or type-dependent) signatures?)
msg169616 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-01 09:30
The issues about "weird" signatures are being discussed on #15831.

> However, this issue is about the docstring. Leave it incorrect?
> Change it to the hard-to-parse one liner? Change it to a 
> two-line signature also?

For the docstring it's ok to use the double signature too.  The description, while not too comprehensive, is understandable.
The description of int() in the docs is instead a bit complicated.  The content is good, but IMHO it would be more understandable if it was broken down into paragraphs or into a list.
msg170709 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-09-19 07:47
> +.. function:: int(number=0)

First argument is named "x".

>>> int(number=42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'number' is an invalid keyword argument for this function
>>> int(x=42)
42

+              int(string, base=10)

Here can be not only string, but bytes or bytearray.

>>> int('42', 6)
26
>>> int(b'42', 6)
26
>>> int(bytearray(b'42'), 6)
26
msg170711 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-19 07:58
> First argument is named "x".

Sometimes the doc uses "better" names to improve clarity when the argument is not supposed to be called as keyword arg.

> Here can be not only string, but bytes or bytearray.

The same applies here.  "string" is also used in the error message (int() can't convert non-string with explicit base).  If bytes/bytearrays are accepted too it could be mentioned later in the prose.

Otherwise we could use x for both, but the distinction would be less clear.
msg170810 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-09-20 12:38
It may be worth rewrite int() and str() so that the first argument was positional-only argument?
msg170813 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-20 14:36
That would be backward incompatible, and there might be some valid (corner) cases to pass it as a keyword.  Since people are usually not supposed to use it as a keyword arg, it doesn't matter much if the name is different if that makes the docs more understandable.  If someone tries to do int(number=10) and gets an error it would likely switch to the simpler int(10).  If he really needs keyword args he can always check the code.

That said, I don't have a strong opinion about this, so if people think that x should be used, it's fine with me.
msg171239 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-25 10:19
To make it easier to make progress on this docstring issue, I created issue 16036 to focus on int()'s reST documentation.  (I have a comment on that aspect.)  This will allow the current issue to focus on the docstring aspect.
msg171654 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-30 17:20
The change for issue 15831 contains a number of places where a single signature line was converted to multiple -- but in the docs and not the docstrings.  Those instances can also be examined for this issue.

The signature line for str() was not updated in that patch, however.
msg171662 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-30 19:30
> So (a) there is precedent for multiple signatures in docstrings

For the record, this is also true of 2.7:

http://hg.python.org/cpython/file/15fd0b4496e0/Objects/bytearrayobject.c#l2870
msg171694 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-01 07:33
Attaching proposed patch.  This updates the docstrings for int() and str(), as well as for range() and slice() in a similar way.

It also makes the documentation for str() closer to that of the docstring.  The documentation for int(), range(), and slice() has already been updated along the lines of this patch.
msg172332 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-07 19:07
Any comments on the latest patch, in particular on the int() docstring?  Especially you, Terry, as you created the issue?
msg172334 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-10-07 19:19
LGTM
msg172335 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-10-07 19:21
I checked pretty carefully and it looks good to me.
msg172350 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-07 22:05
New changeset e4598364ea29 by Chris Jerdonek in branch '3.2':
Issue #14783: Improve int() docstring and also str(), range(), and slice().
http://hg.python.org/cpython/rev/e4598364ea29

New changeset 365da47a6dc1 by Chris Jerdonek in branch '3.3':
Issue #14783: Merge changes from 3.2.
http://hg.python.org/cpython/rev/365da47a6dc1

New changeset 3773c98d9da8 by Chris Jerdonek in branch 'default':
Issue #14783: Merge changes from 3.3.
http://hg.python.org/cpython/rev/3773c98d9da8
msg172351 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-07 22:09
Leaving open to backport applicable portions to 2.7.  I should get to that later today.
msg172360 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-08 03:40
New changeset 3b484f53f91b by Chris Jerdonek in branch '2.7':
Issue #14783: Backport changes from 3.2.
http://hg.python.org/cpython/rev/3b484f53f91b
msg177250 - (view) Author: Roundup Robot (python-dev) Date: 2012-12-10 02:25
New changeset 181c170c6270 by Chris Jerdonek in branch '3.2':
Issue #16629: Fix IDLE idlelib.CallTips test.  Patch by Roger Serwy.
http://hg.python.org/cpython/rev/181c170c6270
History
Date User Action Args
2012-12-10 02:25:05python-devsetmessages: + msg177250
2012-10-08 03:42:07chris.jerdoneksetstatus: open -> closed
resolution: fixed
stage: commit review -> resolved
2012-10-08 03:40:40python-devsetmessages: + msg172360
2012-10-07 22:09:56chris.jerdoneksetmessages: + msg172351
2012-10-07 22:05:30python-devsetnosy: + python-dev
messages: + msg172350
2012-10-07 19:21:35terry.reedysetmessages: + msg172335
stage: patch review -> commit review
2012-10-07 19:19:24asvetlovsetnosy: + asvetlov
messages: + msg172334
2012-10-07 19:07:50chris.jerdoneksetmessages: + msg172332
2012-10-01 07:33:38chris.jerdoneksetkeywords: + needs review
files: + issue-14783-1-default.patch
messages: + msg171694

stage: needs patch -> patch review
2012-09-30 19:30:40chris.jerdoneksetmessages: + msg171662
2012-09-30 17:20:11chris.jerdoneksetstage: commit review -> needs patch
messages: + msg171654
versions: + Python 2.7, Python 3.4
2012-09-25 10:19:15chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg171239
2012-09-20 14:36:17ezio.melottisetmessages: + msg170813
2012-09-20 12:38:19serhiy.storchakasetmessages: + msg170810
2012-09-19 07:58:08ezio.melottisetmessages: + msg170711
2012-09-19 07:47:26serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg170709
2012-09-01 09:30:07ezio.melottisetmessages: + msg169616
2012-08-31 19:36:37terry.reedysetnosy: + georg.brandl

messages: + msg169577
title: Update int() docstring from manual -> Make int() and str() docstrings correct
2012-08-31 17:59:14ezio.melottisetfiles: + issue14783.diff
messages: + msg169573

assignee: ezio.melotti
keywords: + patch
stage: needs patch -> commit review
2012-08-31 17:09:35eric.araujosetnosy: + eric.araujo
messages: + msg169567
2012-08-28 13:21:54ezio.melottisetmessages: + msg169279
2012-08-28 05:59:28rhettingersetnosy: + rhettinger
messages: + msg169252
2012-08-27 09:03:46cvrebertsetnosy: + cvrebert
2012-05-16 21:07:38ezio.melottisetassignee: docs@python -> (no value)

type: enhancement
nosy: + ezio.melotti
stage: needs patch
2012-05-11 17:42:10tshepangsetnosy: + tshepang, docs@python

components: + Documentation
assignee: docs@python
2012-05-11 15:50:12terry.reedycreate