[Python-Dev] Minor inconvenience: f-string not recognized as docstring

[Antoine Pitrou]

Hello,

Currently, a f-string is not recognized as a docstring:

>>> class C: f"foo"
>>> C.__doc__
>>>

This means you need to use a (admittedly easy) workaround:

>>> class C: __doc__ = f"foo"
>>> C.__doc__
'foo'

Shouldn't the former be allowed for convenience?

Regards

Antoine.


_______________________________________________
Python-Dev mailing list -- pytho...@python.org
To unsubscribe send an email to python-d...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/UALMEMQ4QW7W4HE2PIBARWYBKFWJZFB4/
Code of Conduct: http://python.org/psf/codeofconduct/

[Eric V. Smith]

Constant f-strings (those without substitutions) as doc strings used to
work, since the compiler turns them into normal strings.

I can't find exactly where it was removed, but there was definitely
discussion about it. See https://bugs.python.org/issue28739 for at least
part of the discussion.

Eric

Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/NCJKOGE4UKHTGBWZOLPAAWZ2DVU4FLZZ/

[Antoine Pitrou]

On Tue, 11 Jan 2022 10:58:03 -0500
"Eric V. Smith" <er...@trueblade.com> wrote:
> Constant f-strings (those without substitutions) as doc strings used to
> work, since the compiler turns them into normal strings.
>
> I can't find exactly where it was removed, but there was definitely
> discussion about it. See https://bugs.python.org/issue28739 for at least
> part of the discussion.

Ah, sorry for the misunderstanding. While the example I showed doesn't
have any substitutions, I'm interested in the non-trivial (non-constant)
case actually :-)

Regards

Antoine.

>
> Eric
>
> On 1/11/2022 8:41 AM, Antoine Pitrou wrote:
> > Hello,
> >
> > Currently, a f-string is not recognized as a docstring:
> >
> >>>> class C: f"foo"
> >>>> C.__doc__
> >>>>
> > This means you need to use a (admittedly easy) workaround:
> >
> >>>> class C: __doc__ = f"foo"
> >>>> C.__doc__
> > 'foo'
> >
> > Shouldn't the former be allowed for convenience?
> >
> > Regards
> >
> > Antoine.
> >
> >
> > _______________________________________________
> > Python-Dev mailing list -- pytho...@python.org
> > To unsubscribe send an email to python-d...@python.org
> > https://mail.python.org/mailman3/lists/python-dev.python.org/
> > Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/UALMEMQ4QW7W4HE2PIBARWYBKFWJZFB4/
> > Code of Conduct: http://python.org/psf/codeofconduct/



_______________________________________________
Python-Dev mailing list -- pytho...@python.org
To unsubscribe send an email to python-d...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/

Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/37YAHCREZYZFSV4BRDKUEQAX4ZF4JTI6/

[Guido van Rossum]

I personally think F-strings should not be usable as docstrings. If you want a dynamically calculated docstring you should assign it dynamically, not smuggle it in using a string-like expression. We don't allow "blah {x} blah".format(x=1) as a docstring either, not "foo %s bar" % x.

--

--Guido van Rossum (python.org/~guido)

Pronouns: he/him (why is my pronoun here?)

[Gregory P. Smith]

On Tue, Jan 11, 2022 at 10:29 AM Guido van Rossum <gu...@python.org> wrote:

I personally think F-strings should not be usable as docstrings. If you want a dynamically calculated docstring you should assign it dynamically, not smuggle it in using a string-like expression. We don't allow "blah {x} blah".format(x=1) as a docstring either, not "foo %s bar" % x.

Agreed.  If we wanted to remove the wart of constant f-strings happening to work as an implementation detail in this context, that could be made into a warning.  But that kind of check may be best left to a linter for all of these dynamic situations that don't wind up populating __doc__.

-gps

 

Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/35R3DCNPIQJ7ZCHTLP64IP2XZCK7QSLJ/

[Brett Cannon]

On Tue, Jan 11, 2022 at 10:40 AM Gregory P. Smith <gr...@krypto.org> wrote:

On Tue, Jan 11, 2022 at 10:29 AM Guido van Rossum <gu...@python.org> wrote:

I personally think F-strings should not be usable as docstrings. If you want a dynamically calculated docstring you should assign it dynamically, not smuggle it in using a string-like expression. We don't allow "blah {x} blah".format(x=1) as a docstring either, not "foo %s bar" % x.

Agreed.  If we wanted to remove the wart of constant f-strings happening to work as an implementation detail in this context, that could be made into a warning.  But that kind of check may be best left to a linter for all of these dynamic situations that don't wind up populating __doc__.

Agreed on not supporting it and linters catching such a mistake.

-Brett

 

Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/QFGCXW25TZOMEN2DRVLDQ4XQQSYNNTI7/

[Eric V. Smith]

On 1/11/2022 3:44 PM, Brett Cannon wrote:

On Tue, Jan 11, 2022 at 10:40 AM Gregory P. Smith <gr...@krypto.org> wrote:

On Tue, Jan 11, 2022 at 10:29 AM Guido van Rossum <gu...@python.org> wrote:

I personally think F-strings should not be usable as docstrings. If you want a dynamically calculated docstring you should assign it dynamically, not smuggle it in using a string-like expression. We don't allow "blah {x} blah".format(x=1) as a docstring either, not "foo %s bar" % x.

Agreed.  If we wanted to remove the wart of constant f-strings happening to work as an implementation detail in this context, that could be made into a warning.  But that kind of check may be best left to a linter for all of these dynamic situations that don't wind up populating __doc__.

Agreed on not supporting it and linters catching such a mistake.

Just to be clear, we don't support this.

>>> class C: 'foo'
...
>>> C.__doc__ == 'foo'
True

>>> class C: f'foo'
...
>>> C.__doc__ == 'foo'
False
>>> C.__doc__ is None
True

And there's a test to make sure constant f-strings are not doc strings: https://github.com/python/cpython/blob/dce642f24418c58e67fa31a686575c980c31dd37/Lib/test/test_fstring.py#L406

Eric

Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/J5EMBDNY52ZHZPPUZSRUOCUYF4RCSRZH/

[Neil Muller]

On Wed, 12 Jan 2022 at 00:12, Eric V. Smith <er...@trueblade.com> wrote:
>
> On 1/11/2022 3:44 PM, Brett Cannon wrote:
>
>
>
> >>> class C: 'foo'
> ...
> >>> C.__doc__ == 'foo'
> True
>
> >>> class C: f'foo'
> ...
> >>> C.__doc__ == 'foo'
> False
> >>> C.__doc__ is None
> True
>
> And there's a test to make sure constant f-strings are not doc strings: https://github.com/python/cpython/blob/dce642f24418c58e67fa31a686575c980c31dd37/Lib/test/test_fstring.py#L406
>

Having something that looks like it sets the docstring, but silently
doesn't is very surprising, though. Linters can warn about this, but
linters are not a universal fix, and this is something that
superficially looks entirely reasonable.

--
Neil Muller
drnlm...@gmail.com

_______________________________________________
Python-Dev mailing list -- pytho...@python.org
To unsubscribe send an email to python-d...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/

Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/V3RS2Y2FGTIWLUMBAMJKRGHXUF4HUN2J/

[Steven Barker]

On Wed, Jan 12, 2022 at 2:58 AM Neil Muller <drnlmull...@gmail.com> wrote:

Having something that looks like it sets the docstring, but silently
doesn't is very surprising, though. Linters can warn about this, but
linters are not a universal fix, and this is something that
superficially looks entirely reasonable.

While f-strings in class scope could theoretically be valid docstrings a lot of the time, the equivalent situation for function docstrings is much less positive. A function like this the one below obviously problematic, since the f-string value is not a compile-time constant:

def foo(x): f"is this a docstring? x is {x}"

I'm pretty sure f-strings cannot be used as docstrings in other contexts because of how broken they'd be in functions.

--

Steven Barker

[Neil Muller]

On Thu, 13 Jan 2022 at 02:31, Steven Barker <blck...@gmail.com> wrote:
>
> While f-strings in class scope could theoretically be valid docstrings a lot of the time, the equivalent situation for function docstrings is much less positive. A function like this the one below obviously problematic, since the f-string value is not a compile-time constant:
>
> def foo(x): f"is this a docstring? x is {x}"
>
> I'm pretty sure f-strings cannot be used as docstrings in other contexts because of how broken they'd be in functions.
>

I don't have a horse in the race of whether this should be allowed or
not for constant f-strings. I do however believe that having something
like the example given previously where the code doesn't do what it
appears to do, by silently not setting the docstring without giving a
warning, is bad behaviour.

--
Neil Muller
drnlm...@gmail.com
_______________________________________________
Python-Dev mailing list -- pytho...@python.org
To unsubscribe send an email to python-d...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/

Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/Y3AVDHPBVEEJERIG2P326XHR5FT6UAH5/

[Steve Holden]

On Tue, Jan 11, 2022 at 6:24 PM Guido van Rossum <gu...@python.org> wrote:

I personally think F-strings should not be usable as docstrings. If you want a dynamically calculated docstring you should assign it dynamically, not smuggle it in using a string-like expression. We don't allow "blah {x} blah".format(x=1) as a docstring either, not "foo %s bar" % x.

I came to the conclusion that something like jinja2, operating on a Python template, was a better way to go.

[Jim J. Jewett]

Guido van Rossum wrote:
> I personally think F-strings should not be usable as docstrings. If you
> want a dynamically calculated docstring you should assign it dynamically,
> not smuggle it in using a string-like expression. We don't allow "blah {x}
> blah".format(x=1) as a docstring either, not "foo %s bar" % x.

Nor, last I checked, even "string1" + "string2", even though the result is a compile-time string in the appropriate location. I think all of these should be allowed, but I'll grant that annotations reduce the need. I'll even admit that scoping issues make the interpolating versions error prone, and the UI to clear that up may be more of a hassle than it is worth.

-jJ

_______________________________________________
Python-Dev mailing list -- pytho...@python.org
To unsubscribe send an email to python-d...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/

Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/ZUWTCGK6KZJYCUDRR3JNB7H5W3ZHJWMT/