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