f-string '=' debugging output needs to be documented

[ericvsmith]

BPO	36858
Nosy	@ericvsmith, @Mariatta, @tmblweed

^{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 = None
created_at = <Date 2019-05-08.20:36:56.010>
labels = ['type-feature', '3.8', 'docs']
title = "f-string '=' debugging output needs to be documented"
updated_at = <Date 2019-08-21.18:19:36.043>
user = 'https://github.com/ericvsmith'

bugs.python.org fields:

activity = <Date 2019-08-21.18:19:36.043>
actor = 'syadlapalli'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-05-08.20:36:56.010>
creator = 'eric.smith'
dependencies = []
files = []
hgrepos = []
issue_num = 36858
keywords = []
message_count = 4.0
messages = ['341941', '342018', '342082', '350101']
nosy_count = 4.0
nosy_names = ['eric.smith', 'docs@python', 'Mariatta', 'syadlapalli']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue36858'
versions = ['Python 3.8']

[ericvsmith]

There are two problems here: what to call this feature, and where to put it.

The current f-string documentation is in Doc/reference/lexical_analysis.rst, which I'm not sure is the best place to add discussion about how this feature works. This feature is run-time behavior, and goes beyond what the lexer documentation should show.

[Mariatta]

Related issue where the '=' debug mode was implemented: https://bugs.python.org/issue36817

[Mariatta]

Perhaps it can be added under Tutorial?

https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals

[tmblweed]

Hello,

I'd like to work on this and will take a look.

[serhiy-storchaka]

Not everything should be in the tutorial Otherwise, the tutorial will be too heavy and no one will finish it.

It is an advanced feature. It is not necessary for beginner.

But it would be nice to have the documentation for f-string expressions (less dry than in the language specification), str.format(), built-in format() and printf-style formatting in one place. Currently it is scattered across different files and even different directories.

[ericvsmith]

Merged. Thanks!