[Python-Dev] decorator support

[Edward Loper]

Raymond wrote:
> So, it would be nice if there were some support for carrying forward 
> the
> argspec to inform help(), calltips(), and inspect().

+1.  I've already gotten one complaint about decorators confusing 
epydoc (since the user wasn't copying the function's __name__), and I 
expect to get many more.  One thing that's always bothered me about 
classmethod and staticmethod is the fact that you can't inspect them.  
Compare that to instancemethod, which has the im_func property.

One way to carry forward the argspec would be to recommend that 
decorators add a pointer back to the undecorated function (similar to 
instancemethod's im_func):

   newf.__doc__  = oldf.__doc__        # copy the docstring
   newf.__dict__.update(oldf.__dict__) # copy attributes
   newf.__name__ = oldf.__name__       # keep the name (new in Py2.4)
   newf.__undecorated__ = oldf         # [XX NEW] ptr to undecorated obj

Then tools like pydoc/epydoc could be written to check this property 
for the real argspec.  (Note that there's precedent for showing the 
*undecorated* signature in tools like pydoc/epydoc, since that's what 
they both do with instancemethods, classmethods, and staticmethods).

We would want to pick a standard name.  __undecorated__ seems 
reasonable to me, but I'd be ok with other names.

Martin v. Lowis wrote:
> What were you thinking of? I could imagine a predefined class, such as
> class copyfuncattrs: [...]

This function could take care of adding the __undecorated__ attribute.  
But I'm not sure copyfuncattrs is the right name; note that it works 
just as well on class decorators (we did decide that we're allowing 
those, right?).  Perhaps just copyattrs?

Martin v. Lowis wrote:
> Then, the question is where copyfuncattrs should live, and I would
> object that to be yet another builtin.

Having trouble parsing this sentence -- do you mean that you object to 
making it a builtin, or did you mean "I would expect that to be..."?

Anthony Baxter wrote:
> I think it's very likely that in 2.5 we'll have some sort of
> 'decorators' module that captures these sorts of things. I
> don't think it's likely we'll know enough about the various ins
> and outs of decorators to want to put something in 2.4.

I disagree.  We may not know much about the ins and outs of decorators, 
but I feel very confident that I'll want to be able to inspect them, 
whatever they are.  I would very much like for one of the following to 
happen *before* we release 2.4:

   - Add a prominent note in the docs on decorators that decorators 
should
     generally copy the original object's __doc__, __name__, and
     attributes, unless there's a good reason not to.  (Also, create an
     __undecorated__ property, but I'll wait to see what others see about
     that idea first.)

   - Add copyfuncattrs to the standard library (or builtins), and add a
     prominent note to the docs that you should use it unless you have a
     good reason not to.

(I can write up an appropriate patch for the docs if no one objects; 
for copyfuncattrs, we'd need to decide what to name it and where it 
should live, first.)

-Edward