[Python-Dev] decorator module in stdlib?

[Daniel Fetchinson]

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

My original suggestion for inclusion in stdlib was motivated by this
reason alone: I'd like to see an official one way of preserving
function signatures by decorators. If there are better ways of doing
it than the decorator module, that's totally fine, but there should be
one.


Cheers,
Daniel

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




-- 
Psss, psss, put it down! - http://www.cafepress.com/putitdown