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, TYPE_VARIANT
  33 from ._gobject 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  # now is '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             '''Read only property.'''
  65             return ...
  66
  67         @GObject.Property(type=int)
  68         def propInt(self):
  69             '''Read-write integer property.'''
  70             return ...
  71
  72         @propInt.setter
  73         def propInt(self, value):
  74             ...
  75     """
  76     _type_from_pytype_lookup = {
  77         # Put long_ first in case long_ and int are the same so int clobbers long_
  78         _long: TYPE_LONG,
  79         int: TYPE_INT,
  80         bool: TYPE_BOOLEAN,
  81         float: TYPE_DOUBLE,
  82         str: TYPE_STRING,
  83         object: TYPE_PYOBJECT,
  84     }
  85
  86     _min_value_lookup = {
  87         TYPE_UINT: 0,
  88         TYPE_ULONG: 0,
  89         TYPE_UINT64: 0,
  90         # Remember that G_MINFLOAT and G_MINDOUBLE are something different.
  91         TYPE_FLOAT: -G_MAXFLOAT,
  92         TYPE_DOUBLE: -G_MAXDOUBLE,
  93         TYPE_INT: G_MININT,
  94         TYPE_LONG: G_MINLONG,
  95         TYPE_INT64: -2 ** 63,
  96     }
  97
  98     _max_value_lookup = {
  99         TYPE_UINT: G_MAXUINT,
 100         TYPE_ULONG: G_MAXULONG,
 101         TYPE_INT64: 2 ** 63 - 1,
 102         TYPE_UINT64: 2 ** 64 - 1,
 103         TYPE_FLOAT: G_MAXFLOAT,
 104         TYPE_DOUBLE: G_MAXDOUBLE,
 105         TYPE_INT: G_MAXINT,
 106         TYPE_LONG: G_MAXLONG,
 107     }
 108
 109     _default_lookup = {
 110         TYPE_INT: 0,
 111         TYPE_UINT: 0,
 112         TYPE_LONG: 0,
 113         TYPE_ULONG: 0,
 114         TYPE_INT64: 0,
 115         TYPE_UINT64: 0,
 116         TYPE_STRING: '',
 117         TYPE_FLOAT: 0.0,
 118         TYPE_DOUBLE: 0.0,
 119     }
 120
 121     class __metaclass__(type):
 122         def __repr__(self):
 123             return "<class 'GObject.Property'>"
 124
 125     def __init__(self, getter=None, setter=None, type=None, default=None,
 126                  nick='', blurb='', flags=_gobject.PARAM_READWRITE,
 127                  minimum=None, maximum=None):
 128         """
 129         @param  getter: getter to get the value of the property
 130         @type   getter: callable
 131         @param  setter: setter to set the value of the property
 132         @type   setter: callable
 133         @param    type: type of property
 134         @type     type: type
 135         @param default: default value
 136         @param    nick: short description
 137         @type     nick: string
 138         @param   blurb: long description
 139         @type    blurb: string
 140         @param flags:    parameter flags, one of:
 141         - gobject.PARAM_READABLE
 142         - gobject.PARAM_READWRITE
 143         - gobject.PARAM_WRITABLE
 144         - gobject.PARAM_CONSTRUCT
 145         - gobject.PARAM_CONSTRUCT_ONLY
 146         - gobject.PARAM_LAX_VALIDATION
 147         @keyword minimum:  minimum allowed value (int, float, long only)
 148         @keyword maximum:  maximum allowed value (int, float, long only)
 149         """
 150
 151         self.name = None
 152
 153         if type is None:
 154             type = object
 155         self.type = self._type_from_python(type)
 156         self.default = self._get_default(default)
 157         self._check_default()
 158
 159         if not isinstance(nick, _basestring):
 160             raise TypeError("nick must be a string")
 161         self.nick = nick
 162
 163         if not isinstance(blurb, _basestring):
 164             raise TypeError("blurb must be a string")
 165         self.blurb = blurb
 166         # Always clobber __doc__ with blurb even if blurb is empty because
 167         # we don't want the lengthy Property class documentation showing up
 168         # on instances.
 169         self.__doc__ = blurb
 170         self.flags = flags
 171
 172         # Call after setting blurb for potential __doc__ usage.
 173         if getter and not setter:
 174             setter = self._readonly_setter
 175         elif setter and not getter:
 176             getter = self._writeonly_getter
 177         elif not setter and not getter:
 178             getter = self._default_getter
 179             setter = self._default_setter
 180         self.getter(getter)
 181         # do not call self.setter() here, as this defines the property name
 182         # already
 183         self.fset = setter
 184
 185         if minimum is not None:
 186             if minimum < self._get_minimum():
 187                 raise TypeError(
 188                     "Minimum for type %s cannot be lower than %d" % (
 189                     self.type, self._get_minimum()))
 190         else:
 191             minimum = self._get_minimum()
 192         self.minimum = minimum
 193         if maximum is not None:
 194             if maximum > self._get_maximum():
 195                 raise TypeError(
 196                     "Maximum for type %s cannot be higher than %d" % (
 197                     self.type, self._get_maximum()))
 198         else:
 199             maximum = self._get_maximum()
 200         self.maximum = maximum
 201
 202         self._exc = None
 203
 204     def __repr__(self):
 205         return '<GObject Property %s (%s)>' % (
 206             self.name or '(uninitialized)',
 207             _gobject.type_name(self.type))
 208
 209     def __get__(self, instance, klass):
 210         if instance is None:
 211             return self
 212
 213         self._exc = None
 214         value = instance.get_property(self.name)
 215         if self._exc:
 216             exc = self._exc
 217             self._exc = None
 218             raise exc
 219
 220         return value
 221
 222     def __set__(self, instance, value):
 223         if instance is None:
 224             raise TypeError
 225
 226         self._exc = None
 227         instance.set_property(self.name, value)
 228         if self._exc:
 229             exc = self._exc
 230             self._exc = None
 231             raise exc
 232
 233     def __call__(self, fget):
 234         """Allows application of the getter along with init arguments."""
 235         return self.getter(fget)
 236
 237     def getter(self, fget):
 238         """Set the getter function to fget. For use as a decorator."""
 239         if fget.__doc__:
 240             # Always clobber docstring and blurb with the getter docstring.
 241             self.blurb = fget.__doc__
 242             self.__doc__ = fget.__doc__
 243         self.fget = fget
 244         return self
 245
 246     def setter(self, fset):
 247         """Set the setter function to fset. For use as a decorator."""
 248         self.fset = fset
 249         # with a setter decorator, we must ignore the name of the method in
 250         # install_properties, as this does not need to be a valid property name
 251         # and does not define the property name. So set the name here.
 252         if not self.name:
 253             self.name = self.fget.__name__
 254         return self
 255
 256     def _type_from_python(self, type_):
 257         if type_ in self._type_from_pytype_lookup:
 258             return self._type_from_pytype_lookup[type_]
 259         elif (isinstance(type_, type) and
 260               issubclass(type_, (_gobject.GObject,
 261                                  _gobject.GEnum,
 262                                  _gobject.GFlags,
 263                                  _gobject.GBoxed,
 264                                  _gobject.GInterface))):
 265             return type_.__gtype__
 266         elif type_ in (TYPE_NONE, TYPE_INTERFACE, TYPE_CHAR, TYPE_UCHAR,
 267                        TYPE_INT, TYPE_UINT, TYPE_BOOLEAN, TYPE_LONG,
 268                        TYPE_ULONG, TYPE_INT64, TYPE_UINT64,
 269                        TYPE_FLOAT, TYPE_DOUBLE, TYPE_POINTER,
 270                        TYPE_BOXED, TYPE_PARAM, TYPE_OBJECT, TYPE_STRING,
 271                        TYPE_PYOBJECT, TYPE_GTYPE, TYPE_STRV, TYPE_VARIANT):
 272             return type_
 273         else:
 274             raise TypeError("Unsupported type: %r" % (type_,))
 275
 276     def _get_default(self, default):
 277         if default is not None:
 278             return default
 279         return self._default_lookup.get(self.type, None)
 280
 281     def _check_default(self):
 282         ptype = self.type
 283         default = self.default
 284         if (ptype == TYPE_BOOLEAN and (default not in (True, False))):
 285             raise TypeError(
 286                 "default must be True or False, not %r" % (default,))
 287         elif ptype == TYPE_PYOBJECT:
 288             if default is not None:
 289                 raise TypeError("object types does not have default values")
 290         elif ptype == TYPE_GTYPE:
 291             if default is not None:
 292                 raise TypeError("GType types does not have default values")
 293         elif _gobject.type_is_a(ptype, TYPE_ENUM):
 294             if default is None:
 295                 raise TypeError("enum properties needs a default value")
 296             elif not _gobject.type_is_a(default, ptype):
 297                 raise TypeError("enum value %s must be an instance of %r" %
 298                                 (default, ptype))
 299         elif _gobject.type_is_a(ptype, TYPE_FLAGS):
 300             if not _gobject.type_is_a(default, ptype):
 301                 raise TypeError("flags value %s must be an instance of %r" %
 302                                 (default, ptype))
 303         elif _gobject.type_is_a(ptype, TYPE_STRV) and default is not None:
 304             if not isinstance(default, list):
 305                 raise TypeError("Strv value %s must be a list" % repr(default))
 306             for val in default:
 307                 if type(val) not in (str, bytes):
 308                     raise TypeError("Strv value %s must contain only strings" % str(default))
 309         elif _gobject.type_is_a(ptype, TYPE_VARIANT) and default is not None:
 310             if not hasattr(default, '__gtype__') or not _gobject.type_is_a(default, TYPE_VARIANT):
 311                 raise TypeError("variant value %s must be an instance of %r" %
 312                                 (default, ptype))
 313
 314     def _get_minimum(self):
 315         return self._min_value_lookup.get(self.type, None)
 316
 317     def _get_maximum(self):
 318         return self._max_value_lookup.get(self.type, None)
 319
 320     #
 321     # Getter and Setter
 322     #
 323
 324     def _default_setter(self, instance, value):
 325         setattr(instance, '_property_helper_' + self.name, value)
 326
 327     def _default_getter(self, instance):
 328         return getattr(instance, '_property_helper_' + self.name, self.default)
 329
 330     def _readonly_setter(self, instance, value):
 331         self._exc = TypeError("%s property of %s is read-only" % (
 332             self.name, type(instance).__name__))
 333
 334     def _writeonly_getter(self, instance):
 335         self._exc = TypeError("%s property of %s is write-only" % (
 336             self.name, type(instance).__name__))
 337
 338     #
 339     # Public API
 340     #
 341
 342     def get_pspec_args(self):
 343         ptype = self.type
 344         if ptype in (TYPE_INT, TYPE_UINT, TYPE_LONG, TYPE_ULONG,
 345                      TYPE_INT64, TYPE_UINT64, TYPE_FLOAT, TYPE_DOUBLE):
 346             args = self.minimum, self.maximum, self.default
 347         elif (ptype == TYPE_STRING or ptype == TYPE_BOOLEAN or
 348               ptype.is_a(TYPE_ENUM) or ptype.is_a(TYPE_FLAGS) or
 349               ptype.is_a(TYPE_VARIANT)):
 350             args = (self.default,)
 351         elif ptype in (TYPE_PYOBJECT, TYPE_GTYPE):
 352             args = ()
 353         elif ptype.is_a(TYPE_OBJECT) or ptype.is_a(TYPE_BOXED):
 354             args = ()
 355         else:
 356             raise NotImplementedError(ptype)
 357
 358         return (self.type, self.nick, self.blurb) + args + (self.flags,)
 359
 360
 361 def install_properties(cls):
 362     """
 363     Scans the given class for instances of Property and merges them
 364     into the classes __gproperties__ dict if it exists or adds it if not.
 365     """
 366     gproperties = cls.__dict__.get('__gproperties__', {})
 367
 368     props = []
 369     for name, prop in cls.__dict__.items():
 370         if isinstance(prop, Property):  # not same as the built-in
 371             # if a property was defined with a decorator, it may already have
 372             # a name; if it was defined with an assignment (prop = Property(...))
 373             # we set the property's name to the member name
 374             if not prop.name:
 375                 prop.name = name
 376             # we will encounter the same property multiple times in case of
 377             # custom setter methods
 378             if prop.name in gproperties:
 379                 if gproperties[prop.name] == prop.get_pspec_args():
 380                     continue
 381                 raise ValueError('Property %s was already found in __gproperties__' % prop.name)
 382             gproperties[prop.name] = prop.get_pspec_args()
 383             props.append(prop)
 384
 385     if not props:
 386         return
 387
 388     cls.__gproperties__ = gproperties
 389
 390     if 'do_get_property' in cls.__dict__ or 'do_set_property' in cls.__dict__:
 391         for prop in props:
 392             if prop.fget != prop._default_getter or prop.fset != prop._default_setter:
 393                 raise TypeError(
 394                     "GObject subclass %r defines do_get/set_property"
 395                     " and it also uses a property with a custom setter"
 396                     " or getter. This is not allowed" % (
 397                     cls.__name__,))
 398
 399     def obj_get_property(self, pspec):
 400         name = pspec.name.replace('-', '_')
 401         prop = getattr(cls, name, None)
 402         if prop:
 403             return prop.fget(self)
 404     cls.do_get_property = obj_get_property
 405
 406     def obj_set_property(self, pspec, value):
 407         name = pspec.name.replace('-', '_')
 408         prop = getattr(cls, name, None)
 409         if prop:
 410             prop.fset(self, value)
 411     cls.do_set_property = obj_set_property