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

Created on 2012-09-25 10:18 by chris.jerdonek, last changed 2012-10-07 22:05 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue-16036-1-default.patch chris.jerdonek, 2012-09-25 12:33 review
issue-16036-2-default.patch chris.jerdonek, 2012-09-25 21:25 review
issue16036.diff ezio.melotti, 2012-09-26 13:04 review
issue-16036-4-default.patch chris.jerdonek, 2012-09-27 21:25 review
issue-16036-5-27.patch chris.jerdonek, 2012-09-30 06:06
Messages (16)
msg171238 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-25 10:18
This issue is to simplify the documentation of the built-in function int()'s signature:

int([number | string[, base]])

and to make any needed changes to the text of the docs as a consequence.  Discussion around this issue began in the comments to issue 14783 about int() and str()'s docstrings.

[I copied the nosy list from that issue.]
msg171259 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-25 12:33
[Continuing the issue 14783 discussion]

> 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.

I also feel that *x* should be used, since that is what the code enforces.

I'm attaching a revised patch.  This patch also makes related adjustments to the corresponding text.
msg171319 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-25 21:25
I'm attaching an updated patch that does not cover certain edge cases that may differ for other Python implementations (and in fact does differ for PyPY).

See issue 16045 for more information.
msg171340 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-26 13:04
The latest patch is better, however I think it can be further improved.

The text is currently divided in two paragraphs:
 1) covers int(), int(num), int(x, base=b);
 2) covers int(float), and int(x, base=b);

I think it would be better to cover first int(), int(num), int(float), and then cover int(x, base=b).  The attached patch does this.
msg171349 - (view) Author: √Čric Araujo (eric.araujo) * (Python committer) Date: 2012-09-26 17:17
Latest patch LGTM.
msg171352 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-26 17:43
Good improvement.  LGTM.
msg171366 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-27 03:54
Ezio, do you want to commit this or should I?
msg171393 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-27 21:25
Attaching updated patch that clarifies the accepted non-numeric types as Serhiy suggested on Rietveld.

I also made a few other changes like linking to "integer literal" and updating the "base-radix" reference.  As I began to suspect, the latter was left over from a prior version of the docs (when the keyword argument was named "radix"):

http://hg.python.org/cpython/file/18db8c4d4487/Doc/library/functions.rst#l559

I will commit later today unless there are further suggestions.
msg171411 - (view) Author: Roundup Robot (python-dev) Date: 2012-09-28 08:21
New changeset 9205277bc008 by Chris Jerdonek in branch '3.2':
Issue #16036: Improve documentation of built-in int()'s signature and arguments.
http://hg.python.org/cpython/rev/9205277bc008

New changeset 6ccb04c4cbae by Chris Jerdonek in branch 'default':
Issue #16036: Merge update from 3.2.
http://hg.python.org/cpython/rev/6ccb04c4cbae
msg171412 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-28 08:26
Leaving open until the change is made in 2.7 (the current wording is somewhat different there).  I will do that in the next day or so.
msg171596 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-29 21:04
See the following comment to issue 16045 for a couple differences in the behavior of int() in 2.7:

http://bugs.python.org/issue16045#msg171595
msg171612 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-30 06:06
Attaching patch updated for backport to 2.7.

In cases where the 2.7 language was substantively different, I preserved the 2.7 language (e.g. I preserved the reference to plain and long integers).  I also added the lone "0" prefix for octals, which is a difference from 3.x: ``0o``/``0O``/``0``.
msg171686 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-01 01:11
[Django/Rietveld is erroring out for me when I try to reply there, so replying here]

On 2012/10/01 01:45:03, cvrebert wrote:
> Doc/library/functions.rst:636: arguments are given.  If *x* is a number, return
> :meth:`x.__int__()
> How is "number-ness" determined? Are we just assuming anything with an __int__()
> method is a number for purposes of explanation?

cvrebert, this patch has already been committed to 3.x.  Maybe open a new issue if you think the language can be improved further?  (Feel free to add me to the nosy list.)  This issue was originally focused more on updating just the signature line (along with any consequent changes to the text).
msg171690 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-01 04:11
New changeset ed76eac4491e by Chris Jerdonek in branch '2.7':
Close #16036: Backport 3.x documentation improvement.
http://hg.python.org/cpython/rev/ed76eac4491e
msg171691 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-01 04:12
Chris (cvrebert), feel free to create a new issue to improve the int() docs further.
msg172349 - (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
History
Date User Action Args
2012-10-07 22:05:29python-devsetmessages: + msg172349
2012-10-01 04:12:35chris.jerdoneksetmessages: + msg171691
2012-10-01 04:11:04python-devsetstatus: open -> closed
resolution: fixed
messages: + msg171690

stage: patch review -> resolved
2012-10-01 01:11:20chris.jerdoneksetmessages: + msg171686
2012-09-30 06:06:56chris.jerdoneksetfiles: + issue-16036-5-27.patch

messages: + msg171612
2012-09-29 21:04:12chris.jerdoneksetmessages: + msg171596
2012-09-28 08:26:07chris.jerdoneksetmessages: + msg171412
versions: + Python 2.7
2012-09-28 08:21:09python-devsetnosy: + python-dev
messages: + msg171411
2012-09-27 21:25:31chris.jerdoneksetfiles: + issue-16036-4-default.patch

messages: + msg171393
2012-09-27 03:54:24chris.jerdoneksetmessages: + msg171366
2012-09-26 17:43:22chris.jerdoneksetmessages: + msg171352
2012-09-26 17:17:23eric.araujosetmessages: + msg171349
2012-09-26 13:04:28ezio.melottisetfiles: + issue16036.diff

messages: + msg171340
2012-09-25 21:25:06chris.jerdoneksetfiles: + issue-16036-2-default.patch

messages: + msg171319
2012-09-25 12:33:13chris.jerdoneksetkeywords: + needs review, patch
files: + issue-16036-1-default.patch
messages: + msg171259

stage: patch review
2012-09-25 10:18:29chris.jerdonekcreate