classification
Title: Allow formatted strings as docstrings
Type: enhancement Stage: resolved
Components: Versions: Python 3.9
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: Nosy List: conqp, eric.smith, xtreak
Priority: normal Keywords:

Created on 2020-03-24 15:29 by conqp, last changed 2020-03-25 06:44 by serhiy.storchaka. This issue is now closed.

Messages (3)
msg364934 - (view) Author: Richard Neumann (conqp) * Date: 2020-03-24 15:29
Currently only plain strings can be used as docstrings, such as:


    class Foo:
        """Spamm eggs."""

For dynamic class generation, it would be useful to allow format strings as docstrings as well:

    doc = 'eggs'

    class Foo:
        """Spamm {}.""".format(doc)

or:

    doc = 'eggs'

    class Foo:
        f"""Spamm {doc}."""

A current use case in which I realized that this feature was missing is:


    class OAuth2ClientMixin(Model, ClientMixin):   # pylint: disable=R0904
        """An OAuth 2.0 client mixin for peewee models."""

        <snip>

        @classmethod
        def get_related_models(cls, model=Model):
            """Yields related models."""
            for mixin, backref in CLIENT_RELATED_MIXINS:
                yield cls._get_related_model(model, mixin, backref)

        @classmethod
        def _get_related_model(cls, model, mixin, backref):
            """Returns an implementation of the related model."""
            class ClientRelatedModel(model, mixin):
                f"""Implementation of {mixin.__name__}."""
                client = ForeignKeyField(
                    cls, column_name='client', backref=backref,
                    on_delete='CASCADE', on_update='CASCADE')

            return ClientRelatedModel

It actually *is* possible to dynamically set the docstring via the __doc__ attribute:

    doc = 'eggs'

    class Foo:
        pass

    Foo.__doc__ = doc


Allowing format strings would imho be more obvious when reading the code as it is set, where a docstring is expected i.e. below the class / function definition.
msg364936 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2020-03-24 15:54
The problem is that __doc__ is set at compile time, not run time. The ''.format call (and f-strings) are evaluated at run time.
msg364939 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2020-03-24 16:19
See also https://bugs.python.org/issue28739
History
Date User Action Args
2020-03-25 06:44:41serhiy.storchakasetstatus: open -> closed
resolution: rejected
stage: resolved
2020-03-24 16:19:23xtreaksetnosy: + xtreak
messages: + msg364939
2020-03-24 15:54:09eric.smithsetnosy: + eric.smith
messages: + msg364936
2020-03-24 15:29:16conqpcreate