It's fairly well-known that decorators are useful, but raises some issues.

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.

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

[...]

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.

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

On 10/4/07, Malcolm Tredinnick <malc...@pointy-stick.com> wrote:

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

On 10/4/07, Malcolm Tredinnick <malc...@pointy-stick.com> wrote:

functools.wraps keeps these:
WRAPPER_ASSIGNMENTS = ('__module__', '__name__', '__doc__')
WRAPPER_UPDATES = ('__dict__',)

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.

On 10/4/07, Jeremy Dunck <jdu...@gmail.com> wrote:

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

On 10/5/07, Jeremy Dunck <jdu...@gmail.com> wrote:

Ha - I'd forgotten about those myself :)

Yes, please!

Jacob

On 10/4/07, Malcolm Tredinnick <malc...@pointy-stick.com> wrote:

Patch attached to this ticket:
http://code.djangoproject.com/ticket/5701

I note that this is a (perhaps subtle-enough) backwards-incompatible change.

On 10/7/07, Jeremy Dunck <jdu...@gmail.com> wrote:

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

On 10/7/07, Jeremy Dunck <jdu...@gmail.com> wrote:

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

Hi,

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

signature.asc < 1K Download

On 10/8/07, Jacob Kaplan-Moss <jacob.kaplanm...@gmail.com> wrote:

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.

On 10/8/07, Jacob Kaplan-Moss <jacob.kaplanm...@gmail.com> wrote:

Should I follow up on this with the Python mailing list, or will you?

On 10/8/07, Jeremy Dunck <jdu...@gmail.com> wrote:

*ping*

Is this another thing held up by the need to create the Django Foundation?  :)

On 10/8/07, Jeremy Dunck <jdu...@gmail.com> wrote:

I'd love it if you could - thanks!

Jacob

On 10/11/07, Jacob Kaplan-Moss <jacob.kaplanm...@gmail.com> wrote:

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

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

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

[1] http://www.python.org/download/releases/2.5.1/license/