classification
Title: Some Examples in Format String Syntax are incorrect or poorly worded
Type: Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: RufusVS, docs@python, r.david.murray, rhettinger, zach.ware
Priority: normal Keywords:

Created on 2016-07-11 16:56 by RufusVS, last changed 2017-10-02 00:37 by RufusVS. This issue is now closed.

Messages (5)
msg270189 - (view) Author: Rufus V. Smith (RufusVS) Date: 2016-07-11 16:56
In section 6.1.3 Format String Syntax, some examples have incorrect or poorly worded comments:

Original:

"Harold's a clever {0!s}"        # Calls str() on the argument first
"Bring out the holy {name!r}"    # Calls repr() on the argument first
"More {!a}"                      # Calls ascii() on the argument first

Suggested Changes:

"Harold's a clever {0!s}"        # Calls str() on first positional argument
"Bring out the holy {name!r}"    # Calls repr() on the named argument 'name'
"More {!a}"                      # Calls ascii() on first positional argument (v. 3.1 and later)
msg270194 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-07-11 18:10
I think all of these read fine as-is though I would change "argument first" to  "first argument" or just "argument".   Adding the word "positional" is a distractor from what the comments are trying to communicate.

The version numbering is normally done with a directive and outside of the examples.
msg270197 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2016-07-11 18:29
I don't think "argument first" should be changed to "first argument": the point is that the converter is called on the argument before it's formatted into the string, the call is done "first".
msg270203 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-11 20:18
Agree with Zach.  The example comments are correct as written, especially when considered in the context of the preceding example.
msg303504 - (view) Author: Rufus V. Smith (RufusVS) Date: 2017-10-02 00:37
I happened to run across this in my old email inbox.

It's embarrassing to realize how wrong I was in submitting the report.

Reading it with fresh eyes, your original makes sense.

I don't know what I was thinking.

> On Jul 11, 2016, at 2:10 PM, Raymond Hettinger <report@bugs.python.org> wrote:
> 
> 
> Raymond Hettinger added the comment:
> 
> I think all of these read fine as-is though I would change "argument first" to  "first argument" or just "argument".   Adding the word "positional" is a distractor from what the comments are trying to communicate.
> 
> The version numbering is normally done with a directive and outside of the examples.
> 
> ----------
> nosy: +rhettinger
> 
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue27484>
> _______________________________________
History
Date User Action Args
2017-10-02 00:37:19RufusVSsetmessages: + msg303504
2016-07-11 20:18:35r.david.murraysetstatus: open -> closed

nosy: + r.david.murray
messages: + msg270203

resolution: not a bug
stage: resolved
2016-07-11 18:29:31zach.waresetnosy: + zach.ware
messages: + msg270197
2016-07-11 18:10:42rhettingersetnosy: + rhettinger
messages: + msg270194
2016-07-11 16:56:56RufusVScreate