Repository navigation
PEP 498 f-strings need to be documented #69366
Description
| BPO | 25179 |
|---|---|
| Nosy | @ericvsmith, @vadmium, @jayvdb, @Vgr255 |
| Files |
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 = <Date 2016-02-13.03:14:42.869>
created_at = <Date 2015-09-19.18:55:18.577>
labels = ['type-feature', 'docs']
title = 'PEP 498 f-strings need to be documented'
updated_at = <Date 2016-02-13.03:14:42.850>
user = 'https://github.com/ericvsmith'bugs.python.org fields:
activity = <Date 2016-02-13.03:14:42.850>
actor = 'martin.panter'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-02-13.03:14:42.869>
closer = 'martin.panter'
components = ['Documentation']
creation = <Date 2015-09-19.18:55:18.577>
creator = 'eric.smith'
dependencies = []
files = ['41839', '41864']
hgrepos = []
issue_num = 25179
keywords = ['patch']
message_count = 12.0
messages = ['251101', '254298', '254299', '254300', '254303', '254309', '254310', '259756', '259757', '259907', '260221', '260223']
nosy_count = 6.0
nosy_names = ['eric.smith', 'docs@python', 'python-dev', 'martin.panter', 'jayvdb', 'abarry']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue25179'
versions = ['Python 3.6']
Activity
ericvsmith commentedon Sep 19, 2015
bpo-24965 add f-strings (see PEP-498). They need to be documented.
jayvdb commentedon Nov 7, 2015
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?
Vgr255 commentedon Nov 7, 2015
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).
ericvsmith commentedon Nov 7, 2015
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.
Vgr255 commentedon Nov 7, 2015
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).
ericvsmith commentedon Nov 7, 2015
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.
Vgr255 commentedon Nov 7, 2015
Well, then my bad. Pretend I didn't say anything :)
python-dev commentedon Feb 7, 2016
New changeset f25d8cbd074a by Martin Panter in branch '3.5':
Issue bpo-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 bpo-25179: Preparatory cleanup of existing docs on string formatting
https://hg.python.org/cpython/rev/fe692ee6d19a
vadmium commentedon Feb 7, 2016
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.
vadmium commentedon Feb 9, 2016
Updated with Eric’s suggestions
python-dev commentedon Feb 13, 2016
New changeset f4d7de7d18c0 by Martin Panter in branch 'default':
Issue bpo-25179: Documentation for formatted string literals aka f-strings
https://hg.python.org/cpython/rev/f4d7de7d18c0
vadmium commentedon Feb 13, 2016
Hopefully that did it. Let me know if I missed anything.