On 04Apr2019 15:40, Ben Finney <ben+pyt...@benfinney.id.au> wrote:
Cameron Simpson <c...@cskk.id.au> writes:
To answer my own question ...
On 04Apr2019 14:05, Cameron Simpson <c...@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 <c...@cskk.id.au>
* Yes I know Python doesn't have real constants, let's not bicker here.
--
https://mail.python.org/mailman/listinfo/python-list
