Issue 22702: to improve documentation for join() (str method) (original) (raw)
Created on 2014-10-22 22:37 by vy0123, last changed 2022-04-11 14:58 by admin. This issue is now closed.
Messages (15)
Author: Van Ly (vy0123) *
Date: 2014-10-22 22:37
This issue should go in the Documentation component but that is not an option in the issue tracker.
Suggestion to improve documentation for join() (str method). Applies to versions 2.7.5, 3.3.6, 3.5.0a0.
--quote
str.join(iterable)
Returns a string. Uses the string str to join strings from iterable. Raises TypeError for non-string found in iterable including object of bytes.
the iterable consists of number
try: print "-".join([0, 1, 2, 3]) except TypeError: print "A non-string is found in the iterable." A non-string is found in the iterable.
the iterable consists of string
try: print ", ".join(["x", "y", "z", "0", "1", "2", "3"]) print " - ".join(["x", "y", "z", "0", "1", "2", "3"]) print " + ".join(["x", "y", "z", "0", "1", "2", "3"]) except TypeError: print "A non-string is found in the iterable." x, y, z, 0, 1, 2, 3 x - y - z - 0 - 1 - 2 - 3 x + y + z + 0 + 1 + 2 + 3
--quote--
Author: Josh Rosenberg (josh.r) * 
Date: 2014-10-23 04:00
Seems awfully verbose relative to the standards of the other built-in methods. Can you explain what improvements you feel this provides? str.join isn't a particularly complex method, relative to the other str methods that have inline usage examples (e.g. the *strip methods, where it needs to be made clear that it's stripping by character, not string matching, or the interaction of arguments in str.split).
Author: Van Ly (vy0123) *
Date: 2014-10-23 04:21
The improvement on the original (doc v.2.7.5) lies in the removal of the repeated 'iterable' in the first sentence, and I have also shortened it to deliver only what is returned by the builtin method which was what I wanted to know without knowing how. I wrote up this reformulation as I would have like to read it. I believe the word "concatenation" is off putting to beginners without a formal background or wanting to acquire that, and there are people like me who prefer plain and simple words. "concatenation" could be used in a footnote to guide readers to more depth if that is something they want to have. The inline usage example serves to confirm what has been described/claimed.
--original: doc v.2.7.5
str.join(iterable)
Return a string which is the concatenation of the strings in the iterable iterable. The separator between elements is the string providing this method.
Author: Raymond Hettinger (rhettinger) * 
Date: 2014-10-23 04:42
At least the "iterable iterable" should be fixed. However, as Josh said, the proposed wording is verbose. Aim for the smallest number of words that gets the job done.
Author: Van Ly (vy0123) *
Date: 2014-10-23 04:51
Aim for the fewest syllables in the words without losing meaning or good taste.
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2017-02-18 11:25
Current documentation looks good to me and not needing changes (except fixing the doubled "iterable"). Proposed change looks incorrect to me. No parameter named "str" is provided in this method.
See also the docstring of str.join.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2017-04-09 09:55
Raymond, in the review comments on https://github.com/python/cpython/pull/156 Xiang noted that the current apparently duplicated iterable isn't entirely redundant:
- the first reference is to the term "iterable"
- the second reference is to the parameter name "iterable"
"Return a string which is the concatenation of the strings in the :term:iterable iterable."
So if we're going to drop one of them, it should probably be the link to the term, rather than the parameter name:
"Return a string which is the concatenation of the strings in iterable."
Does that sound reasonable to you?
Author: Alyssa Coghlan (ncoghlan) *
Date: 2017-04-09 09:59
Noting for the record: Marco Buttu proposed my suggested approach on the PR back in early March.
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2017-04-14 15:26
A reference to the iterable term was added in when str.join() started accepting arbitrary iterables rather than just sequences.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2017-05-27 05:44
New changeset 08e2f355d04d3cbea5751ce1275306ee3f569b32 by Nick Coghlan (Sanyam Khurana) in branch 'master': bpo-22702: Clarify documentation of str.join & bytes.join (GH-156) https://github.com/python/cpython/commit/08e2f355d04d3cbea5751ce1275306ee3f569b32
Author: Alyssa Coghlan (ncoghlan) *
Date: 2017-05-27 05:47
Raymond, I went ahead and accepted the patch to remove the "iterable iterable" phrasing by only referencing the parameter name and dropping the link to the term definition.
Do you think that's sufficient to fully resolve the request here, or would you prefer to see further changes made?
Author: Raymond Hettinger (rhettinger) *
Date: 2017-05-27 16:49
Do you think that's sufficient to fully resolve the request here,
Thanks Nick. That will suffice.
Author: Mariatta (Mariatta) *
Date: 2017-06-01 02:48
New changeset 1721b06a78a4fd7942d9658ac8add6911a1a03e3 by Mariatta in branch '3.5': bpo-22702: Clarify documentation of str.join & bytes.join (GH-156) (GH-1896) https://github.com/python/cpython/commit/1721b06a78a4fd7942d9658ac8add6911a1a03e3
Author: Mariatta (Mariatta) *
Date: 2017-06-01 02:49
New changeset 9522159bc41f2be0f4aafd0fa182669876aca47f by Mariatta in branch '3.6': bpo-22702: Clarify documentation of str.join & bytes.join (GH-156) (GH-1897) https://github.com/python/cpython/commit/9522159bc41f2be0f4aafd0fa182669876aca47f
Author: Mariatta (Mariatta) *
Date: 2017-06-01 02:49
New changeset 9139f23464ed0f71cb0e34a535a5b7ddf7fad748 by Mariatta in branch '2.7': bpo-22702: Clarify documentation of str.join & bytes.join (GH-156) (GH-1898) https://github.com/python/cpython/commit/9139f23464ed0f71cb0e34a535a5b7ddf7fad748
History
Date
User
Action
Args
2022-04-11 14:58:09
admin
set
github: 66891
2017-06-01 02:50:00
Mariatta
set
stage: backport needed -> resolved
2017-06-01 02:49:33
Mariatta
set
messages: +
2017-06-01 02:49:03
Mariatta
set
messages: +
2017-06-01 02:48:30
Mariatta
set
nosy: + Mariatta
messages: +
2017-06-01 02:32:48
Mariatta
set
pull_requests: + <pull%5Frequest1976>
2017-06-01 02:29:59
Mariatta
set
pull_requests: + <pull%5Frequest1975>
2017-06-01 02:29:23
Mariatta
set
pull_requests: + <pull%5Frequest1974>
2017-06-01 02:26:19
Mariatta
set
stage: resolved -> backport needed
versions: + Python 3.6, Python 3.7, - Python 3.4
2017-05-27 16:49:24
rhettinger
set
status: open -> closed
resolution: fixed
messages: +
stage: resolved
2017-05-27 05:47:38
ncoghlan
set
messages: +
2017-05-27 05:44:43
ncoghlan
set
messages: +
2017-04-14 15:26:20
serhiy.storchaka
set
messages: +
2017-04-09 09:59:20
ncoghlan
set
messages: +
2017-04-09 09:55:54
ncoghlan
set
nosy: + xiang.zhang, ncoghlan
messages: +
2017-02-18 11:25:14
serhiy.storchaka
set
nosy: + serhiy.storchaka
messages: +
2017-02-18 11:12:13
CuriousLearner
set
pull_requests: + <pull%5Frequest120>
2014-10-23 04:51:02
vy0123
set
messages: +
2014-10-23 04:42:14
rhettinger
set
messages: +
2014-10-23 04:35:55
rhettinger
set
assignee: docs@python -> rhettinger
nosy: + rhettinger
2014-10-23 04:21:24
vy0123
set
messages: +
2014-10-23 04:00:41
josh.r
set
nosy: + josh.r
messages: +
2014-10-22 22:52:47
ned.deily
set
nosy: + docs@python, - ronaldoussoren, ned.deily
assignee: docs@python
components: + Documentation, - macOS
versions: + Python 3.4, - Python 3.3
2014-10-22 22:37:21
vy0123
create