gobject/propertyhelper.py

   1 # -*- Mode: Python; py-indent-offset: 4 -*-
   2 # pygobject - Python bindings for the GObject library
   3 # Copyright (C) 2007 Johan Dahlin
   4 #
   5 #   gobject/propertyhelper.py: GObject property wrapper/helper
   6 #
   7 # This library is free software; you can redistribute it and/or
   8 # modify it under the terms of the GNU Lesser General Public
   9 # License as published by the Free Software Foundation; either
  10 # version 2.1 of the License, or (at your option) any later version.
  11 #
  12 # This library is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 # Lesser General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU Lesser General Public
  18 # License along with this library; if not, write to the Free Software
  19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
  20 # USA
  21
  22 import sys
  23
  24 import gobject._gobject
  25 _gobject = sys.modules['gobject._gobject']
  26
  27 from gobject.constants import \
  28      TYPE_NONE, TYPE_INTERFACE, TYPE_CHAR, TYPE_UCHAR, \
  29      TYPE_BOOLEAN, TYPE_INT, TYPE_UINT, TYPE_LONG, \
  30      TYPE_ULONG, TYPE_INT64, TYPE_UINT64, TYPE_ENUM, \
  31      TYPE_FLAGS, TYPE_FLOAT, TYPE_DOUBLE, TYPE_STRING, \
  32      TYPE_POINTER, TYPE_BOXED, TYPE_PARAM, TYPE_OBJECT, \
  33      TYPE_PYOBJECT
  34 from gobject.constants import \
  35      G_MINFLOAT, G_MAXFLOAT, G_MINDOUBLE, G_MAXDOUBLE, \
  36      G_MININT, G_MAXINT, G_MAXUINT, G_MINLONG, G_MAXLONG, \
  37      G_MAXULONG
  38
  39 if sys.version_info >= (3, 0):
  40     _basestring = str
  41     _long = int
  42 else:
  43     _basestring = basestring
  44     _long = long
  45
  46 class property(object):
  47     """
  48     Creates a new property which in conjunction with GObject subclass will
  49     create a property proxy:
  50
  51     >>> class MyObject(gobject.GObject):
  52     >>> ... prop = gobject.property(type=str)
  53
  54     >>> obj = MyObject()
  55     >>> obj.prop = 'value'
  56
  57     >>> obj.prop
  58     'value'
  59
  60     The API is similar to the builtin property:
  61
  62     class AnotherObject(gobject.GObject):
  63         @gobject.property
  64         def prop(self):
  65             return ...
  66
  67     Which will create a read-only property called prop.
  68     """
  69
  70     class __metaclass__(type):
  71         def __repr__(self):
  72             return "<class 'gobject.property'>"
  73
  74     def __init__(self, getter=None, setter=None, type=None, default=None,
  75                  nick='', blurb='', flags=_gobject.PARAM_READWRITE,
  76                  minimum=None, maximum=None):
  77         """
  78         @param  getter: getter to get the value of the property
  79         @type   getter: callable
  80         @param  setter: setter to set the value of the property
  81         @type   setter: callable
  82         @param    type: type of property
  83         @type     type: type
  84         @param default: default value
  85         @param    nick: short description
  86         @type     bick: string
  87         @param   blurb: long description
  88         @type    blurb: string
  89         @param flags:    parameter flags, one of:
  90         - gobject.PARAM_READABLE
  91         - gobject.PARAM_READWRITE
  92         - gobject.PARAM_WRITABLE
  93         - gobject.PARAM_CONSTRUCT
  94         - gobject.PARAM_CONSTRUCT_ONLY
  95         - gobject.PARAM_LAX_VALIDATION
  96         @keyword minimum:  minimum allowed value (int, float, long only)
  97         @keyword maximum:  maximum allowed value (int, float, long only)
  98         """
  99
 100         if getter and not setter:
 101             setter = self._readonly_setter
 102         elif setter and not getter:
 103             getter = self._writeonly_getter
 104         elif not setter and not getter:
 105             getter = self._default_getter
 106             setter = self._default_setter
 107         self.getter = getter
 108         self.setter = setter
 109
 110         if type is None:
 111             type = object
 112         self.type = self._type_from_python(type)
 113         self.default = self._get_default(default)
 114         self._check_default()
 115
 116         if not isinstance(nick, _basestring):
 117             raise TypeError("nick must be a string")
 118         self.nick = nick
 119
 120         if not isinstance(blurb, _basestring):
 121             raise TypeError("blurb must be a string")
 122         self.blurb = blurb
 123
 124         if flags < 0 or flags > 32:
 125             raise TypeError("invalid flag value: %r" % (flags,))
 126         self.flags = flags
 127
 128         if minimum is not None:
 129             if minimum < self._get_minimum():
 130                 raise TypeError(
 131                     "Minimum for type %s cannot be lower than %d" % (
 132                     self.type, self._get_minimum()))
 133         else:
 134             minimum = self._get_minimum()
 135         self.minimum = minimum
 136         if maximum is not None:
 137             if maximum > self._get_maximum():
 138                 raise TypeError(
 139                     "Maximum for type %s cannot be higher than %d" % (
 140                     self.type, self._get_maximum()))
 141         else:
 142             maximum = self._get_maximum()
 143         self.maximum = maximum
 144
 145         self.name = None
 146
 147         self._exc = None
 148
 149     def __repr__(self):
 150         return '<gobject property %s (%s)>' % (
 151             self.name or '(uninitialized)',
 152             _gobject.type_name(self.type))
 153
 154     def __get__(self, instance, klass):
 155         if instance is None:
 156             return self
 157
 158         self._exc = None
 159         value = instance.get_property(self.name)
 160         if self._exc:
 161             exc = self._exc
 162             self._exc = None
 163             raise exc
 164
 165         return value
 166
 167     def __set__(self, instance, value):
 168         if instance is None:
 169             raise TypeError
 170
 171         self._exc = None
 172         instance.set_property(self.name, value)
 173         if self._exc:
 174             exc = self._exc
 175             self._exc = None
 176             raise exc
 177
 178     def _type_from_python(self, type_):
 179         if type_ == _long:
 180             return TYPE_LONG
 181         elif type_ == int:
 182             return TYPE_INT
 183         elif type_ == bool:
 184             return TYPE_BOOLEAN
 185         elif type_ == float:
 186             return TYPE_DOUBLE
 187         elif type_ == str:
 188             return TYPE_STRING
 189         elif type_ == object:
 190             return TYPE_PYOBJECT
 191         elif isinstance(type_, type) and issubclass(type_, _gobject.GObject):
 192             return type_.__gtype__
 193         elif type_ in [TYPE_NONE, TYPE_INTERFACE, TYPE_CHAR, TYPE_UCHAR,
 194                       TYPE_INT, TYPE_UINT, TYPE_BOOLEAN, TYPE_LONG,
 195                       TYPE_ULONG, TYPE_INT64, TYPE_UINT64, TYPE_ENUM,
 196                       TYPE_FLAGS, TYPE_FLOAT, TYPE_DOUBLE, TYPE_POINTER,
 197                       TYPE_BOXED, TYPE_PARAM, TYPE_OBJECT, TYPE_STRING,
 198                       TYPE_PYOBJECT]:
 199             return type_
 200         else:
 201             raise TypeError("Unsupported type: %r" % (type_,))
 202
 203     def _get_default(self, default):
 204         ptype = self.type
 205         if default is not None:
 206             return default
 207
 208         if ptype in [TYPE_INT, TYPE_UINT, TYPE_LONG, TYPE_ULONG,
 209                      TYPE_INT64, TYPE_UINT64]:
 210             return 0
 211         elif ptype == TYPE_STRING:
 212             return ''
 213         elif ptype == TYPE_FLOAT or ptype == TYPE_DOUBLE:
 214             return 0.0
 215         else:
 216             return None
 217
 218     def _check_default(self):
 219         ptype = self.type
 220         default = self.default
 221         if (ptype == TYPE_BOOLEAN and (default not in (True, False))):
 222             raise TypeError(
 223                 "default must be True or False, not %r" % (default,))
 224         elif ptype == TYPE_PYOBJECT:
 225             if default is not None:
 226                 raise TypeError("object types does not have default values")
 227
 228     def _get_minimum(self):
 229         ptype = self.type
 230         if ptype in [TYPE_UINT, TYPE_ULONG, TYPE_UINT64]:
 231             return 0
 232         # Remember that G_MINFLOAT and G_MINDOUBLE are something different.
 233         elif ptype == TYPE_FLOAT:
 234             return -G_MAXFLOAT
 235         elif ptype == TYPE_DOUBLE:
 236             return -G_MAXDOUBLE
 237         elif ptype == TYPE_INT:
 238             return G_MININT
 239         elif ptype == TYPE_LONG:
 240             return G_MINLONG
 241         elif ptype == TYPE_INT64:
 242             return -2 ** 62 - 1
 243
 244         return None
 245
 246     def _get_maximum(self):
 247         ptype = self.type
 248         if ptype == TYPE_UINT:
 249             return G_MAXUINT
 250         elif ptype == TYPE_ULONG:
 251             return G_MAXULONG
 252         elif ptype == TYPE_INT64:
 253             return 2 ** 62 - 1
 254         elif ptype == TYPE_UINT64:
 255             return 2 ** 63 - 1
 256         elif ptype == TYPE_FLOAT:
 257             return G_MAXFLOAT
 258         elif ptype == TYPE_DOUBLE:
 259             return G_MAXDOUBLE
 260         elif ptype == TYPE_INT:
 261             return G_MAXINT
 262         elif ptype == TYPE_LONG:
 263             return G_MAXLONG
 264
 265         return None
 266
 267     #
 268     # Getter and Setter
 269     #
 270
 271     def _default_setter(self, instance, value):
 272         setattr(instance, '_property_helper_'+self.name, value)
 273
 274     def _default_getter(self, instance):
 275         return getattr(instance, '_property_helper_'+self.name, self.default)
 276
 277     def _readonly_setter(self, instance, value):
 278         self._exc = TypeError("%s property of %s is read-only" % (
 279             self.name, type(instance).__name__))
 280
 281     def _writeonly_getter(self, instance):
 282         self._exc = TypeError("%s property of %s is write-only" % (
 283             self.name, type(instance).__name__))
 284
 285     #
 286     # Public API
 287     #
 288
 289     def get_pspec_args(self):
 290         ptype = self.type
 291         if ptype in [TYPE_INT, TYPE_UINT, TYPE_LONG, TYPE_ULONG,
 292                      TYPE_INT64, TYPE_UINT64, TYPE_FLOAT, TYPE_DOUBLE]:
 293             args = self._get_minimum(), self._get_maximum(), self.default
 294         elif ptype == TYPE_STRING or ptype == TYPE_BOOLEAN:
 295             args = (self.default,)
 296         elif ptype == TYPE_PYOBJECT:
 297             args = ()
 298         elif ptype.is_a(TYPE_OBJECT):
 299             args = ()
 300         else:
 301             raise NotImplementedError(ptype)
 302
 303         return (self.type, self.nick, self.blurb) + args + (self.flags,)