classification
Title: Make implementation and doc of tuple and list more compliant
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: rhettinger, serhiy.storchaka, terry.reedy, xiang.zhang
Priority: normal Keywords: patch

Created on 2016-07-20 08:17 by xiang.zhang, last changed 2017-03-06 14:41 by xiang.zhang. This issue is now closed.

Files
File name Uploaded Description Edit
tuple_and_list_parameter_name.patch xiang.zhang, 2016-07-23 16:18 review
tuple_and_list_parameter_name_v2.patch xiang.zhang, 2016-07-29 07:30 review
Messages (9)
msg270858 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2016-07-20 08:17
For tuple and list, their signatures are tuple([iterable]) and list([iterable]). But actually they support keyword argument *sequence*. The parameter names in doc are sometimes just placeholders but sometimes are real parameter names. So I suggest make the implementation and doc more compliant. One method is make the parameter name in implementation *iterable*. The other is totally suppress keyword argument since it is never documented. This is not a necessary change but I think the compliment is not a bad idea.
msg271034 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-07-22 21:23
>>> help(tuple)
Help on class tuple in module builtins:

class tuple(object)
 |  tuple() -> empty tuple
 |  tuple(iterable) -> tuple initialized from iterable's items
...
>>> tuple(sequence=[1,2,3])
(1, 2, 3)

I am surprised.  Searches with Google, Githup, Nullage turned up no example of such usage.  'tuple(sequence)' has, rather naturally, been used.
msg271049 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-07-23 03:14
This should have been changed in Python 3.0 which is when were allowed to make non-backwards compatible changes.  Since it wasn't, we have to live this mild annoyance forever (you can't change it without breaking somebody's working code somewhere).

I'm open to a small documentation patch that indicates that the actual keyword is "sequence" but the main entry of list(iterable) should remain because it is more descriptive of the kind of argument that is allowed.
msg271091 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2016-07-23 16:18
Thanks for replies. Attach a small documentation patch.
msg271613 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-07-29 06:44
Can you limit the doc change to just a single occurrence for list and tuple.  I'm averse to filling docs with redundant, noisy notes over a very minor nuance that is more of a curiosity than an actual issue.  Also, can you inline the text rather than using the ..note directive which adds more visual clutter than is warranted for something so minor.
msg271614 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-07-29 06:59
I agree with Raymond's comments.  No 'note', and once in each doc.  Perhaps 'for __ and __, the actual name of parameter 'iterable' is still 'sequence'.  ('Still' would be appropriate if the functions predate iterables.)
msg271616 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2016-07-29 07:30
Nice to know your opinions. :) Adjust the patch to use Terry's sentence.
msg277508 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-09-27 08:52
I would prefer deprecating keyword parameter for list() and tuple(). It is not documented and unlikely used in third party code.
msg289109 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2017-03-06 14:39
This issue doesn't make any sense once #29695 is applied. So close.
History
Date User Action Args
2017-03-06 14:41:37xiang.zhangsetstatus: open -> closed
2017-03-06 14:39:16xiang.zhangsetresolution: fixed
messages: + msg289109
stage: resolved
2016-09-27 08:52:31serhiy.storchakasetmessages: + msg277508
2016-07-29 07:30:50xiang.zhangsetfiles: + tuple_and_list_parameter_name_v2.patch

messages: + msg271616
components: + Documentation, - Interpreter Core
2016-07-29 06:59:45terry.reedysetmessages: + msg271614
2016-07-29 06:44:18rhettingersetmessages: + msg271613
2016-07-23 16:19:00xiang.zhangsetfiles: + tuple_and_list_parameter_name.patch
keywords: + patch
messages: + msg271091
2016-07-23 03:15:00rhettingersetassignee: rhettinger

messages: + msg271049
nosy: + rhettinger
2016-07-22 21:23:10terry.reedysetnosy: + terry.reedy
messages: + msg271034
2016-07-20 08:18:51xiang.zhangsettitle: tuple and list parameter name conflicts between doc and implementation -> Make implementation and doc of tuple and list more compliant
2016-07-20 08:17:22xiang.zhangcreate