Decoration and aliasing
Jeremy Dunck
Example:
==============
def decorate(f):
def wrap(*args, **kwargs):
print "called"
return f(*args, **kwargs)
return wrap
@decorate
def add_to(augend, addend):
"Adds stuff"
return augend + addend
Introspecting add_to, undecorated, would have a __name__ of 'add_to'
and __doc__ of 'Adds stuff'.
After decorating, add_to.__name__ becomes 'wrap' and __doc__ becomes None.
================
In Python 2.5+, there's functools.wraps, which takes care of the
problem of introspection on decorated functions by copying attributes
from the wrapped function.
http://docs.python.org/lib/module-functools.html
Since Django already includes curry, which is roughly the same as
functools.partial, it'd be pretty easy to back-port "wraps" to Django.
Is there any interest in a patch that modifies Django's built-in
decorators to use functools.wraps in order to preserve things like
view function doc strings?
....While I'm at it, I think aliasing functools.partial to
functional.curry would be good, assuming functools is available.
Marty Alchin
> functools.partial, it'd be pretty easy to back-port "wraps" to Django.
>
> Is there any interest in a patch that modifies Django's built-in
> decorators to use functools.wraps in order to preserve things like
> view function doc strings?
I love functools.wraps, but I never considered back-porting it in pure
Python like curry. I'd personally love to see this happen, and I'd be
glad to help out if you need it.
OT: I hope nobody uses this as an opportunity to complain about the
naming of "curry". There was some discussion pre-2.5 about the
difference between functools.partial and a true curry, but I don't
think it's not worth making that distinction now.
-Gul
Malcolm Tredinnick
[...]
> Is there any interest in a patch that modifies Django's built-in
> decorators to use functools.wraps in order to preserve things like
> view function doc strings?
Definitely interest from me. It's a bit of a bug at the moment that we
lose docstrings when we decorate things. Particular admin-docs loses
stuff.
So, yeah, go for it.
>
> ....While I'm at it, I think aliasing functools.partial to
> functional.curry would be good, assuming functools is available.
Providing the functionality is identical. Otherwise it's really, really
painful to work out why things are behaving differently. We don't appear
to be dramatically missing anything in our current currying stuff, so if
this change would introduce different behaviour between 2.3 and, say,
2.5, I'd be against it.
Regards,
Malcolm
Marty Alchin
> > ....While I'm at it, I think aliasing functools.partial to
> > functional.curry would be good, assuming functools is available.
>
> Providing the functionality is identical. Otherwise it's really, really
> painful to work out why things are behaving differently. We don't appear
> to be dramatically missing anything in our current currying stuff, so if
> this change would introduce different behaviour between 2.3 and, say,
> 2.5, I'd be against it.
For some reason, I seem to recall there was some difference in how
partial handles duplicate keyword arguments in the final call, as
opposed to how curry does it. But when I actually do a side-by-side
now, I can't discover any differences. So either I haven't figured out
what I was doing before, or I was just smoking something at the time.
-Gul
Jeremy Dunck
> [...]
> > Is there any interest in a patch that modifies Django's built-in
> > decorators to use functools.wraps in order to preserve things like
> > view function doc strings?
>
> Definitely interest from me. It's a bit of a bug at the moment that we
> lose docstrings when we decorate things. Particular admin-docs loses
> stuff.
functools.wraps keeps these:
WRAPPER_ASSIGNMENTS = ('__module__', '__name__', '__doc__')
WRAPPER_UPDATES = ('__dict__',)
> >
> > ....While I'm at it, I think aliasing functools.partial to
> > functional.curry would be good, assuming functools is available.
>
> Providing the functionality is identical. Otherwise it's really, really
> painful to work out why things are behaving differently. We don't appear
> to be dramatically missing anything in our current currying stuff, so if
> this change would introduce different behaviour between 2.3 and, say,
> 2.5, I'd be against it.
As far as I'm aware, the semantics are the same.
But on closer inspection, functools.partial actually returns a new
type rather than a simple function. Things like inspect.getargspec
fail on the result from functools.partial. With that in mind, I'll
leave it out.
Jeremy Dunck
> On 10/4/07, Malcolm Tredinnick <mal...@pointy-stick.com> wrote:
> >
> > On Thu, 2007-10-04 at 15:15 -0500, Jeremy Dunck wrote:
> > [...]
> > > Is there any interest in a patch that modifies Django's built-in
> > > decorators to use functools.wraps in order to preserve things like
> > > view function doc strings?
> >
> > Definitely interest from me. It's a bit of a bug at the moment that we
> > lose docstrings when we decorate things. Particular admin-docs loses
> > stuff.
So, I've found a couple decorators I never knew existed. :)
Is there a reason django.views.http.require_http_method and friends
aren't documented?
I can add docs and tests...
Jacob Kaplan-Moss
> So, I've found a couple decorators I never knew existed. :)
>
> Is there a reason django.views.http.require_http_method and friends
> aren't documented?
Ha - I'd forgotten about those myself :)
> I can add docs and tests...
Yes, please!
Jacob
Jeremy Dunck
> [...]
> > Is there any interest in a patch that modifies Django's built-in
> > decorators to use functools.wraps in order to preserve things like
> > view function doc strings?
>
> Definitely interest from me. It's a bit of a bug at the moment that we
> lose docstrings when we decorate things. Particular admin-docs loses
> stuff.
>
> So, yeah, go for it.
Patch attached to this ticket:
http://code.djangoproject.com/ticket/5701
I note that this is a (perhaps subtle-enough) backwards-incompatible change.
Jacob Kaplan-Moss
> I note that this is a (perhaps subtle-enough) backwards-incompatible change.
Can you say a bit more about how this is backwards-incompatible? I'm
having a dense morning, and can't seem to see any breakage here (which
is a good thing!)
Jacob
Jacob Kaplan-Moss
Oh yeah, and one other thing:
IANAL, but I think the Python Software License is not compatible with
the BSD, so we'll need permission from the PSF to distribute code
copied from functools.py, and we'll need to include the original
copyright statement.
I notice as I write this that we only sorta followed this approach in
the other bits from Python (_threading_local and _decimal). That
really needs to be fixed. Grumble.
Jacob
Forest Bond
I think Jeremy was simply pointing out that object attributes are being
permanently changed and somebody, somewhere may be relying on them currently.
In this particular case that seems unlikely, of course.
-Forest
--
Forest Bond
http://www.alittletooquiet.net
Jeremy Dunck
I just mean that current code doing naive introspection is getting
decorator names rather than decorated names, and going forward it'll
get the decorated name, etc.
That's the intent, but it is a change to existing (undocumented) functionality.
Jeremy Dunck
Should I follow up on this with the Python mailing list, or will you?
Jeremy Dunck
*ping*
Is this another thing held up by the need to create the Django Foundation? :)
Jacob Kaplan-Moss
I'd love it if you could - thanks!
Jacob
Jeremy Dunck
OK, I quickly dug through the mailing list archives to see which one to post to.
In doing so, I found a short thread on decimal inclusion for Django:
http://mail.python.org/pipermail/python-dev/2007-February/thread.html#71324
Did you know about that thread, or does it simply fall short of the
needed clarity?
"You don't need my permission, but you have it" is hardly strong provenance.
On the bright side, the license page[1] makes the assertion that the
same license applies to all python-distributed files.
Original copyright seems to point to [2]:
Peter Harris scav at blueyonder.co.uk [3]
Nick Coghlan ncoghlan at iinet.net.au [4]
This list is not comprehensive. I don't have a python 2.5 source
checkout handy, so need to wait to look at commit history.
Surprisingly, http://svn.python.org/view/ is apparently down right
now!
Also, regarding code apparently shared on mailing lists, python has this to say:
"
Be aware of intellectual property when handling patches. Any code with
no copyright will fall under the copyright of the Python Software
Foundation. If you have no qualms with that, wonderful; this is the
best solution for Python. But if you feel the need to include a
copyright then make sure that it is compatible with copyright used on
Python (i.e., BSD-style). The best solution, though, is to sign the
copyright over to the Python Software Foundation.
" from: http://www.python.org/dev/intro/
Even so, it seems PSF does not require a contributor agreement,
leaving it to the contributor's promise that the code offered and
shared is actually hers to give.
...Is this the line of work you were thinking? Have I missed anything
(other than actually finishing compiling the list of contributors and
getting their permission...)?
[1]
http://www.python.org/psf/license/
[2]
http://mail.python.org/pipermail/python-dev/2006-April/064620.html
Thread continues:
http://mail.python.org/pipermail/python-dev/2006-May/thread.html#64653
http://mail.python.org/pipermail/python-dev/2006-May/thread.html#64698
[3]
http://www.python.org/dev/peps/pep-0309/ author
[4] The author of the list message introducing the implementation of
functools.partial
Gary Wilson
> Oh yeah, and one other thing:
>
> IANAL, but I think the Python Software License is not compatible with
> the BSD, so we'll need permission from the PSF to distribute code
> copied from functools.py, and we'll need to include the original
> copyright statement.
Any headway on this?
These seem to be the pertinent clauses of the PSF license (taken from the
official license for the Python 2.5 release [1]):
"""
2. Subject to the terms and conditions of this License Agreement, PSF
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python
alone or in any derivative version, provided, however, that PSF's
License Agreement and PSF's notice of copyright, i.e., "Copyright (c)
2001, 2002, 2003, 2004, 2005, 2006 Python Software Foundation; All Rights
Reserved" are retained in Python alone or in any derivative version
prepared by Licensee.
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python or any part thereof, and wants to make
the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python.
"""
So it seems as if we need to put the PSF copyright in the file, distribute a
copy of the License Agreement, and add a summary of changes if we make any
alterations.
Gary