Easy property creation and control (Python recipe) by Kevin L. Sitze

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

#! /usr/bin/env python
######################################################################
#  Written by Kevin L. Sitze on 2008-05-03
#  This code may be used pursuant to the MIT License.
######################################################################

"""
Property
========
The Property class provides basic functionality that allows class
level control over how a particular attribute is managed.  In its
simplest form a Property attribute works exactly like a regular
attribute on an instance while providing documentation details
about the attribute accessible via the declaring class.

This class modifies how properties are created on a class.  The Python
documentation contains the following example:

class C(object):
    def __init__(self):
        self._x = None

    def getx(self):
        return self._x
    def setx(self, value):
        self._x = value
    def delx(self):
        del self._x
    x = property(getx, setx, delx, 'the "x" property.')

The equivalent using Property is as follows:

class C(object):
  x = Property('x', None)

>>> x = C()
>>> repr(x.x)
'None'
>>> C.x.__doc__
'the "x" property'

Need a read-only property?  Here is the Python example:

class Parrot(object):
    def __init__(self):
        self._voltage = 100000

    @property
    def voltage(self):
        'Get the current voltage.'
        return self._voltage

And here is the equivalent:

class Parrot(object):
    voltage = Property('voltage', 100000, Property.Mode.READ_ONLY, 'Get the current voltage')

If your class needs to write to a property that is intended to be
public read-only you can use the set_property() function.
"""

__all__ = ( 'Enum', 'Property' )

def Enum(*names):
    """See immutable symbolic enumeration types by Zoran Isailovski
    (see http://code.activestate.com/recipes/413486-first-class-enums-in-python/)

    - Enums are immutable; attributes cannot be added, deleted or changed.
    - Enums are iterable.
    - Enum value access is symbolic and qualified, ex. Days.Monday (like in C#).
    - Enum values are true constants.
    - Enum values are comparable.
    - Enum values are invertible (useful for 2-valued enums, like Enum('no', 'yes').
    - Enum values are usable as truth values (in a C tradition, but this is debatable).
    - Enum values are reasonably introspective (by publishing their enum type and numeric value)

    Changed slightly to add '__doc__' tags to the generated
    enumeration types.  So to the above author's comments we add:

    - Enums and Enum values are documented.
    - enumeration values are type-checked during comparisons.
    """
    assert names, "Empty enums are not supported" # <- Don't like empty enums? Uncomment!

    class EnumClass(object):
        __slots__ = names
        def __contains__(self, v): return v in constants
        def __getitem__(self, i):  return constants[i]
        def __iter__(self):        return iter(constants)
        def __len__(self):         return len(constants)
        def __repr__(self):        return 'Enum' + str(names)
        def __str__(self):         return 'enum ' + str(constants)

    class EnumValue(object):
        __slots__ = ('__value')
        def __init__(self, value): self.__value = value
        value = property(lambda self: self.__value)
        type = property(lambda self: EnumType)
        def __hash__(self):        return hash(self.__value)
        def __cmp__(self, other):
            try:
                if self.type is other.type:
                    return cmp(self.__value, other.__value)
                else:
                    raise TypeError, "requires a '%s' object but received a '%s'" % ( self.type.__class__.__name__, other.type.__class__.__name__ )
            except AttributeError:
                raise TypeError, "requires a '%s' object but received a '%s'" % ( self.type.__class__.__name__, other.__class__.__name__ )
        def __invert__(self):      return constants[maximum - self.__value]
        def __nonzero__(self):     return bool(self.__value)
        def __repr__(self):        return str(names[self.__value])
        
    maximum = len(names) - 1
    constants = [None] * len(names)
    for i, each in enumerate(names):
        val = type(EnumValue)(
            'EnumValue', (EnumValue,), { '__doc__': 'Enumeration value "%s"' % each }
        )(i)
        setattr(EnumClass, each, val)
        constants[i] = val
    constants = tuple(constants)
    EnumType = type(EnumClass)(
        'EnumClass', (EnumClass,), { '__doc__': 'Enumeration of %s' % repr(constants) }
    )()
    return EnumType

class Property(object):
    """Construct a data descriptor suitable for associating
    documentation with an attribute value.  Attribute values are
    instance specific and are stored within the instance dictionary
    (so property values go away when the instance is garbage
    collected).  Properties have a class-wide default value used if
    the property has not been specified on an instance.

    The class has the ability to indicate the access mode of the
    resulting attribute.  The possible access modes may be specified
    using exactly one of the following enumeration values:

    Mode.READ_ONLY
    ==================
    The attribute may only be read.  The instance property effectively
    becomes a class constant (as the attribute may not be written).  A
    READ_ONLY attribute must have the default value specified when the
    Property is constructed.

    Unlike an Enum class, the resulting Property is still accessable
    through the declaring class (to provide access to the attribute
    documentation).  This has the side effect that the constant value
    is only accessable through instances of the declaring class.

    Mode.READ_WRITE
    ===================
    The READ_WRITE mode is the default mode on Property instances and
    is used to provide attributes with all the normal behaviors of
    typical class attributes with supporting documentation and
    optional default values.

    Mode.WRITE_ONCE
    ===================
    The WRITE_ONCE mode builds a data descriptor that allows every
    instance of the declaring class to set the resulting attribute one
    time.  A default value may be specified that will be returned if
    the attribute is accessed prior to the write; but the default does
    not prevent the one-time write from occuring.

    Additionally you may supply a documentation string so your class
    properties may expose usage information.
    """

    ####
    #  Special value used to mark an undefined default value.
    ####

    __NONE = object()

    Mode = Enum('READ_ONLY', 'READ_WRITE', 'WRITE_ONCE')

    def __init__(self, name, default = __NONE, mode = Mode.READ_WRITE, doc = None):
        """Construct a new Property data descriptor.

        \var{name} the name of the attribute being created.
        \var{default} the (optional) default value to use when
        retrieving the attribute if it hasn't already been set.
        \var{mode} the mode of the constructed Property.
        \var{doc} the documentation string to use.  This string is
        accessed through the declaring class.
        """
        self.__name = name
        self.__key = '__property__' + name
        if mode.__class__ not in (i.__class__ for i in self.Mode):
            raise TypeError, "the mode parameter requires a member of the 'Property.Mode' enumeration but received a '%s'" % mode.__class__.__name__
        self.__mode = mode
        if default is not self.__NONE:
            self.__default = default
        elif mode is self.Mode.READ_ONLY:
            raise ValueError, 'read only attributes require a default value'
        if doc is None:
            self.__doc__ = 'the "%s" property' % name
        else:
            self.__doc__ = doc

    def __get__(self, obj, objType = None):
        """Get the attribute value.
        """
        try: return obj.__dict__[self.__key]
        except AttributeError: return self
        except KeyError: pass

        try: return objType.__dict__[self.__key]
        except KeyError: pass

        try: return self.__default
        except AttributeError:
            raise AttributeError, "'%s' object has no attribute '%s'" % ( obj.__class__.__name__, self.__name )

    def __set__(self, obj, value):
        """Set the attribute value.
        """
        if self.__mode is self.Mode.READ_ONLY:
            raise AttributeError, "can't set attribute \"%s\"" % self.__name
        elif self.__mode is self.Mode.WRITE_ONCE:
            if self.__key in obj.__dict__:
                raise AttributeError, "can't set attribute \"%s\"" % self.__name
        obj.__dict__[self.__key] = value

    def __delete__(self, obj):
        """Delete the attribute value.
        """
        if self.__mode is not self.Mode.READ_WRITE:
            raise AttributeError, "can't delete attribute \"%s\"" % self.__name
        del(obj.__dict__[self.__key])

def set_property(obj, name, value):
    """Set or reset the property 'name' to 'value' on 'obj'.

    This function may be used to modify the value of a WRITE_ONCE or
    READ_ONLY property.  Therefore use of this function should be
    limited to the implementation class.
    """
    obj.__dict__['__property__' + name] = value

if __name__ == '__main__':

    from types import FloatType, ComplexType

    def assertEquals( exp, got, msg = None ):
        """assertEquals( exp, got[, message] )

        Two objects test as "equal" if:
        
        * they are the same object as tested by the 'is' operator.
        * either object is a float or complex number and the absolute
          value of the difference between the two is less than 1e-8.
        * applying the equals operator ('==') returns True.
        """
        if exp is got:
            r = True
        elif ( type( exp ) in ( FloatType, ComplexType ) or
               type( got ) in ( FloatType, ComplexType ) ):
            r = abs( exp - got ) < 1e-8
        else:
            r = ( exp == got )
        if not r:
            print >>sys.stderr, "Error: expected <%s> but got <%s>%s" % ( repr( exp ), repr( got ), colon( msg ) )
            traceback.print_stack()

    def assertException( exceptionType, f, msg = None ):
        """Assert that an exception of type \var{exceptionType}
        is thrown when the function \var{f} is evaluated.
        """
        try:
            f()
        except exceptionType:
            assert True
        else:
            print >>sys.stderr, "Error: expected <%s> to be thrown by function%s" % ( exceptionType.__name__, colon( msg ) )
            traceback.print_stack()

    def assertNone( x, msg = None ):
        assertSame( None, x, msg )

    def assertSame( exp, got, msg = None ):
        if got is not exp:
            print >>sys.stderr, "Error: expected <%s> to be the same object as <%s>%s" % ( repr( exp ), repr( got ), colon( msg ) )
            traceback.print_stack()

    def assertTrue( b, msg = None ):
        if not b:
            print >>sys.stderr, "Error: expected value to be True%s" % colon( msg )
            traceback.print_stack()

    ####
    #  Test Property
    ####

    class Test( object ):
        ro_value = Property( 'ro_value', 'test', mode = Property.Mode.READ_ONLY )

        assertException( ValueError, lambda: Property( 'ro_undef', mode = Property.Mode.READ_ONLY ),
                         'read-only attributes should require default' )

        rw_undef = Property( 'rw_undef' )
        rw_default = Property( 'rw_default', None )
        rw_doc = Property( 'rw_default', doc = 'alternate documentation' )

        assertException( TypeError, lambda: Property( 'bad_mode', mode = None ),
                         'bad Property mode should raise an exception' )

        wo_undef = Property( 'wo_undef', mode = Property.Mode.WRITE_ONCE )
        wo_default = Property( 'wo_default', 'test', mode = Property.Mode.WRITE_ONCE )

    a = Test()
    b = Test()

    ####
    #  Mode.READ_ONLY

    assertEquals( 'test', a.ro_value )
    assertEquals( 'test', b.ro_value )
    assertException( AttributeError, lambda: setattr( a, 'ro_value', 5 ), 'unexpected write to a read-only attribute' )
    # assertException( AttributeError, lambda: del( b.ro_value ), 'unexpected del() on a read-only attribute' )

    set_property( a, 'ro_value', 'tset' )
    assertEquals( 'tset', a.ro_value )
    assertEquals( 'test', b.ro_value )

    ####
    #  Mode.READ_WRITE

    assertException( AttributeError, lambda: getattr( a, 'rw_undef' ), 'unexpected read of an undefined attribute' )
    assertNone( a.rw_default )

    a.rw_undef = 5
    assertEquals( 5, a.rw_undef )
    assertTrue( '__property__rw_undef' in a.__dict__ )
    assertEquals( 5, a.__dict__['__property__rw_undef'] )
    assertEquals( 'the "rw_undef" property', Test.rw_undef.__doc__ )
    assertSame( int, type( a.rw_undef ) )
    assertSame( Property, type( Test.rw_undef ) )

    assertEquals( 'alternate documentation', Test.rw_doc.__doc__ )

    ####
    #  Mode.READ_WRITE: changes to 'a' should not affect 'b'

    assertException( AttributeError, lambda: getattr( b, 'rw_undef' ), 'invalid state change via a different instance' )
    assertNone( b.rw_default )

    ####
    #  Mode.WRITE_ONCE

    assertException( AttributeError, lambda: getattr( a, 'wo_undef' ), 'unexpected read of an undefined attribute' )
    assertException( AttributeError, lambda: delattr( a, 'wo_undef' ), 'unexpected del() on a write-once attribute' )
    a.wo_undef = 'write_once'
    assertEquals( 'write_once', a.wo_undef )
    assertException( AttributeError, lambda: setattr( a, 'wo_undef', 'write_twice' ), 'unexpected secondary write on a write-once attribute' )
    assertEquals( 'write_once', a.wo_undef )
    assertException( AttributeError, lambda: delattr( a, 'wo_value' ), 'unexpected del() on a write-once attribute' )
    assertEquals( 'test', a.wo_default )
    a.wo_default = 'write_once'
    assertEquals( 'write_once', a.wo_default )
    assertEquals( 'test', b.wo_default )