Minor inconvenience: f-string not recognized as docstring
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.
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
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 -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/UALMEMQ4... Code of Conduct: http://python.org/psf/codeofconduct/
On Tue, 11 Jan 2022 10:58:03 -0500 "Eric V. Smith" eric@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 -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/UALMEMQ4... Code of Conduct: http://python.org/psf/codeofconduct/
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.
On Tue, Jan 11, 2022 at 8:12 AM Antoine Pitrou antoine@python.org wrote:
On Tue, 11 Jan 2022 10:58:03 -0500 "Eric V. Smith" eric@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 -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at
https://mail.python.org/archives/list/python-dev@python.org/message/UALMEMQ4...
Code of Conduct: http://python.org/psf/codeofconduct/
Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/37YAHCRE... Code of Conduct: http://python.org/psf/codeofconduct/
On Tue, Jan 11, 2022 at 10:29 AM Guido van Rossum guido@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
On Tue, Jan 11, 2022 at 8:12 AM Antoine Pitrou antoine@python.org wrote:
On Tue, 11 Jan 2022 10:58:03 -0500 "Eric V. Smith" eric@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 -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at
https://mail.python.org/archives/list/python-dev@python.org/message/UALMEMQ4...
Code of Conduct: http://python.org/psf/codeofconduct/
Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/37YAHCRE... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido) *Pronouns: he/him **(why is my pronoun here?)* http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-change-the-world/ _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/35R3DCNP... Code of Conduct: http://python.org/psf/codeofconduct/
On Tue, Jan 11, 2022 at 10:40 AM Gregory P. Smith greg@krypto.org wrote:
On Tue, Jan 11, 2022 at 10:29 AM Guido van Rossum guido@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
-gps
On Tue, Jan 11, 2022 at 8:12 AM Antoine Pitrou antoine@python.org wrote:
On Tue, 11 Jan 2022 10:58:03 -0500 "Eric V. Smith" eric@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 -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at
https://mail.python.org/archives/list/python-dev@python.org/message/UALMEMQ4...
Code of Conduct: http://python.org/psf/codeofconduct/
Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/37YAHCRE... Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido) *Pronouns: he/him **(why is my pronoun here?)* http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-change-the-world/ _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/35R3DCNP... Code of Conduct: http://python.org/psf/codeofconduct/
Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/QFGCXW25... Code of Conduct: http://python.org/psf/codeofconduct/
On 1/11/2022 3:44 PM, Brett Cannon wrote:
On Tue, Jan 11, 2022 at 10:40 AM Gregory P. Smith greg@krypto.org wrote:
On Tue, Jan 11, 2022 at 10:29 AM Guido van Rossum <guido@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/dce642f24418c58e67fa31a686575c980c31d...
Eric
-Brett
-gps On Tue, Jan 11, 2022 at 8:12 AM Antoine Pitrou <antoine@python.org> wrote: On Tue, 11 Jan 2022 10:58:03 -0500 "Eric V. Smith" <eric@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 -- python-dev@python.org > > To unsubscribe send an email to python-dev-leave@python.org > > https://mail.python.org/mailman3/lists/python-dev.python.org/ > > Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/UALMEMQ4QW7W4HE2PIBARWYBKFWJZFB4/ > > Code of Conduct: http://python.org/psf/codeofconduct/ _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/37YAHCREZYZFSV4BRDKUEQAX4ZF4JTI6/ Code of Conduct: http://python.org/psf/codeofconduct/ -- --Guido van Rossum (python.org/~guido <http://python.org/~guido>) /Pronouns: he/him //(why is my pronoun here?)/ <http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-change-the-world/> _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/35R3DCNPIQJ7ZCHTLP64IP2XZCK7QSLJ/ Code of Conduct: http://python.org/psf/codeofconduct/ _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/QFGCXW25TZOMEN2DRVLDQ4XQQSYNNTI7/ Code of Conduct: http://python.org/psf/codeofconduct/
Python-Dev mailing list --python-dev@python.org To unsubscribe send an email topython-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived athttps://mail.python.org/archives/list/python-dev@python.org/message/J5EMBDNY... Code of Conduct:http://python.org/psf/codeofconduct/
On Wed, 12 Jan 2022 at 00:12, Eric V. Smith eric@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/dce642f24418c58e67fa31a686575c980c31d...
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.
On Wed, Jan 12, 2022 at 2:58 AM Neil Muller drnlmuller+python@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
On Thu, 13 Jan 2022 at 02:31, Steven Barker blckknght@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.
On Tue, Jan 11, 2022 at 6:24 PM Guido van Rossum guido@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.
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
participants (9)
-
Antoine Pitrou -
Brett Cannon -
Eric V. Smith -
Gregory P. Smith -
Guido van Rossum -
Jim J. Jewett -
Neil Muller -
Steve Holden -
Steven Barker