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. 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 strings. -- --Guido van Rossum (home page: http://www.python.org/~guido/) _______________________________________________ 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
