classification
Title: PEP 498 f-strings need to be documented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: abarry, docs@python, eric.smith, jayvdb, martin.panter, python-dev
Priority: normal Keywords: patch

Created on 2015-09-19 18:55 by eric.smith, last changed 2016-02-13 03:14 by martin.panter. This issue is now closed.

Files
File name Uploaded Description Edit
f-strings.patch martin.panter, 2016-02-07 03:06 review
f-strings.v2.patch martin.panter, 2016-02-09 02:17 review
Messages (12)
msg251101 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2015-09-19 18:55
Issue 24965 add f-strings (see PEP 498). They need to be documented.
msg254298 - (view) Author: John Mark Vandenberg (jayvdb) * Date: 2015-11-07 21:37
Might be useful to add a note to PEP 257 that f-strings are not valid as docstrings .

Or should f-strings be valid docstrings and raise an error if any variables present in the f-string do not exist in the outer scope?
msg254299 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2015-11-07 21:58
I think f-strings should be valid as docstrings. I don't know the exact details, but I think it would be harder to prevent rather than allow them. It would be exactly the same as doing func.__doc__ = func.__doc__.format(foo=foo, bar=bar)

It probably wouldn't be useful in most cases, but I don't see why we should restrict the use of f-strings to non-docstrings (not counting users trying to do that and stumbling across this error).
msg254300 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2015-11-07 22:00
Since f-strings are not constant strings, they cannot be used as docstrings without some modifications to the compiler.

I'm not sure it's worth evaluating a docstring f-string at compile time to make them become docstrings: I can't think of a use case where this would be worthwhile. But maybe I'm not thinking hard enough.
msg254303 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2015-11-07 22:04
I was under the impression that they would work without any additional work (as they'd have access to the outer scope). Of course, trying to access a local variable would be an error as it's not yet defined.

My point is more that we shouldn't have to account for such a small case - if they can be used, then let them be used, and if they can't, then don't (unless the modification is straightforward, which it might not be).
msg254309 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2015-11-07 22:12
It does not currently work, because the docstring logic looks for a string, not an expression. And an f-string is an expression.

It would require changing the compiler to evaluate the f-string expression.
msg254310 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2015-11-07 22:13
Well, then my bad. Pretend I didn't say anything :)
msg259756 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-02-07 02:40
New changeset f25d8cbd074a by Martin Panter in branch '3.5':
Issue #25179: Preparatory cleanup of existing docs on string formatting
https://hg.python.org/cpython/rev/f25d8cbd074a

New changeset fe692ee6d19a by Martin Panter in branch '2.7':
Issue #25179: Preparatory cleanup of existing docs on string formatting
https://hg.python.org/cpython/rev/fe692ee6d19a
msg259757 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-02-07 03:06
Regarding doc strings, it seems that a constant f-string without any interpolations does become a doc string. But I would treat this as an implementation detail, not something to advertise.

Attached is my attempt at a patch. Please have a look and let me know if there are things I missed, if I added too much detail, wrong terminology, or whatever. I haven’t really written documentation like this before.

The combinations and permutations of all the Fr". . ." prefixes are getting borderline out of hand in the lexical_analysis.rst grammar. Any suggestions?

I put the bulk of the documentation in a new section “Formatted string literals” of the Lexical Analysis chapter, the same place that describes escape sequences and raw strings. Let me know if there is a more appropriate place for it. It doesn’t feel quite right where it is because this chapter comes before Expressions, and f-strings use expressions inside them.

I also made minimal changes to existing parts of the documentation and tutorial, to point to the new documentation. Perhaps some code examples could be changed from str.format() to f". . .", but I think that would be the subject of a separate patch. There are even places that still use the outdated "{0}".format() numbering.
msg259907 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-02-09 02:17
Updated with Eric’s suggestions
msg260221 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-02-13 00:47
New changeset f4d7de7d18c0 by Martin Panter in branch 'default':
Issue #25179: Documentation for formatted string literals aka f-strings
https://hg.python.org/cpython/rev/f4d7de7d18c0
msg260223 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-02-13 03:14
Hopefully that did it. Let me know if I missed anything.
History
Date User Action Args
2016-02-13 03:14:42martin.pantersetstatus: open -> closed
resolution: fixed
messages: + msg260223

stage: patch review -> resolved
2016-02-13 00:47:02python-devsetmessages: + msg260221
2016-02-09 02:17:18martin.pantersetfiles: + f-strings.v2.patch

messages: + msg259907
2016-02-07 03:06:41martin.pantersetfiles: + f-strings.patch

nosy: + martin.panter
messages: + msg259757

keywords: + patch
stage: needs patch -> patch review
2016-02-07 02:40:41python-devsetnosy: + python-dev
messages: + msg259756
2016-01-04 03:23:41ezio.melottisettype: enhancement
2015-11-07 22:13:04abarrysetmessages: + msg254310
2015-11-07 22:12:03eric.smithsetmessages: + msg254309
2015-11-07 22:04:26abarrysetmessages: + msg254303
2015-11-07 22:00:50eric.smithsetmessages: + msg254300
2015-11-07 21:58:21abarrysetnosy: + abarry
messages: + msg254299
2015-11-07 21:37:08jayvdbsetnosy: + jayvdb
messages: + msg254298
2015-09-19 18:55:18eric.smithcreate