Title: to improve documentation for join() (str method)
Type: enhancement Stage:
Components: Documentation Versions: Python 3.5, Python 3.4, Python 2.7
Status: open Resolution:
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, josh.r, ncoghlan, rhettinger, serhiy.storchaka, vy0123, xiang.zhang
Priority: normal Keywords:

Created on 2014-10-22 22:37 by vy0123, last changed 2017-04-14 15:26 by serhiy.storchaka.

File name Uploaded Description Edit
documentationForJoin.rtf vy0123, 2014-10-22 22:37 Documentation for join() (str method)
Pull Requests
URL Status Linked Edit
PR 156 open CuriousLearner, 2017-02-18 11:12
Messages (9)
msg229841 - (view) 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.



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

msg229851 - (view) 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).
msg229852 - (view) 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


Return a string which is the concatenation of the strings in the iterable iterable. The separator between elements is the string providing this method.
msg229853 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) 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.
msg229854 - (view) Author: Van Ly (vy0123) * Date: 2014-10-23 04:51
Aim for the fewest syllables in the words without losing meaning or good taste.
msg288073 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) 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.
msg291366 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-04-09 09:55
Raymond, in the review comments on 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?
msg291367 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-04-09 09:59
Noting for the record: Marco Buttu proposed my suggested approach on the PR back in early March.
msg291669 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-04-14 15:26
A reference to the iterable term was added in issue7116 when str.join() started accepting arbitrary iterables rather than just sequences.
Date User Action Args
2017-04-14 15:26:20serhiy.storchakasetmessages: + msg291669
2017-04-09 09:59:20ncoghlansetmessages: + msg291367
2017-04-09 09:55:54ncoghlansetnosy: + xiang.zhang, ncoghlan
messages: + msg291366
2017-02-18 11:25:14serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg288073
2017-02-18 11:12:13CuriousLearnersetpull_requests: + pull_request120
2014-10-23 04:51:02vy0123setmessages: + msg229854
2014-10-23 04:42:14rhettingersetmessages: + msg229853
2014-10-23 04:35:55rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
2014-10-23 04:21:24vy0123setmessages: + msg229852
2014-10-23 04:00:41josh.rsetnosy: + josh.r
messages: + msg229851
2014-10-22 22:52:47ned.deilysetnosy: + docs@python, - ronaldoussoren, ned.deily

assignee: docs@python
components: + Documentation, - macOS
versions: + Python 3.4, - Python 3.3
2014-10-22 22:37:21vy0123create