[Python-Dev] decorator module in stdlib?

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

 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.

>  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

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

More information about the Python-Dev mailing list