[issue16036] simplify int() signature docs
New submission from Chris Jerdonek: 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.] ---------- assignee: docs@python components: Documentation keywords: easy messages: 171238 nosy: chris.jerdonek, cvrebert, docs@python, eric.araujo, ezio.melotti, georg.brandl, rhettinger, storchaka, terry.reedy, tshepang priority: normal severity: normal status: open title: simplify int() signature docs type: enhancement versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: [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. ---------- keywords: +needs review, patch stage: -> patch review Added file: http://bugs.python.org/file27294/issue-16036-1-default.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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. ---------- Added file: http://bugs.python.org/file27307/issue-16036-2-default.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Ezio Melotti added the comment: 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. ---------- Added file: http://bugs.python.org/file27313/issue16036.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Éric Araujo added the comment: Latest patch LGTM. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: Good improvement. LGTM. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: Ezio, do you want to commit this or should I? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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#l55... I will commit later today unless there are further suggestions. ---------- Added file: http://bugs.python.org/file27321/issue-16036-4-default.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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. ---------- versions: +Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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``. ---------- Added file: http://bugs.python.org/file27351/issue-16036-5-27.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: [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:
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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Roundup Robot added the comment: New changeset ed76eac4491e by Chris Jerdonek in branch '2.7': Close #16036: Backport 3.x documentation improvement. http://hg.python.org/cpython/rev/ed76eac4491e ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: Chris (cvrebert), feel free to create a new issue to improve the int() docs further. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Roundup Robot added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: [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. ---------- keywords: +needs review, patch stage: -> patch review Added file: http://bugs.python.org/file27294/issue-16036-1-default.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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. ---------- Added file: http://bugs.python.org/file27307/issue-16036-2-default.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Ezio Melotti added the comment: 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. ---------- Added file: http://bugs.python.org/file27313/issue16036.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Éric Araujo added the comment: Latest patch LGTM. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: Good improvement. LGTM. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: Ezio, do you want to commit this or should I? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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#l55... I will commit later today unless there are further suggestions. ---------- Added file: http://bugs.python.org/file27321/issue-16036-4-default.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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. ---------- versions: +Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: 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``. ---------- Added file: http://bugs.python.org/file27351/issue-16036-5-27.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: [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:
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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Roundup Robot added the comment: New changeset ed76eac4491e by Chris Jerdonek in branch '2.7': Close #16036: Backport 3.x documentation improvement. http://hg.python.org/cpython/rev/ed76eac4491e ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Chris Jerdonek added the comment: Chris (cvrebert), feel free to create a new issue to improve the int() docs further. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
Roundup Robot added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16036> _______________________________________
participants (4)
-
Chris Jerdonek -
Ezio Melotti
-
Roundup Robot
-
Éric Araujo