Title: f-string's "debug" feature is undocumented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amaajemyfren, docs@python, eamanu, eric.smith, ezio.melotti, gvanrossum, miss-islington, rishi93
Priority: normal Keywords: patch

Created on 2020-06-19 23:53 by eric.smith, last changed 2020-07-27 23:23 by gvanrossum. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 21464 closed rishi93, 2020-07-13 15:25
PR 21509 merged amaajemyfren, 2020-07-16 15:41
PR 21552 open amaajemyfren, 2020-07-19 22:08
PR 21644 closed miss-islington, 2020-07-27 22:32
PR 21645 merged gvanrossum, 2020-07-27 22:34
PR 21647 merged gvanrossum, 2020-07-27 23:06
Messages (16)
msg371912 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2020-06-19 23:53
The feature of f-strings using '=' for "debugging" formatting is not documented.

>>> foo = 'bar'
>>> f'{foo=}'

I'm not sure where this should fit in to the documentation, but it needs to be in there somewhere.

Basically the documentation needs to say:

1. The entire string from the opening brace { to the start of the expression appears in the output. This allows things like f'{foo = }' to evaluate to "foo = 'bar'" (notice the extra spaces).

2. If no format spec (like :20) is given, repr() is used on the expression. If a format spec is given, then str() is used on the expression. You can use repr() with a format spec by using the !r conversion, like: 

>>> f'{foo=:20}'
'foo=bar                 '

>>> f'{foo=!r:20}'
"foo='bar'               "
msg371913 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-06-20 00:25
Every other detail about f-strings is spelled out meticulously in the reference manual:

I think it needs to be added here.

PS OT: I can't find anything about f-strings in pydoc.
msg373607 - (view) Author: Rajarishi Devarajan (rishi93) * Date: 2020-07-13 14:22
Hello all,

Could I help by adding this to the documentation ?
msg373608 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2020-07-13 14:23
@rishi93: yes, please do!
msg373611 - (view) Author: Rajarishi Devarajan (rishi93) * Date: 2020-07-13 15:27
Thank you very much. I have made a pull request. Looking forward to your review on my first open-source contribution :)
msg373975 - (view) Author: Ama Aje My Fren (amaajemyfren) * Date: 2020-07-19 22:41
Hello all,

I have attempted to resolve this issue by adding some comments to PR21464 and later provided a reworded PR21509 that attempts to resolve this using ideas from @rishi93.

Finally I have tried to document f-string within pydoc itself with PR21552.

I request please that they be marked with skip-news. Also request feedback on the PRs.
msg374120 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-23 04:28
I've reviewed your first PR (#21509).

Regarding your second one, I think there's a misunderstanding. With "pydoc" I didn't mean "the Python docs". IMO the documentation of f-strings in the language reference is sufficient, there's no need for another section about it in the library reference.

What I meant was that the pydoc *module* doesn't have any text about f-strings. The help() builtin calls, and there are some *special* topics that you can invoke whose source text is generated
by running `make pydoc-topics` in the Doc directory and copying the output into Lib/pydoc_data/. There is a list of topics included in Doc/tools/extensions/ (pydoc_topic_labels) and something has to be added there. But beware! This code is tricky. You also need to add an entry to itself, to the dict named 'topics' around line 1891. I think you can just add an entry FSTRINGS to the latter and make it point to the section labeled f-strings in the language reference (which you are updating in PR 21509).

Let me know if you need more help (I had a fun hour figuring out how all this works :-).
msg374394 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2020-07-27 16:06
I was just just trying to link to someone the documentation for f-strings, but:
1) Searching "fstring" only returns two results about xdrlib[0];
2) Searching "f-string" returns many unrelated results[1];
3) The first (and closer) result (string -- Common string operations[2]) yields nothing while using ctrl+f with fstring, f-string, f', f";
4) at the top of that page there are two links in a "see also":
  * Text Sequence Type — str[3]: it mentions raw strings at the beginning, but also yields no results for fstring, f-string, f', f";
  * String Methods[4]: that is another section of the previous page (so ctrl+f doesn't find anything), but has a link to "Format String Syntax"[5];
5) The "Format String Syntax" page[5] has another link in the middle of a paragraph that points to "formatted string literals", that eventually brings us to the right page[6];
6) the "right page"[6] has a wall of text with a block of code containing the grammar, luckily followed by a few examples.

I think we should:
1) add index entries for "f-string" and "fstring" in the relevant sections of the docs, so that they appear in the search result;
2) in the Text Sequence Type — str[3] section, have a bullet list for f-strings, raw-strings, and possibly u-strings;
3) possibly use the term "f-string" in addition (or instead) of "formatted string literal", to make the pages more ctrl+f-friendly throughout the docs;
4) possibly have another more newbie-friendly section on f-string (compared to the lexical analysis page) in the tutorial, in the stdtypes page[7] (e.g. before the printf-style String Formatting" section[8]), or in the string page[2] (e.g. after the "Format String Syntax" section[10]);
5) possibly reorganize and consolidate the different sections about strings, string methods, str.format(), the format mini-language, f-strings, raw/unicode-strings, %-style formatting in a single page or two (a page for the docs and one for the grammar), since it seems to me that over the years these sections got a bit scattered around as they were being added.

If you think this is out of the scope of this issue, I can open a separate one.

msg374397 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-27 16:25
Those are really good observations and proposals, Ezio! I agree that it might be better to separate them into a new issue. Can you also review (the second PR here by amaajemyfren)? Maybe it would actually make a good candidate for part (4) of your proposed solutions.

@Ama Aje My Fren: please look at my review of and implement my suggestions, then we can merge that one and close *this* issue.
msg374399 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2020-07-27 16:33
> I agree that it might be better to separate them into a new issue.

I created #41411.
msg374428 - (view) Author: Ama Aje My Fren (amaajemyfren) * Date: 2020-07-27 22:23
> then we can merge that one and close *this* issue.

I am looking at the pydoc issue now. It will take me more than an hour but I will figure it. Can that be under this issue also or (since you raised it as an OT) make that another issue?
msg374430 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-27 22:29
I think your PR 21552 and any work you're doing on pydoc could go under the new issue 41411 that Ezio just opened.
msg374431 - (view) Author: miss-islington (miss-islington) Date: 2020-07-27 22:31
New changeset 13efaec2e03288d7ff0ee643589c32bde6c6973c by amaajemyfren in branch 'master':
bpo-41045: Document debug feature of f-strings ('=') (GH-21509)
msg374435 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-27 23:01
New changeset e962e3f65a086d9d3b848483fd01215d96ecc5f9 by Guido van Rossum in branch '3.9':
[3.9] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) (GH-21645)
msg374440 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-27 23:22
New changeset 3baff21f5bb8db7fa1c15788a8f82fa040a90d5d by Guido van Rossum in branch '3.8':
[3.8] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) (#21647)
msg374441 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-27 23:23
Thanks Ama Aje My Fren! You can transfer your other PR to a different bpo issue by editing the subject on GitHub.
Date User Action Args
2020-07-27 23:23:16gvanrossumsetstatus: open -> closed
resolution: fixed
messages: + msg374441

stage: patch review -> resolved
2020-07-27 23:22:24gvanrossumsetmessages: + msg374440
2020-07-27 23:06:29gvanrossumsetpull_requests: + pull_request20786
2020-07-27 23:01:56gvanrossumsetmessages: + msg374435
2020-07-27 22:34:37gvanrossumsetpull_requests: + pull_request20785
2020-07-27 22:32:22miss-islingtonsetpull_requests: + pull_request20784
2020-07-27 22:31:09miss-islingtonsetnosy: + miss-islington
messages: + msg374431
2020-07-27 22:29:29gvanrossumsetmessages: + msg374430
2020-07-27 22:23:12amaajemyfrensetmessages: + msg374428
2020-07-27 16:33:18ezio.melottisetmessages: + msg374399
2020-07-27 16:25:40gvanrossumsetmessages: + msg374397
2020-07-27 16:06:29ezio.melottisettype: enhancement

messages: + msg374394
nosy: + ezio.melotti
2020-07-23 04:28:52gvanrossumsetmessages: + msg374120
2020-07-19 22:41:59amaajemyfrensetmessages: + msg373975
2020-07-19 22:08:48amaajemyfrensetpull_requests: + pull_request20698
2020-07-16 15:41:36amaajemyfrensetnosy: + amaajemyfren
pull_requests: + pull_request20645
2020-07-14 01:40:46eamanusetnosy: + eamanu
2020-07-13 15:27:56rishi93setmessages: + msg373611
2020-07-13 15:25:54rishi93setkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request20612
2020-07-13 14:23:32eric.smithsetmessages: + msg373608
2020-07-13 14:22:12rishi93setnosy: + rishi93
messages: + msg373607
2020-06-20 00:25:21gvanrossumsetnosy: + gvanrossum
messages: + msg371913
2020-06-19 23:53:12eric.smithcreate