[issue28739] PEP 498: docstrings as f-strings

[Donald Stufft]

Changes by Donald Stufft :


--
pull_requests: +885

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Mariatta Wijaya]

Mariatta Wijaya added the comment:


New changeset d4e89287b397c7382c12d3f3d9fd901fd8243b3c by Mariatta in branch 
'master':
bpo-28739: Document that f-strings cannot be used as docstring (GH-592)
https://github.com/python/cpython/commit/d4e89287b397c7382c12d3f3d9fd901fd8243b3c


--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Mariatta Wijaya]

Mariatta Wijaya added the comment:


New changeset ff6f3716279e75b2519133a82b9de0c3601963d9 by Mariatta in branch 
'3.6':
bpo-28739: Document that f-strings cannot be used as docstring (GH-592) (GH-600)
https://github.com/python/cpython/commit/ff6f3716279e75b2519133a82b9de0c3601963d9


--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Mariatta Wijaya]

Changes by Mariatta Wijaya :


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

[issue28739] PEP 498: docstrings as f-strings

[Eric V. Smith]

Eric V. Smith added the comment:

Yes, I think it can be closed. Thanks!

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Mariatta Wijaya]

Mariatta Wijaya added the comment:

Thanks for reviewing, Serhiy and Eric. Documentation has been updated and 
backported to 3.6.

OK to close this issue?

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Mariatta Wijaya]

Changes by Mariatta Wijaya :


--
pull_requests: +494

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Mariatta Wijaya]

Changes by Mariatta Wijaya :


--
stage: needs patch -> patch review

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Mariatta Wijaya]

Mariatta Wijaya added the comment:

Hi, I updated the documentation mentioning that f-strings cannot be used as 
docstring. Please review it.
Thanks.

--
nosy: +Mariatta

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Mariatta Wijaya]

Changes by Mariatta Wijaya :


--
pull_requests: +487

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Joakim Soderlund]

Joakim Soderlund added the comment:

I got slightly confused here while playing around.

Python 3.6.0 (default, Jan 31 2017, 11:39:39) 
[GCC 4.9.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> class Huacaya:
...   f"""Huacaya!"""
... 
>>> class Suri:
...   f"""{'Suri!'}"""
... 
>>> Huacaya.__doc__ is None
False
>>> Suri.__doc__ is None
True

At first I thought f-strings *did* work as docstrings since it worked  just 
fine for the first class. But, the docstring suddenly vanished when putting an 
actual expression into it.

--
nosy: +JockeTF

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Serhiy Storchaka]

Changes by Serhiy Storchaka :


--
assignee:  -> docs@python
components: +Documentation -Interpreter Core
keywords:  -patch
nosy: +docs@python
stage: patch review -> needs patch

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Roundup Robot]

Roundup Robot added the comment:

New changeset 30341d5c1423 by Serhiy Storchaka in branch '3.6':
Issue #28739: f-string expressions no longer accepted as docstrings and
https://hg.python.org/cpython/rev/30341d5c1423

New changeset 8e0f147dfa3d by Serhiy Storchaka in branch 'default':
Issue #28739: f-string expressions no longer accepted as docstrings and
https://hg.python.org/cpython/rev/8e0f147dfa3d

--
nosy: +python-dev

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Eric V. Smith]

Eric V. Smith added the comment:

It looks good to me, save for one tiny issue. I left a review comment.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

Eric, could you please make a review of the patch?

--
stage:  -> patch review
type:  -> behavior
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

[issue28739] PEP 498: docstrings as f-strings

[Guido van Rossum]

Guido van Rossum added the comment:

I was just noticing that the formal grammar in the reference manual first
defines a single string literal and then separately describes concatenation.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Terry J. Reedy]

Terry J. Reedy added the comment:

I considered concatenated string literals to be included in 'string literal'.  
If that is not obvious, then it should be made so.  Replace 'string literal' 
with 'string literal or concatenated strings literals' and link each part to 
their respective (and successive) sections.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Guido van Rossum]

Guido van Rossum added the comment:

I think such a patch is fine -- for 3.6.1.

Also note that linking to the definition of "string literal" is
insufficient, assuming we will want to continue supporting literal
concatenation (
https://docs.python.org/3/reference/lexical_analysis.html#string-literal-concatenation).
(And I want to, because I can see a use case.)

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

Proposed patch makes f-strings not be accepted as docstrings. It also disallow 
f-strings in ast.literal_eval().

--
keywords: +patch
Added file: http://bugs.python.org/file45658/fstring-no-docstring.patch

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Terry J. Reedy]

Terry J. Reedy added the comment:

I withdraw my previously suggested addition to the Docstring glossary entry 
(msg281740).  It implies that trivial f-strings are acceptable and I agree that 
other implementations and future Cpython should be free to strictly follow the 
literal meaning of the first sentence: docstring = initial string literal 
expression.

I suggest instead that 'string literal' in the first sentence link to 
https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals.
  This would make it clearer that 'string literal' is being used the the Python 
technical sense rather than in any more informal English sense.

We could possibly add a version of what Guido said above, such as: "(Acceptance 
of anything other than a string literal as a docstring is an implementation 
accident and should not be relied upon.)"

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Guido van Rossum]

Guido van Rossum added the comment:

OK, clearly the code that sets __doc__ is too closely tied to the generated
code (or to the reduced AST used to generate code). I still think code that
uses any of these is on thin ice and should expect to be broken in the
future.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

Adding more confusion, the expression ``('This is a docstring')`` is accepted 
as a docstring despite the fact that it is not a string literal.

The cases f'string' and ('string') looks similar to me. Both are simple 
expressions that become indistinguishable from string literals due to some 
optimization at parser level. It would be nice to disallow them as docstrings, 
but it may be not easy to do.

--
nosy: +serhiy.storchaka

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Guido van Rossum]

Guido van Rossum added the comment:

I don't really care that much, but I personally think that it would be more 
consistent (and a simpler rule) if *no* f-string (not even ones without 
substitutions) were to be allowed as docstrings.

In all other examples that Raymond shows it's the syntactic form that matters 
-- no on b-strings, yes on r-strings, yes on concatenation (using space), no on 
+, etc.

The language reference clearly defines f-strings as all strings with an 
f-prefix, and says that they *may* contain replacement fields.  So it's clear 
that an f-string without replacements is still an f-string, and it is still 
distinguished from other strings.  Hence I think it should not be allowed as a 
docstring.

(Also, what purpose could using the f-prefix for a docstring possibly have?  
All the other allowable combinations do have a use.)

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Raymond Hettinger]

Raymond Hettinger added the comment:

[TJR]
> I think this issue should either be closed as 'not a bug' 
> or redefined as a doc issue.

I concur.  

FWIW, here are some comparisons.  
Not allowed:

   'Not counted as' + ' a docstring'
   'Not a docstring ' * 10
   b'Also not a docstring'

Allowed:

   'This is a ' 'docstring'
   r'This is a docstring'

--
nosy: +rhettinger

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Terry J. Reedy]

Terry J. Reedy added the comment:

Much of this discussion seems to duplicate and effectively re-open of #25179, 
wherein it was decided/accepted that true, non-degenerate, non-trivial, 
non-constant, f-strings that actually do formatting are not constants and do 
not and should not become docstrings.  I agree.  I think this issue should 
either be closed as 'not a bug' or redefined as a doc issue.

It was noted by Martin P. in #25179 that "a constant f-string without any 
interpolations does become a doc string."  That is because such is really a 
string literal and not really an f-string, in the same sense that 'circle of 
radius 0' is really a point and not a circle.

The current glossary entry is

"docstring
A string literal which appears as the first expression in a class, function 
or module. While ignored when the suite is executed, it is recognized by the 
compiler and put into the __doc__ attribute of the enclosing class, function or 
module. Since it is available via introspection, it is the canonical place for 
documentation of the object."

I suggest adding "Bytestring literals and non-trivial f-strings do not become 
docstrings." as the second sentence.

--
nosy: +terry.reedy

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Ned Deily]

Ned Deily added the comment:

Since this was previously discussed and rejected (in Issue25179), I don't think 
we should revisit this now for 3.6, other than potentially a documentation 
tweak.

--
nosy: +ned.deily
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

[issue28739] PEP 498: docstrings as f-strings

[Guido van Rossum]

Guido van Rossum added the comment:

Might I point out the precedent of b-strings? Those also don't contribute
to __doc__.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Eric V. Smith]

Eric V. Smith added the comment:

It's Ned's call, but I wouldn't recommend changing this in 3.6, at least not 
3.6.0.

As Martin points out, the reason f'foo' is a "normal" string has to do with how 
strings and f-strings are assembled and concatenated.

Similarly:
'foo' f'bar' 'baz'
is a normal string, 'foobarbaz'.

I can't think of another place that requires a "normal" string, but if they 
exist, they'd be affected by this, too.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Martin Panter]

Martin Panter added the comment:

Having an unassigned f-string as the first statement is still valid syntax, so 
could at most be a warning, not a SyntaxError.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Martin Panter]

Martin Panter added the comment:

Actually, testing your code fragment, it seems you do get a doc string when the 
f-string has no substitutions in curly brackets, otherwise you don’t get any 
doc string. Maybe this is due to how different forms of string are compiled.

>>> class Foo:
...f'spam'  # Compiled as plain 'spam'
... 
>>> Foo.__doc__
'spam'
>>> class Foo:
... 'spam' f'{"MMM"}'  # Compiled as f'spam{"MMM"}'
... 
>>> Foo.__doc__ is None
True

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Yury Selivanov]

Yury Selivanov added the comment:

> IMO it would be simpler do disallow all f-strings as docstrings.

How exactly you want to disallow them?  Raise SyntaxError?  If you don't raise 
anything, then the behaviour is just confusing -- the interpreter parses them, 
but __doc__ is None.

I think this needs to be fixed.  Eric, can we still fix this in 3.6?  If not, 
then we need to update the PEP and the docs.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Martin Panter]

Martin Panter added the comment:

There was a bit of discussion at the top of 
.

IMO it would be simpler do disallow all f-strings as docstrings. Otherwise, 
what would the result of this be:

name = "module level"
class C:
name = "class level"
def m(self, name="default param"):
f"{name}"

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Eric V. Smith]

Eric V. Smith added the comment:

As you've seen, the answer is "no"!

We'd need to add logic to evaluate them at function definition time. That would 
be a slight noticeable change, if the expressions had side effects.

--

___
Python tracker 

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

[issue28739] PEP 498: docstrings as f-strings

[Yury Selivanov]

New submission from Yury Selivanov:

Can f-strings be used as docstrings?

Right now:

class Foo:
   f'spam'
Foo.__doc__ is None

I couldn't find that f-strings cannot be used as docstrings in neither PEP 498 
not in the 3.6 documentation, so I suppose this is a bug.

--
components: Interpreter Core
messages: 281166
nosy: eric.smith, gvanrossum, martin.panter, yselivanov
priority: normal
severity: normal
status: open
title: PEP 498: docstrings as f-strings
versions: Python 3.6, Python 3.7

___
Python tracker 

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