[Doc-SIG] Proposal: don't nest optional brackets
Mark Sapiro
mark at msapiro.net
Mon Jun 23 05:10:09 CEST 2008
Georg Brandl wrote:
>A.M. Kuchling schrieb:
>> To show a series of optional parameters, currently we nest square
>> brackets.
>>
>> http://docs.python.org/dev/library/warnings.html#warnings.filterwarnings
>>
>> warnings.filterwarnings(action[, message[, category[, module[,
>> lineno[, append]]]]])
>>
>> My proposal is that we drop the nesting and write this as:
>>
>> warnings.filterwarnings(action [, message, category, module, lineno, append])
[...]
>> What does everyone think?
>
>I'm +0. I'd like to hear Fred's opinion since (I guess) he introduced the
>nested bracket notation. If he's okay with it, I'll write a script that
>converts the signatures in the whole documentation.
The nested bracket notation has been around for a very long time. It is
used primarily to indicate positional arguments, any of which may
logically be omitted, but all those to the left of the desired
argument must be specified because of the positional nature of the
arguments.
Of course, the Pythonic thing is to specify just the desired arguments
as keyword arguments and allow the rest to assume their defaults. I
think that the strict notation to express this might be something like
warnings.filterwarnings(action[, message=][, category=][, module=][,
lineno=][, append])
but perhaps
warnings.filterwarnings(action[, message, category, module, lineno,
append])
is understood in a Python context to mean the same thing.
+0
--
Mark Sapiro <mark at msapiro.net> The highway is for gamblers,
San Francisco Bay Area, California better use your sense - B. Dylan
More information about the Doc-SIG
mailing list