formatted docstrings
Cameron Simpson
cs at cskk.id.au
Wed Apr 3 23:14:12 EDT 2019
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>
More information about the Python-list
mailing list