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, TYPE_FLAGS, \
  30     TYPE_FLOAT, TYPE_DOUBLE, TYPE_STRING, \
  31     TYPE_POINTER, TYPE_BOXED, TYPE_PARAM, TYPE_OBJECT, \
  32     TYPE_PYOBJECT, TYPE_GTYPE, TYPE_STRV
  33 from .constants import \
  34     G_MAXFLOAT, 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
  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             '''Read only property.'''
  66             return ...
  67
  68         @GObject.Property(type=int)
  69         def propInt(self):
  70             '''Read-write integer property.'''
  71             return ...
  72
  73         @propInt.setter
  74         def propInt(self, value):
  75             ...
  76     """
  77     _type_from_pytype_lookup = {
  78         # Put long_ first in case long_ and int are the same so int clobbers long_
  79         _long: TYPE_LONG,
  80         int: TYPE_INT,
  81         bool: TYPE_BOOLEAN,
  82         float: TYPE_DOUBLE,
  83         str: TYPE_STRING,
  84         object: TYPE_PYOBJECT,
  85     }
  86
  87     _min_value_lookup = {
  88         TYPE_UINT: 0,
  89         TYPE_ULONG: 0,
  90         TYPE_UINT64: 0,
  91         # Remember that G_MINFLOAT and G_MINDOUBLE are something different.
  92         TYPE_FLOAT: -G_MAXFLOAT,
  93         TYPE_DOUBLE: -G_MAXDOUBLE,
  94         TYPE_INT: G_MININT,
  95         TYPE_LONG: G_MINLONG,
  96         TYPE_INT64: -2 ** 62 - 1,
  97     }
  98
  99     _max_value_lookup = {
 100         TYPE_UINT: G_MAXUINT,
 101         TYPE_ULONG: G_MAXULONG,
 102         TYPE_INT64: 2 ** 62 - 1,
 103         TYPE_UINT64: 2 ** 63 - 1,
 104         TYPE_FLOAT: G_MAXFLOAT,
 105         TYPE_DOUBLE: G_MAXDOUBLE,
 106         TYPE_INT: G_MAXINT,
 107         TYPE_LONG: G_MAXLONG,
 108     }
 109
 110     _default_lookup = {
 111         TYPE_INT: 0,
 112         TYPE_UINT: 0,
 113         TYPE_LONG: 0,
 114         TYPE_ULONG: 0,
 115         TYPE_INT64: 0,
 116         TYPE_UINT64: 0,
 117         TYPE_STRING: '',
 118         TYPE_FLOAT: 0.0,
 119         TYPE_DOUBLE: 0.0,
 120     }
 121
 122     class __metaclass__(type):
 123         def __repr__(self):
 124             return "<class 'GObject.Property'>"
 125
 126     def __init__(self, getter=None, setter=None, type=None, default=None,
 127                  nick='', blurb='', flags=_gobject.PARAM_READWRITE,
 128                  minimum=None, maximum=None):
 129         """
 130         @param  getter: getter to get the value of the property
 131         @type   getter: callable
 132         @param  setter: setter to set the value of the property
 133         @type   setter: callable
 134         @param    type: type of property
 135         @type     type: type
 136         @param default: default value
 137         @param    nick: short description
 138         @type     nick: string
 139         @param   blurb: long description
 140         @type    blurb: string
 141         @param flags:    parameter flags, one of:
 142         - gobject.PARAM_READABLE
 143         - gobject.PARAM_READWRITE
 144         - gobject.PARAM_WRITABLE
 145         - gobject.PARAM_CONSTRUCT
 146         - gobject.PARAM_CONSTRUCT_ONLY
 147         - gobject.PARAM_LAX_VALIDATION
 148         @keyword minimum:  minimum allowed value (int, float, long only)
 149         @keyword maximum:  maximum allowed value (int, float, long only)
 150         """
 151
 152         if type is None:
 153             type = object
 154         self.type = self._type_from_python(type)
 155         self.default = self._get_default(default)
 156         self._check_default()
 157
 158         if not isinstance(nick, _basestring):
 159             raise TypeError("nick must be a string")
 160         self.nick = nick
 161
 162         if not isinstance(blurb, _basestring):
 163             raise TypeError("blurb must be a string")
 164         self.blurb = blurb
 165
 166         if flags < 0 or flags > 32:
 167             raise TypeError("invalid flag value: %r" % (flags,))
 168         self.flags = flags
 169
 170         # Call after setting blurb for potential __doc__ usage.
 171         if getter and not setter:
 172             setter = self._readonly_setter
 173         elif setter and not getter:
 174             getter = self._writeonly_getter
 175         elif not setter and not getter:
 176             getter = self._default_getter
 177             setter = self._default_setter
 178         self.getter(getter)
 179         self.setter(setter)
 180
 181         if minimum is not None:
 182             if minimum < self._get_minimum():
 183                 raise TypeError(
 184                     "Minimum for type %s cannot be lower than %d" % (
 185                     self.type, self._get_minimum()))
 186         else:
 187             minimum = self._get_minimum()
 188         self.minimum = minimum
 189         if maximum is not None:
 190             if maximum > self._get_maximum():
 191                 raise TypeError(
 192                     "Maximum for type %s cannot be higher than %d" % (
 193                     self.type, self._get_maximum()))
 194         else:
 195             maximum = self._get_maximum()
 196         self.maximum = maximum
 197
 198         self.name = None
 199
 200         self._exc = None
 201
 202     def __repr__(self):
 203         return '<GObject Property %s (%s)>' % (
 204             self.name or '(uninitialized)',
 205             _gobject.type_name(self.type))
 206
 207     def __get__(self, instance, klass):
 208         if instance is None:
 209             return self
 210
 211         self._exc = None
 212         value = instance.get_property(self.name)
 213         if self._exc:
 214             exc = self._exc
 215             self._exc = None
 216             raise exc
 217
 218         return value
 219
 220     def __set__(self, instance, value):
 221         if instance is None:
 222             raise TypeError
 223
 224         self._exc = None
 225         instance.set_property(self.name, value)
 226         if self._exc:
 227             exc = self._exc
 228             self._exc = None
 229             raise exc
 230
 231     def __call__(self, fget):
 232         """Allows application of the getter along with init arguments."""
 233         return self.getter(fget)
 234
 235     def getter(self, fget):
 236         """Set the getter function to fget. For use as a decorator."""
 237         if self.__doc__ is None:
 238             self.__doc__ = fget.__doc__
 239         if not self.blurb and fget.__doc__:
 240             self.blurb = fget.__doc__
 241         self.fget = fget
 242         return self
 243
 244     def setter(self, fset):
 245         """Set the setter function to fset. For use as a decorator."""
 246         self.fset = fset
 247         return self
 248
 249     def _type_from_python(self, type_):
 250         if type_ in self._type_from_pytype_lookup:
 251             return self._type_from_pytype_lookup[type_]
 252         elif (isinstance(type_, type) and
 253               issubclass(type_, (_gobject.GObject,
 254                                  _gobject.GEnum,
 255                                  _gobject.GFlags,
 256                                  _gobject.GBoxed))):
 257             return type_.__gtype__
 258         elif type_ in (TYPE_NONE, TYPE_INTERFACE, TYPE_CHAR, TYPE_UCHAR,
 259                        TYPE_INT, TYPE_UINT, TYPE_BOOLEAN, TYPE_LONG,
 260                        TYPE_ULONG, TYPE_INT64, TYPE_UINT64,
 261                        TYPE_FLOAT, TYPE_DOUBLE, TYPE_POINTER,
 262                        TYPE_BOXED, TYPE_PARAM, TYPE_OBJECT, TYPE_STRING,
 263                        TYPE_PYOBJECT, TYPE_GTYPE, TYPE_STRV):
 264             return type_
 265         else:
 266             raise TypeError("Unsupported type: %r" % (type_,))
 267
 268     def _get_default(self, default):
 269         if default is not None:
 270             return default
 271         return self._default_lookup.get(self.type, None)
 272
 273     def _check_default(self):
 274         ptype = self.type
 275         default = self.default
 276         if (ptype == TYPE_BOOLEAN and (default not in (True, False))):
 277             raise TypeError(
 278                 "default must be True or False, not %r" % (default,))
 279         elif ptype == TYPE_PYOBJECT:
 280             if default is not None:
 281                 raise TypeError("object types does not have default values")
 282         elif ptype == TYPE_GTYPE:
 283             if default is not None:
 284                 raise TypeError("GType types does not have default values")
 285         elif _gobject.type_is_a(ptype, TYPE_ENUM):
 286             if default is None:
 287                 raise TypeError("enum properties needs a default value")
 288             elif not _gobject.type_is_a(default, ptype):
 289                 raise TypeError("enum value %s must be an instance of %r" %
 290                                 (default, ptype))
 291         elif _gobject.type_is_a(ptype, TYPE_FLAGS):
 292             if not _gobject.type_is_a(default, ptype):
 293                 raise TypeError("flags value %s must be an instance of %r" %
 294                                 (default, ptype))
 295         elif _gobject.type_is_a(ptype, TYPE_STRV) and default is not None:
 296             if not isinstance(default, list):
 297                 raise TypeError("Strv value %s must be a list" % repr(default))
 298             for val in default:
 299                 if type(val) not in (str, bytes):
 300                     raise TypeError("Strv value %s must contain only strings" % str(default))
 301
 302     def _get_minimum(self):
 303         return self._min_value_lookup.get(self.type, None)
 304
 305     def _get_maximum(self):
 306         return self._max_value_lookup.get(self.type, None)
 307
 308     #
 309     # Getter and Setter
 310     #
 311
 312     def _default_setter(self, instance, value):
 313         setattr(instance, '_property_helper_' + self.name, value)
 314
 315     def _default_getter(self, instance):
 316         return getattr(instance, '_property_helper_' + self.name, self.default)
 317
 318     def _readonly_setter(self, instance, value):
 319         self._exc = TypeError("%s property of %s is read-only" % (
 320             self.name, type(instance).__name__))
 321
 322     def _writeonly_getter(self, instance):
 323         self._exc = TypeError("%s property of %s is write-only" % (
 324             self.name, type(instance).__name__))
 325
 326     #
 327     # Public API
 328     #
 329
 330     def get_pspec_args(self):
 331         ptype = self.type
 332         if ptype in (TYPE_INT, TYPE_UINT, TYPE_LONG, TYPE_ULONG,
 333                      TYPE_INT64, TYPE_UINT64, TYPE_FLOAT, TYPE_DOUBLE):
 334             args = self.minimum, self.maximum, self.default
 335         elif (ptype == TYPE_STRING or ptype == TYPE_BOOLEAN or
 336               ptype.is_a(TYPE_ENUM) or ptype.is_a(TYPE_FLAGS)):
 337             args = (self.default,)
 338         elif ptype in (TYPE_PYOBJECT, TYPE_GTYPE):
 339             args = ()
 340         elif ptype.is_a(TYPE_OBJECT) or ptype.is_a(TYPE_BOXED):
 341             args = ()
 342         else:
 343             raise NotImplementedError(ptype)
 344
 345         return (self.type, self.nick, self.blurb) + args + (self.flags,)