Issue 24965 add f-strings (see PEP 498). They need to be documented.

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?

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

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.

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

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.

Well, then my bad. Pretend I didn't say anything :)

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

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.

Updated with Eric’s suggestions

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

Hopefully that did it. Let me know if I missed anything.