[issue14783] Make int() and str() docstrings correct

2012-12-09 Thread Roundup Robot

Roundup Robot added the comment:

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

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-10-07 Thread Chris Jerdonek

Chris Jerdonek added the comment:

Any comments on the latest patch, in particular on the int() docstring?  
Especially you, Terry, as you created the issue?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-10-07 Thread Andrew Svetlov

Andrew Svetlov added the comment:

LGTM

--
nosy: +asvetlov

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-10-07 Thread Terry J. Reedy

Terry J. Reedy added the comment:

I checked pretty carefully and it looks good to me.

--
stage: patch review - commit review

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-10-07 Thread Roundup Robot

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

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

--
nosy: +python-dev

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-10-07 Thread Chris Jerdonek

Chris Jerdonek added the comment:

Leaving open to backport applicable portions to 2.7.  I should get to that 
later today.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-10-07 Thread Roundup Robot

Roundup Robot added the comment:

New changeset 3b484f53f91b by Chris Jerdonek in branch '2.7':
Issue #14783: Backport changes from 3.2.
http://hg.python.org/cpython/rev/3b484f53f91b

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-10-07 Thread Chris Jerdonek

Changes by Chris Jerdonek chris.jerdo...@gmail.com:


--
resolution:  - fixed
stage: commit review - committed/rejected
status: open - closed

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-10-01 Thread Chris Jerdonek

Chris Jerdonek added the comment:

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.

--
keywords: +needs review
stage: needs patch - patch review
Added file: http://bugs.python.org/file27370/issue-14783-1-default.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-09-30 Thread Chris Jerdonek

Chris Jerdonek added the comment:

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.

--
stage: commit review - needs patch
versions: +Python 2.7, Python 3.4

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-09-30 Thread Chris Jerdonek

Chris Jerdonek added the comment:

 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

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-09-25 Thread Chris Jerdonek

Chris Jerdonek added the comment:

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.

--
nosy: +chris.jerdonek

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-09-20 Thread Serhiy Storchaka

Serhiy Storchaka added the comment:

It may be worth rewrite int() and str() so that the first argument was 
positional-only argument?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-09-20 Thread Ezio Melotti

Ezio Melotti added the comment:

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-09-19 Thread Serhiy Storchaka

Serhiy Storchaka added the comment:

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

--
nosy: +storchaka

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-09-19 Thread Ezio Melotti

Ezio Melotti added the comment:

 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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-09-01 Thread Ezio Melotti

Ezio Melotti added the comment:

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



[issue14783] Make int() and str() docstrings correct

2012-08-31 Thread Terry J. Reedy

Terry J. Reedy added the comment:

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?)

--
nosy: +georg.brandl
title: Update int() docstring from manual - Make int() and str() docstrings 
correct

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue14783
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com