[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Guido van Rossum  added the comment:

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

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Guido van Rossum  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Change by Guido van Rossum :


--
pull_requests: +20786
pull_request: https://github.com/python/cpython/pull/21647

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Guido van Rossum  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Change by Guido van Rossum :


--
pull_requests: +20785
pull_request: https://github.com/python/cpython/pull/21645

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[miss-islington]

Change by miss-islington :


--
pull_requests: +20784
pull_request: https://github.com/python/cpython/pull/21644

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[miss-islington]

miss-islington  added the comment:


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


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Guido van Rossum  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Ama Aje My Fren]

Ama Aje My Fren  added the comment:

> 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?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Ezio Melotti]

Ezio Melotti  added the comment:

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

I created #41411.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Guido van Rossum  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Ezio Melotti]

Ezio Melotti  added the comment:

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

--
nosy: +ezio.melotti
type:  -> enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Guido van Rossum  added the comment:

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 :-).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Ama Aje My Fren]

Ama Aje My Fren  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Ama Aje My Fren]

Change by Ama Aje My Fren :


--
pull_requests: +20698
pull_request: https://github.com/python/cpython/pull/21552

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Ama Aje My Fren]

Change by Ama Aje My Fren :


--
nosy: +amaajemyfren
nosy_count: 5.0 -> 6.0
pull_requests: +20645
pull_request: https://github.com/python/cpython/pull/21509

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Emmanuel Arias]

Change by Emmanuel Arias :


--
nosy: +eamanu

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Rajarishi Devarajan]

Rajarishi Devarajan  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Rajarishi Devarajan]

Change by Rajarishi Devarajan :


--
keywords: +patch
pull_requests: +20612
stage: needs patch -> patch review
pull_request: https://github.com/python/cpython/pull/21464

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Eric V. Smith]

Eric V. Smith  added the comment:

@rishi93: yes, please do!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Rishi]

Rishi  added the comment:

Hello all,

Could I help by adding this to the documentation ?

--
nosy: +rishi93

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Guido van Rossum]

Guido van Rossum  added the comment:

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.

--
nosy: +gvanrossum

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue41045] f-string's "debug" feature is undocumented

[Eric V. Smith]

New submission from Eric V. Smith :

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

--
assignee: docs@python
components: Documentation
messages: 371912
nosy: docs@python, eric.smith
priority: normal
severity: normal
stage: needs patch
status: open
title: f-string's "debug" feature is undocumented
versions: Python 3.10, Python 3.8, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com