formatted docstrings
Cameron Simpson
cs at cskk.id.au
Thu Apr 4 01:00:43 EDT 2019
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.
More information about the Python-list
mailing list