Guido van Rossum wrote:
So while: fooble(arg) is pretty nasty, documentation that tells me that 'arg' is a string is probably enough to set me on the right track. But if the documentation tells me that arg is a thunk/block, that's almost certainly not enough to get me going. I also need to know how that thunk/block will be called.
This argument against thunks sounds bogus to me. The signature of any callable arguments is recursively part of the signature of the function you're documenting. Just like the element type of any sequence arguments is part of the argument type.
It wasn't really an argument against thunks. (See the disclaimer I gave at the bottom of my previous email.) Think of it as an early documentation request for the thunks in the language reference -- I'd like to see it remind users of thunks that part of the thunk-accepting function interface is the parameters the thunk will be called with, and that these should be documented.
In case my point about the difference between thunks and other callables (specifically decorators) slipped by, consider the documentation for staticmethod, which takes a callable. All the staticmethod documentation says about that callable's parameters is: "A static method does not receive an implicit first argument" Pretty simple I'd say. Or classmethod: "A class method receives the class as implicit first argument, just like an instance method receives the instance." Again, pretty simple. Why are these simple? Because decorators generally pass on pretty much the same arguments as the callables they wrap. My point was just that because thunks don't wrap other normal callables, they can't make such abbreviations.