f-string's "debug" feature is undocumented

[ericvsmith]

BPO	41045
Nosy	@gvanrossum, @ericvsmith, @ezio-melotti, @eamanu, @miss-islington, @amaajemyfren, @rishi93
PRs	bpo-41045: Add documentation for f-string's self documenting expressions #21464 bpo-41045: Document debug feature of f-strings ('=') #21509 gh-85583: Document f-strings in library/stdtypes.rst #21552 [3.8] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) #21644 [3.9] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) #21645 [3.8] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) #21647

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-07-27.23:23:16.235>
created_at = <Date 2020-06-19.23:53:12.742>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'f-string\'s "debug" feature is undocumented'
updated_at = <Date 2020-07-27.23:23:16.234>
user = 'https://github.com/ericvsmith'

bugs.python.org fields:

activity = <Date 2020-07-27.23:23:16.234>
actor = 'gvanrossum'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-07-27.23:23:16.235>
closer = 'gvanrossum'
components = ['Documentation']
creation = <Date 2020-06-19.23:53:12.742>
creator = 'eric.smith'
dependencies = []
files = []
hgrepos = []
issue_num = 41045
keywords = ['patch']
message_count = 16.0
messages = ['371912', '371913', '373607', '373608', '373611', '373975', '374120', '374394', '374397', '374399', '374428', '374430', '374431', '374435', '374440', '374441']
nosy_count = 8.0
nosy_names = ['gvanrossum', 'eric.smith', 'ezio.melotti', 'docs@python', 'eamanu', 'miss-islington', 'amaajemyfren', 'rishi93']
pr_nums = ['21464', '21509', '21552', '21644', '21645', '21647']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue41045'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[ericvsmith]

The feature of f-strings using '=' for "debugging" formatting is not documented.

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

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'               "

[gvanrossum]

Every other detail about f-strings is spelled out meticulously in the reference manual: https://docs.python.org/3/reference/lexical_analysis.html#formatted-string-literals

I think it needs to be added here.

PS OT: I can't find anything about f-strings in pydoc.

[rishi93]

Hello all,

Could I help by adding this to the documentation ?

[ericvsmith]

@rishi93: yes, please do!

[rishi93]

Thank you very much. I have made a pull request. Looking forward to your review on my first open-source contribution :)

[amaajemyfren]

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.

[gvanrossum]

I've reviewed your first PR (bpo-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 pydoc.help(), 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/pyspecific.py (pydoc_topic_labels) and something has to be added there. But beware! This code is tricky. You also need to add an entry to pydoc.py 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 :-).

[ezio-melotti]

I was just just trying to link to someone the documentation for f-strings, but:

1. Searching "fstring" only returns two results about xdrlib0;
2. Searching "f-string" returns many unrelated results1;
3. The first (and closer) result (string -- Common string operations2) 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 — str3: it mentions raw strings at the beginning, but also yields no results for fstring, f-string, f', f";
• String Methods4: 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" page5 has another link in the middle of a paragraph that points to "formatted string literals", that eventually brings us to the right page6;
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 — str3 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 page7 (e.g. before the printf-style String Formatting" section8), or in the string page2 (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.

[gvanrossum]

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 #21552 (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 #21509 and implement my suggestions, then we can merge that one and close *this* issue.

[ezio-melotti]

I agree that it might be better to separate them into a new issue.

I created bpo-41411.

[amaajemyfren]

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?

[gvanrossum]

I think your PR 21552 and any work you're doing on pydoc could go under the new bpo-41411 that Ezio just opened.

[miss-islington]

New changeset 13efaec by amaajemyfren in branch 'master':
bpo-41045: Document debug feature of f-strings ('=') (GH-21509)
13efaec

[gvanrossum]

New changeset e962e3f by Guido van Rossum in branch '3.9':
[3.9] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) (GH-21645)
e962e3f

[gvanrossum]

New changeset 3baff21 by Guido van Rossum in branch '3.8':
[3.8] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) (bpo-21647)
3baff21

[gvanrossum]

Thanks Ama Aje My Fren! You can transfer your other PR to a different bpo issue by editing the subject on GitHub.