classification
Title: Mention 'keyword only' for list.sort, improve glossary.
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: zach.ware Nosy List: docs@python, ezio.melotti, icedream91, python-dev, r.david.murray, terry.reedy, zach.ware
Priority: normal Keywords: easy, patch

Created on 2013-06-29 13:05 by icedream91, last changed 2013-11-22 20:06 by zach.ware. This issue is now closed.

Files
File name Uploaded Description Edit
issue18326.diff zach.ware, 2013-07-05 19:58 review
issue18326.that.diff zach.ware, 2013-07-05 20:44 s/which/that/ review
issue18326.v2.diff zach.ware, 2013-08-20 16:19 review
issue18326.v3.diff zach.ware, 2013-08-23 14:40 review
Messages (12)
msg192034 - (view) Author: (icedream91) Date: 2013-06-29 13:05
I think the documents talking about list.sort() in page 
http://docs.python.org/3/library/stdtypes.html#list.sort is not clear enough. What asterisk means in "sort(*, key=None, reverse=None)", may be cmp argument from Python 2, or anything else? Or it is a typo?

I think document should explain what this asterisk means.

Thanks.
msg192035 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-06-29 13:27
It means they are keyword-only arguments.  This could be mentioned in the text, with the term 'keyword-only arguments' linked to an appropriate glossary entry (which appears to need to be added).
msg192345 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-07-05 18:57
'keyword argument' refers one to 'argument'. The entry for the latter says that there are only two types of arguments, keyword and positional. That is true as to how actual arguments are passed.

There are 3 possibilities for how a single argument for a parameter might be passed:
standard - positional or keyword
positional only (args for many C functions, not specifically indicated)
keyword only (follow '*' or '*args' after signature.

These are explained in the parameter entry. Keyword-only parameters have to be matched by keyword arguments.

I think it a bit misleading to say "There are two types of arguments". That actually means "There are two ways of passing an argument". Precede it by 'name=' or not. An object is the same whether passed by name or position.

Calling a name a keyword in this context is also misleading since 'keyword' otherwise means a reserved word that cannot be used as a name. Using an actual keyword to name an argument is illegal: 'for = 2' raises.
msg192351 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-07-05 19:58
How about this patch?

I agree that "types of arguments/parameters" has great potential for confusion, so the glossary has been changed to "kinds of argument/parameter" (dropping the pluralization as well; it is unnecessary).  I think just taking the word "type" out of it makes the rest of each entry unambiguous.

To list.sort, I simply added a line: ":meth:`sort` accepts two arguments which can only be passed by keyword:".  I considered making each parameter's description an indented block after that, but that seems like more change than is really necessary, and the patched version doesn't look too bad to me.
msg192357 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-07-05 20:38
The new 'which' should be 'that'. Other than that, looks good to me.
msg194694 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-08-08 16:56
"keyword-only" is a well-established term, and I think it's better to use it and possibly make it a link to the "parameter" entry of the glossary.
msg195701 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-08-20 16:19
How about this?
msg195843 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-08-21 23:59
In this expository context, I prefer the issue18326.that.diff version, but the index link to the keyword-only_parameter ref should still be added to it (on "only be passed by keyword").
msg195977 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-08-23 14:40
How about a combination of the two?  It's still short, but gets the point across without assuming the reader knows exactly what 'keyword-only argument' or requiring further reading, while introducing the term and providing the link for deeper understanding.

(Here's the relevant change in this patch, the rest is the same:)

+      :meth:`sort` accepts two arguments that must be passed by keyword
+      (:ref:`keyword-only arguments <keyword-only_parameter>`):
msg202670 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-11-12 04:20
Any further thoughts on this?  I think my vote is for v3, except s/must/can only/.  "must" makes it sound like you are forced to pass those arguments.
msg203115 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-11-17 00:53
I think v2 is enough, but v3 is fine with me if people think v3 it's better.
msg203853 - (view) Author: Roundup Robot (python-dev) Date: 2013-11-22 20:04
New changeset 9192c0798a90 by Zachary Ware in branch '3.3':
Issue #18326: Clarify that list.sort's arguments are keyword-only.
http://hg.python.org/cpython/rev/9192c0798a90

New changeset 3f1c332c5e2e by Zachary Ware in branch 'default':
Issue #18326: merge with 3.3
http://hg.python.org/cpython/rev/3f1c332c5e2e
History
Date User Action Args
2013-11-22 20:06:42zach.waresetstatus: open -> closed
assignee: docs@python -> zach.ware
resolution: fixed
stage: patch review -> resolved
2013-11-22 20:04:34python-devsetnosy: + python-dev
messages: + msg203853
2013-11-17 00:53:48ezio.melottisetmessages: + msg203115
2013-11-12 04:20:57zach.waresetmessages: + msg202670
2013-08-23 14:40:28zach.waresetfiles: + issue18326.v3.diff

messages: + msg195977
2013-08-21 23:59:04r.david.murraysetmessages: + msg195843
2013-08-20 16:19:27zach.waresetfiles: + issue18326.v2.diff

messages: + msg195701
2013-08-08 16:56:48ezio.melottisetnosy: + ezio.melotti

messages: + msg194694
stage: needs patch -> patch review
2013-07-05 20:44:46zach.waresetfiles: + issue18326.that.diff
2013-07-05 20:38:43terry.reedysetmessages: + msg192357
2013-07-05 19:58:46zach.waresetfiles: + issue18326.diff

nosy: + zach.ware
messages: + msg192351

keywords: + patch
2013-07-05 18:57:14terry.reedysetnosy: + terry.reedy

messages: + msg192345
title: Mention keywork only in list.sort docs -> Mention 'keyword only' for list.sort, improve glossary.
2013-07-05 18:30:40terry.reedysettype: enhancement
title: Not Clear Docs -> Mention keywork only in list.sort docs
2013-06-29 13:27:03r.david.murraysetversions: + Python 3.4
nosy: + r.david.murray

messages: + msg192035

keywords: + easy
stage: needs patch
2013-06-29 13:05:36icedream91create