#!/usr/bin/env python
#
# Copyright 2010- Hui Zhang
# E-mail: hui.zh012@gmail.com
#
# Distributed under the terms of the GPL (GNU Public License)
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
__all__ = ["Attribute", "attribute", ]
from weakref import ref
from functools import partial
class BaseAttribute(object):
"""
usage:
>>>class A(object):
val = Attriubte('val',
factory=int,
validator=lambda v: v in range(3,7),
onchanged=somfunc,
readonly=True,
otw=False,
... # for more please check the code
)
>>> a = A()
>>> print a.val
0
>>> a.val=1; print a.val
1
>>> del a.val; print a.val
0
notes:
'del a.val' does not delete the attr from instance.
it just clean the assigned value for this attr.
parameters:
* name :
the attr's name, default is ''
* readonly :
define if the attr could be assigned.
notes: readonly does not impact behavior of 'del a.val'
* delable :
define if the value could be deleted
* default :
the default value.
* factory, boundfactory
define the initializer for the attr.
-factory takes no parametor
-boundfactory would get the instance as the only parameter.
* validator, boundvalidator, skip_valid_err
validate the value assigned to the attr.
if validate failed,
- the value would not be assigned
- a exception would be raised if skip_valid_err is False.
The validation would not be applied for the value initialized by:
default, factory, boundfactory
* onchanged
define a hook while attr value changed.
the following 4 args would be given to the hook:
(instance, Attribute instance, old value, new value)
* otw
one time write.
e.g:
class A(object):
v = Attribute(otw=True)
class B(A):
def __init__(self, value):
self.v = value
b = B(99)
print b.v -> 99
b.v = 100 -> exception raised
[initialization:]
initializers are prioritized as "default, factory, boundfactory"
if no any defined and value assinged, a exception would be raised while you try to read this attr.
"""
undefined = object()
def __init__(self, name='', **kwargs):
self.name = name
self.dict = kwargs.copy()
self.skip_valid_err = self.getarg('skip_valid_err', True)
self.build_initer()
self.build_assigner()
self.build_deleter()
onchanged = self.getarg('onchanged', None)
if onchanged:
self.onchanged(onchanged)
## read, write and erase the value from/to the storage
## to be implemented by sub classes
def _read_(self, instance):
""" read the value from the storage
raise exception if the value is not initialized
"""
def _write_(self, instance, value):
""" store the value to the storage
"""
def _earase_(self, instance):
""" erase the value from the storage
"""
def __get__(self, instance, owner):
if instance is None:
return self
else:
try:
return self._read_(instance)
except:
if self.initer:
self._write_(instance, self.initer(instance))
return self._read_(instance)
raise AttributeError("Attribute is used before initialized.")
def __set__(self, instance, value):
self.assigner(instance, value)
def __delete__(self, instance):
self.deleter(instance)
## build the initer, assigner and deleter
def getarg(self, name, default):
if name in self.dict:
return self.dict.pop(name)
else:
return default
def build_initer(self):
self.initer = None
_dummy = object
default = self.getarg('default', _dummy)
if default is not _dummy:
self.initer = lambda instance: default
return
factory = self.getarg('factory', _dummy)
if factory is not _dummy:
self.initer = lambda instance: factory()
return
boundfactory = self.getarg('boundfactory', _dummy)
if boundfactory is not _dummy:
self.initer = lambda instance: boundfactory(instance)
return
def build_assigner(self):
readonly = self.getarg('readonly', False)
if readonly:
def assigner(instance, value):
raise AttributeError("Cannot set value to read-only attribute")
self.assigner = assigner
return
self.assigner = self._write_
otw = self.getarg('otw', False)
if otw:
self.set_otw()
validator = self.getarg('validator', None)
if validator:
self.validator(validator)
boundvalidator = self.getarg('boundvalidator', None)
if boundvalidator:
self.boundvalidator(boundvalidator)
def build_deleter(self):
delable = self.getarg('delable', True)
if not delable:
def deleter(instance):
raise AttributeError("Cannot delete attribute")
self.deleter = deleter
else:
self.deleter = self._earase_
## handler wrappers
def set_otw(self):
oldassinger = self.assigner
def assigner(instance, value):
try:
self._read_(instance)
inited = True
except:
inited = False
if inited:
raise AttributeError('Attribute could only be written once.')
oldassinger(instance, value)
self.assigner = assigner
# be able to use as decorator
def onchanged(self, hook):
def wrap(func):
def newfunc(*args):
instance = args[0]
try:
oldval = self.__get__(instance, None)
except:
oldval = BaseAttribute.undefined
func(*args)
try:
newval = self.__get__(instance, None)
except:
newval = BaseAttribute.undefined
if oldval != newval:
hook(instance, self, oldval, newval)
return newfunc
self.assigner = wrap(self.assigner)
self.deleter = wrap(self.deleter)
return self
def validator(self, hook):
oldassinger = self.assigner
def assigner(instance, value):
if hook(value):
oldassinger(instance, value)
elif not self.skip_valid_err:
raise AttributeError("The value for attribute is not valid")
self.assigner = assigner
return self
def boundvalidator(self, hook):
oldassinger = self.assigner
def assigner(instance, value):
if hook(instance, value):
oldassinger(instance, value)
elif not self.skip_valid_err:
raise AttributeError("The value for attribute is not valid")
self.assigner = assigner
return self
class Attribute(BaseAttribute):
def __init__(self, name='', **kwargs):
super(Attribute, self).__init__(name, **kwargs)
self.__values = weakkeymap() # Recipe 577580: weak reference map
def _read_(self, instance):
return self.__values.get(instance)
def _write_(self, instance, value):
self.__values.set(instance, value)
def _earase_(self, instance):
self.__values.remove(instance)
def attribute(*args, **kwargs):
assert 'boundfactory' not in kwargs \
and ( not args
or (len(args)==1 and not kwargs)
)
if args:
return Attribute(args[0].func_name,
boundfactory=args[0])
else:
def deco(func):
return Attribute(func.func_name,
boundfactory=func,
**kwargs)
return deco
## demo code
#class A(object):
# @attribute(skip_valid_err=False)
# def value(self):
# return 10000
#
# @value.boundvalidator
# def value(self, v):
# return v < 20
#
# value.validator(lambda v: v>5)
#
# @value.onchanged
# def value(self, *args):
# print args
#
#a = A()
#print a.value
#a.value = 9
#print a.value
#a.value = 100
