[Python-Dev] decorator module in stdlib? (original) (raw)

Guido van Rossum guido at python.org
Fri Apr 10 05:55:34 CEST 2009

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: updatewrapper 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.

For instance, if I see a method

getuser(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 getuser(*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.

 I hate losing information about the true signature of functions, since I also use a lot IPython, Python help, etc.

I guess we just have different styles. That's fine.

I must admit that while I still like decorators, I do like them as much as in the past. Of course there was a missing NOT in this sentence, but you all understood the intended meaning. (All this BTW is not to say that I don't trust you with commit privileges if you were to be interested in contributing. I just don't think that adding that particular decorator module to the stdlib would be wise. It can be debated though.) Fine. As I have repeated many time that particular module was never meant for inclusion in the standard library.

Then perhaps it shouldn't -- I haven't looked but if you don't plan stdlib inclusion it is often the case that the API style and/or implementation details make stdlib inclusion unrealistic. (Though admittedly some older modules wouldn't be accepted by today's standards either -- and I'm not just talking PEP-8 compliance! :-)

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.

I do not think everybody disagree with your point here. My point still stands, though: objects should not lie about their signature, especially during  debugging and when generating documentation from code.

Source code never lies. Debuggers should make access to the source code a key point. And good documentation should be written by a human, not automatically cobbled together from source code and a few doc strings.

-- --Guido van Rossum (home page: http://www.python.org/~guido/)

More information about the Python-Dev mailing list