[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

formatted docstrings

On 04Apr2019 15:40, Ben Finney <ben+python at> wrote:
>Cameron Simpson <cs at> writes:
>> To answer my own question ...
>> On 04Apr2019 14:05, Cameron Simpson <cs at> 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

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:


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

I'm certainly considering constructions like:

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

which would turn into:

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

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

Cameron Simpson <cs at>

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