[issue25179] PEP 498 f-strings need to be documented

[Roundup Robot]

Roundup Robot added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Martin Panter]

Martin Panter added the comment:

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

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Martin Panter]

Martin Panter added the comment:

Updated with Eric’s suggestions

--
Added file: http://bugs.python.org/file41864/f-strings.v2.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Martin Panter]

Martin Panter added the comment:

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.

--
keywords: +patch
nosy: +martin.panter
stage: needs patch -> patch review
Added file: http://bugs.python.org/file41839/f-strings.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Roundup Robot]

Roundup Robot added the comment:

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

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Ezio Melotti]

Changes by Ezio Melotti :


--
type:  -> enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Eric V. Smith]

Eric V. Smith added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Emanuel Barry]

Emanuel Barry added the comment:

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

--
nosy: +ebarry

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Eric V. Smith]

Eric V. Smith added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Emanuel Barry]

Emanuel Barry added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue25179] PEP 498 f-strings need to be documented

[Eric V. Smith]

New submission from Eric V. Smith:

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

--
assignee: docs@python
components: Documentation
messages: 251101
nosy: docs@python, eric.smith
priority: normal
severity: normal
stage: needs patch
status: open
title: PEP 498 f-strings need to be documented
versions: Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com