formatted docstrings

[Cameron Simpson]

To answer my own question ...

On 04Apr2019 14:05, Cameron Simpson <cs at cskk.id.au> wrote:
>I just wrote this (specifics changed for confidentiality reasons):
> DEFAULT_ENVVAR = 'APP_VALUE'
> def get_handle(setting=None):
>   f'''Get a handle.
>       Parameter:
>       * `setting`: the application setting.
>         Default from the {DEFAULT_ENVVAR} environment variable.
>   '''
>   if setting is None:
>     setting = os.environ[DEFAULT_ENVVAR]
>
>I thought this was way cool. Until I disovered that there was no 
>docstring because a format string is not a string literal.
>
>Is it unreasonable to promote bare format strings as candidates for the 
>docstring?

Sigh. Because such a string _should_ be evaluated in the runtime scope 
context of the _called_ function, and it hasn't been called. The current 
restriction to string literals (i.e. excluding formatted strings) has no 
such ambiguity.

To make the problem with my suggestion clear, to allow a formatted 
docstring like the above a function like this:

  def f():
    f'docstring {foo}'
    foo = 9
    f'docstring {foo}'

would want to evaluate the first and second f'' string values with 
different scope rules, which would be bonkers.

A workaround would look like this:

  def f():
    ....
  f.__doc__ = f'docstring {foo}'

which is annoying, but correct.

Sorry to have bothered everyone,
Cameron Simpson <cs at cskk.id.au>