Issue 16036: simplify int() signature docs

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

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

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.

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.

Latest patch LGTM.

Good improvement.  LGTM.

Ezio, do you want to commit this or should I?

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.

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

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.

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

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

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

New changeset ed76eac4491e by Chris Jerdonek in branch '2.7':
Close #16036: Backport 3.x documentation improvement.
http://hg.python.org/cpython/rev/ed76eac4491e

Chris (cvrebert), feel free to create a new issue to improve the int() docs further.

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

stage: patch review -> resolved

messages: + msg171612

messages: + msg171393

messages: + msg171340

messages: + msg171319

stage: patch review