formatted docstrings

[Cameron Simpson]

On 04Apr2019 15:40, Ben Finney <ben+python at benfinney.id.au> wrote:
>Cameron Simpson <cs at cskk.id.au> writes:
>> To answer my own question ...
>> On 04Apr2019 14:05, Cameron Simpson <cs at cskk.id.au> wrote:
>> > 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.
>
>Another reason why docstrings should only be literals: a common use case
>is to evaluate the docstrings and put them into static reference
>documentation.

Yeah, I do that myself.

>If there's something about the API that will be different depending on
>where the API is running, but the API documentation just shows me some
>condition from when the documentation was built, that's a nasty surprise
>waiting to happen. [...]

Certainly that is a concern; I've been thinking just that in the last 
several minutes. But on that basis I intend to constrain my own use of 
this heavily; I've no intention of embedding dynamic information in 
docstrings, just "computable constants" for want of a better term.

My use case was wiring into the docstring the environment variable names 
which control some default behaviour, and those names are themselves 
constants(*) in the module - they may never change but the module puts 
their definitions at the top of the source code:

    DEFAULT_BLAH_ENVVAR = 'APP_BLAH'

Absent monkey patching, I wanted an end user to know the environment 
variable name directly without performing tedious source code 
inspection.

I'm certainly considering constructions like:

  Default value from os.environ[DEFAULT_BLAH_ENVVAR] i.e.  
  ${DEFAULT_BLAH_ENVVAR}.

which would turn into:

  Default value from os.environ[DEFAULT_BLAH_ENVVAR] i.e.
  $APP_BLAH.

though that is then harder to read, albeit more precise.

Cheers,
Cameron Simpson <cs at cskk.id.au>

* Yes I know Python doesn't have real constants, let's not bicker here.