classification
Title: f-string's "debug" feature is undocumented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
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=}'
"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'               "
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: 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.
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 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 :-).
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.

[0]: https://docs.python.org/3/search.html?q=fstring
[1]: https://docs.python.org/3/search.html?q=f-string
[2]: https://docs.python.org/3/library/string.html
[3]: https://docs.python.org/3/library/stdtypes.html#textseq
[4]: https://docs.python.org/3/library/stdtypes.html#string-methods
[5]: https://docs.python.org/3/library/string.html#formatstrings
[6]: https://docs.python.org/3/reference/lexical_analysis.html#f-strings
[7]: https://docs.python.org/3/library/stdtypes.html
[8]: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting
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 https://github.com/python/cpython/pull/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 https://github.com/python/cpython/pull/21509 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)
https://github.com/python/cpython/commit/13efaec2e03288d7ff0ee643589c32bde6c6973c
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)
https://github.com/python/cpython/commit/e962e3f65a086d9d3b848483fd01215d96ecc5f9
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)
https://github.com/python/cpython/commit/3baff21f5bb8db7fa1c15788a8f82fa040a90d5d
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.
History
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