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