[Python-Dev] decorator module in stdlib?

[Michael Foord]

Guido van Rossum wrote:
> On Wed, Apr 8, 2009 at 9:31 PM, Michele Simionato
> <michele.simionato at gmail.com> wrote:
>   
>> Then perhaps you misunderstand the goal of the decorator module.
>> The raison d'etre of the module is to PRESERVE the signature:
>> update_wrapper unfortunately *changes* it.
>>
>> When confronted with a library which I do not not know, I often run
>> over it pydoc, or sphinx, or a custom made documentation tool, to extract the
>> signature of functions.
>>     
>
> Ah, I see. Personally I rarely trust automatically extracted
> documentation -- too often in my experience it is out of date or
> simply absent. Extracting the signatures in theory wouldn't lie, but
> in practice I still wouldn't trust it -- not only because of what
> decorators might or might not do, but because it might still be
> misleading. Call me old-fashioned, but I prefer to read the source
> code.
>   

If you auto-generate API documentation by introspection (which we do at 
Resolver Systems) then preserving signatures can also be important. 
Interactive use (support for help), and more straightforward tracebacks 
in the event of usage errors are other reasons to want to preserve 
signatures and function name.

>  For instance, if I see a method
>   
>> get_user(self, username) I have a good hint about what it is supposed
>> to do. But if the library (say a web framework) uses non signature-preserving
>> decorators, my documentation tool says to me that there is function
>> get_user(*args, **kwargs) which frankly is not enough [this is the
>> optimistic case, when the author of the decorator has taken care
>> to preserve the name of the original function].
>>     
>
> But seeing the decorator is often essential for understanding what
> goes on! Even if the decorator preserves the signature (in truth or
> according inspect), many decorators *do* something, and it's important
> to know how a function is decorated. For example, I work a lot with a
> small internal framework at Google whose decorators can raise
> exceptions and set instance variables; they also help me understand
> under which conditions a method can be called.
>   

Having methods renamed to 'wrapped' and their signature changed to 
*args, **kwargs may tell you there *is* a decorator but doesn't give you 
any useful information about what it does. If you look at the code then 
the decorator is obvious (whether or not it mangles the method)...
> [+1]
>> But I feel strongly about
>> the possibility of being able to preserve (not change!) the function
>> signature.
>>     
>
> That could be added to functools if enough people want it.
>
>   

+1

Michael


-- 
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog