classification
Title: Wrong defaults args notation in 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: docs@python, eric.araujo, ezio.melotti, georg.brandl, hynek, petri.lehtinen, python-dev
Priority: low Keywords: patch

Created on 2012-05-14 09:46 by hynek, last changed 2012-05-22 08:36 by hynek. This issue is now closed.

Files
File name Uploaded Description Edit
doc-default-args.diff hynek, 2012-05-14 09:46 review
doc-default-args-v2.diff hynek, 2012-05-14 11:37 review
doc-default-args-v2-2.7.diff hynek, 2012-05-14 12:59
Messages (16)
msg160599 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2012-05-14 09:46
After having been called out on wrong default arg notation in one of my patches (eg. function:: copyfile(src, dst[, symlinks=False])), I've done a "grep -RPi "\[\w+=" Doc/library" and fixed the cases I've found – many of them sadly from myself (all the symlinks=False ones). ;)

The patch is against tip, I'd back port it to 3.2 if the contents is okay (and do it for 2.7 too, there's a lot of this errors there, I suppose docs fixes are okay for 2.7?).
msg160600 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-05-14 09:56
The patch looks good to me, however in

-.. method:: epoll.poll([timeout=-1[, maxevents=-1]])
+.. method:: epoll.poll(timeout=-1, maxevents=-1)

it seems that maxevents can be passed only if timeout is specified, and this information is now lost in the signature.  If this is indeed true, it should be written down in the doc.
msg160602 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2012-05-14 10:13
Looking at the code of epoll.poll(), it seems that 

   epoll.poll(timeout=-1, maxevents=-1)

is correct and the old 

   epoll.poll([timeout=-1[, maxevents=-1]])

is wrong, as there's no dependency between timeout and maxevents.
msg160606 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2012-05-14 11:37
I had to expand the patch a bit by default args that weren't caught before. So here is still against default. It applies also against 3.2, only missing stuff fails AFAICT. (and yes, I checked the mknod device arg).

2.7 is in the works.
msg160620 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2012-05-14 12:59
Here's against 2.7 which proved to be a can of worms. I tried to be as unobstructive as possible.

Please have a look at it, I'm sure I forgot some parenthesis somewhere.
msg160626 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-14 13:58
I think there’s already one report for this.
msg160690 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-05-15 07:05
Are you referring to #8350?
msg160723 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-15 13:21
Yes.  Close as duplicate?
msg160724 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2012-05-15 13:24
This issue is about documentation style of function signatures, not about missing keyword arguments in C functions.
msg160729 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-05-15 14:05
Indeed.
msg161252 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2012-05-21 08:20
Now we’re all on the same page – any opinions on the patches themselves? :)
msg161253 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2012-05-21 08:26
The 3.x patch looks good to me.

What comes to the 2.7 patch, there's at least the problem with fmtparam in the csv module (should be **fmtparams instead of [, fmtparam]). And that's were I stopped reviewing, so there may also be other errors. Maybe the problem(s) should first be fixed on a case-by-case basis and then fix the style-only issues with one big patch.
msg161263 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-05-21 11:43
New changeset d13fdd97cc8e by Hynek Schlawack in branch '3.2':
#14804: Remove [] around optional arguments with default values
http://hg.python.org/cpython/rev/d13fdd97cc8e

New changeset 2293eba03348 by Hynek Schlawack in branch 'default':
#14804: Remove [] around optional arguments with default values
http://hg.python.org/cpython/rev/2293eba03348

New changeset 8b7cb7e4ed8b by Hynek Schlawack in branch 'default':
#14804: Remove [] around optional arguments with default values
http://hg.python.org/cpython/rev/8b7cb7e4ed8b
msg161265 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2012-05-21 11:52
I agree. I’ve committed the uncontroversial and mostly unrelated 3.x patch and will look at the special cases of 2.7 now.
msg161335 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-05-22 08:34
New changeset a36666c52115 by Hynek Schlawack in branch '2.7':
#14804: Remove [] around optional arguments with default values
http://hg.python.org/cpython/rev/a36666c52115
msg161336 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2012-05-22 08:36
The problematic cases have been outsourced to Issue14880 & Issue14870. Closing this one.
History
Date User Action Args
2012-05-22 08:36:31hyneksetstatus: open -> closed
resolution: fixed
messages: + msg161336

stage: patch review -> resolved
2012-05-22 08:34:02python-devsetmessages: + msg161335
2012-05-21 11:52:09hyneksetmessages: + msg161265
2012-05-21 11:43:14python-devsetnosy: + python-dev
messages: + msg161263
2012-05-21 08:26:09petri.lehtinensetmessages: + msg161253
2012-05-21 08:20:21hyneksetmessages: + msg161252
2012-05-15 14:05:21ezio.melottisetmessages: + msg160729
2012-05-15 13:24:06petri.lehtinensetmessages: + msg160724
2012-05-15 13:21:32eric.araujosetmessages: + msg160723
2012-05-15 07:05:27ezio.melottisetmessages: + msg160690
2012-05-14 13:58:11eric.araujosetmessages: + msg160626
2012-05-14 12:59:23hyneksetfiles: + doc-default-args-v2-2.7.diff

messages: + msg160620
2012-05-14 11:37:58hyneksetfiles: + doc-default-args-v2.diff

messages: + msg160606
2012-05-14 10:13:02petri.lehtinensetnosy: + petri.lehtinen
messages: + msg160602
2012-05-14 09:56:45ezio.melottisetmessages: + msg160600
2012-05-14 09:46:58hynekcreate