Guido van Rossum wrote:
On Wed, Apr 8, 2009 at 9:31 PM, Michele Simionato
<michele.simion...@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
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
