[issue40054] Allow formatted strings as docstrings

[Richard Neumann]

New submission from Richard Neumann <mail at richard-neumann.de>:

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.

----------
messages: 364934
nosy: conqp
priority: normal
severity: normal
status: open
title: Allow formatted strings as docstrings
type: enhancement
versions: Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40054>
_______________________________________