f-string documentation not fully accurate

[vpython]

BPO	37816
Nosy	@ericvsmith

^{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-08-11.01:06:41.829>
labels = ['3.7', '3.8', '3.9', 'docs']
title = 'f-string documentation not fully accurate'
updated_at = <Date 2019-08-11.03:17:56.205>
user = 'https://bugs.python.org/vpython'

bugs.python.org fields:

activity = <Date 2019-08-11.03:17:56.205>
actor = 'xtreak'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-08-11.01:06:41.829>
creator = 'v+python'
dependencies = []
files = []
hgrepos = []
issue_num = 37816
keywords = []
message_count = 1.0
messages = ['349370']
nosy_count = 3.0
nosy_names = ['eric.smith', 'v+python', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue37816'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9']

[vpython]

I noticed the following description for f-strings:

Escape sequences are decoded like in ordinary string literals (except when a literal is also marked as a raw string). After decoding, the grammar for the contents of the string is:

followed by lots of stuff, followed by

Backslashes are not allowed in format expressions and will raise an error:
f"newline: {ord('\n')}" # raises SyntaxError

If f-strings are processed AS DESCRIBED, the \n would never seen by the format expression... but in fact, it does produce an error.

PEP-498 has a more accurate description, that the {} parsing actually happens before the escape processing. The string or raw-string escape processing is done only to the literal string pieces.

So the string content is first parsed for format expressions enclosed in {}, on the way, converting {{ and }} to { and } in the literal parts of the string, and then the literal parts are treated exactly like independent string literals (with regular or raw-string escaping performed), to be concatenated with the evaluation of the format expressions, and subsequent literal parts.

The evaluation of the format expressions presently precludes the use of # and \ for comments and escapes, but otherwise tries to sort of by the same as a python expression possibly followed by a format mini-language part. I am not the expert here, just the messenger.

[iritkatriel]

CC @ericvsmith .

[ericvsmith]

I'd be open to a PR to address this, but I don't think it's causing a lot of confusion in the wild.