Property decorator for python 2.4 (Python recipe) by George Sakkis

ActiveState Code (http://code.activestate.com/recipes/410698/)

class/metaclass. I think a metaclass is more useful and easier to read (in use, not necessarily in implementation) for this kind of thing. I've posted an example of this in my repository: http://svn.colorstudy.com/home/ianb/recipes/class_property.py <p>

I'll copy the actual code here:

real_property = property

class property_meta(type):

    def __new__(meta, class_name, bases, new_attrs):
        if bases == (object,):
            # The property class itself
            return type.__new__(meta, class_name, bases, new_attrs)
        fget = new_attrs.get('fget')
        fset = new_attrs.get('fset')
        fdel = new_attrs.get('fdel')
        fdoc = new_attrs.get('__doc__')
        return real_property(fget, fset, fdel, fdoc)

class property(object):

    __metaclass__ = property_meta

    def __new__(cls, fget=None, fset=None, fdel=None, fdoc=None):
        if fdoc is None and fget is not None:
            fdoc = fget.__doc__
        return real_property(fget, fset, fdel, fdoc)

A brief discussion: this is backward compatible, because property.__new__ produces a normal property instance when you call it (__new__ keeps property() from returning an instance of itself, instead returning an instances of the real property class). The metaclass causes subclasses of this custom property to return property instances again, instead of real subclasses. (There's a special case that keeps the property class itself from returning an property instances -- bases == (object,)). Though the use of "class" is unfortunate, I think this is otherwise an ideal syntax for creating properties. I wrote this code, but I know I've seen similar implementations elsewhere, so I can't claim it's my own novel idea. Ultimately you use it like:

class Angle(object):
    def __init__(self,rad):
        self._rad = rad

    class rad(property):
        '''The angle in radians'''
        def fget(self):
            return self._rad
        def fset(self,angle):
            if isinstance(angle,Angle): angle = angle.rad
            self._rad = angle

The two approaches (decorator vs metaclass) are pretty similar in usage, although completely different in implementation. The main difference in usage is the property "signature":

@Property
def rad():

with decorator versus

class rad(property):

with metaclass. None is IMO as good as a special property syntax or code blocks would allow, e.g. something like

rad = property:
    def fget(self): ...
    def fset(self): ...

I find decorators are closer though by being more explicit; the class declaration would be misleading to anyone not familiar with the mutated property().

An advantage of the metaclass solution is the backwards compatibility with the builtin property(); with the decorator, a new name ("Property") has to be defined.

The two approaches (decorator vs metaclass) are pretty similar in usage, although completely different in implementation. The main difference in usage is the property "signature":

@Property
def rad():

with decorator versus

class rad(property):

with metaclass. None is IMO as good as a special property syntax or code blocks would allow, e.g. something like

rad = property:
    def fget(self): ...
    def fset(self): ...

I find decorators are closer though by being more explicit; the class declaration would be misleading to anyone not familiar with the mutated property().

An advantage of the metaclass solution is the backwards compatibility with the builtin property(); with the decorator, a new name ("Property") has to be defined.

Alternate without a new decorator. Here's a way that doesn't require any new decorators:

class Example(object):

    @apply
    def myattr():
        doc = """This is the doc string."""

        def fget(self):
            return self._value

        def fset(self, value):
            self._value = value

        def fdel(self):
            del self._value

        return property(**locals())

backward compatible change to property. Your improvement on my recipe is great. Thanks.

I just wanted to suggest that it's possible to change the original property to take on this decorating behaviour in a backwards compatible way:

import sys

# changed name to use published cookbook idiom and to aid clarity
def nested_property(function):
    keys = 'fget', 'fset', 'fdel'
    func_locals = {'doc':function.__doc__}
    def probe_function(frame, event, arg):
        if event == 'return':
            locals = frame.f_locals
            func_locals.update(dict((k,locals.get(k)) for k in keys))
            sys.settrace(None)
        return probe_function
    sys.settrace(probe_function)
    function()
    return property(**func_locals)

old_property = property
def property(fget=None, fset=None, fdel=None, doc=None, nested=False):
  if nested:
    return nested_property
  else:
    return old_property(fget, fset, fdel, doc)

...


class Angle(object):
    def __init__(self,rad):
        self._rad = rad

    @property(nested=True)
    def rad():
        '''The angle in radians'''
        def fget(self):
            return self._rad
        def fset(self,angle):
            if isinstance(angle,Angle): angle = angle.rad
            self._rad = float(angle)

     ...

Apply is deprecated, and sys.settrace should not be abused this way. The apply function is deprecated. This is an abuse of sys.settrace, which should only be used for debuggers, profilers, and code coverage tools. (Also sys.settrace is implementation dependent.)

Abandoning both, you can accomplish something easier than the apply technique:

def newProp( fcn ):
    return property( **fcn() )

class Example(object):

    @newProp
    def myattr():
        doc = """This is the doc string."""

        def fget(self):
            return self._value

        def fset(self, value):
            self._value = value

        def fdel(self):
            del self._value

        return locals()

Check out my recipe:

Easy Property Creation in Python
http://code.activestate.com/recipes/576742/

One drawback I see with these approaches is that it removes the ability for derived classes to override and customize a particular method (such as a setter). In the traditional method, you still have a setter method in the base class that can be overridden to do something extra in the derived class in addition to what the base class does. On the other hand this does a pretty good job of encapsulation, so this could be a good thing depending on the situation.

Never mind what I said above, it seems like the property() hardcodes the method object from the base class, so even if derives classes override one of the accessors, the property will continue to use the base class methods.

Apologies for spamming, but needed to clarify the above as I found a workaround. If you use a lambda function instead of calling accessor directly, it will work just fine. E.g., "property(lambda self: self.getx(), lambda self, v: self.setx(v))" instead of "property(getx, setx)". Derived classes can then override getx/setx and it will work just fine.

I've tried this with Python 2.6.4, with the result below. I get a similar result with Python 3.1.

Where have I gone astray?

Colin W.

* Python 2.6.4 (r264:75708, Oct 26 2009, 08:23:19) [MSC v.1500 32 bit (Intel)] on win32. *

>>> 
[Dbg]>>> 
Traceback (most recent call last):
  File "<string>", line 129, in run
  File "C:\Python26\Lib\bdb.py", line 368, in run
    exec cmd in globals, locals
  File "C:\Documents and Settings\cjw\My Documents\My Downloads\StockData\recipe-410698-1.py", line 56, in <module>
    test()
  File "C:\Documents and Settings\cjw\My Documents\My Downloads\StockData\recipe-410698-1.py", line 4, in test
    class Angle(object):
  File "C:\Documents and Settings\cjw\My Documents\My Downloads\StockData\recipe-410698-1.py", line 8, in Angle
    @Property
  File "C:\Documents and Settings\cjw\My Documents\My Downloads\StockData\recipe-410698-1.py", line 52, in Property
    return property(**func_locals)
TypeError: property() got an unexpected keyword argument 'doc'



>>> 
[PM]>>>

Please ignore the 20-Jan-10 comment above.

Colin W.