On Tue, Sep 16, 2008 at 07:10:59PM -0400, Fred Drake wrote: > The nested notation makes sense for optional arguments, especially where > keywords aren't supported. This is still the case for many of the APIs > written in C, and those cases often won't be changed due to performance > considerations. (Adding keyword support definitely slows things down.)
So, the use cases are: * Python code where arguments are both optional and specifiable as a keyword argument. * C code where keywords are supported. * C code where keywords are not supported. I think nesting the optional arguments doesn't actually indicate whether keywords are supported or not. For example, two functions from the socket module are: .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]]) .. method:: socket.recv_into(buffer[, nbytes[, flags]]) getaddrinfo() doesn't support keyword arguments; recv_into() does. But nesting the brackets does add a lot of typographical fluff. Can we invent a new notation for separating which functions support keywords and which don't? How would we render that distinction typographically in the output? Ideas: * Boldface parameters that can be provided as keywords. * Add '=' after parameters that can be provided as keywords: buffer=, [nbytes=, flags=] ... * Write keyword arguments as unnested square brackets: (buffer[, nbytes][, flags]) This reserves the nesting for functions that don't support keywords. I think the difflib docs are mostly written in this style. > So I guess now someone will tell me this has already been changed, and I > missed it. No, no one's made any changes relating to this yet. --amk _______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
