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@[...].net>         The highway is for gamblers,
San Francisco Bay Area, California    better use your sense - B. Dylan

_______________________________________________
Doc-SIG maillist  -  Doc-SIG@[...].org
http://mail.python.org/mailman/listinfo/doc-sig