1 # -*- Mode: Python; py-indent-offset: 4 -*-
2 # pygobject - Python bindings for the GObject library
3 # Copyright (C) 2007 Johan Dahlin
5 # gobject/propertyhelper.py: GObject property wrapper/helper
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.
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.
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
24 from . import _gobject
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, \
38 if sys.version_info >= (3, 0):
42 _basestring = basestring
46 class Property(object):
48 Creates a new property which in conjunction with GObject subclass will
49 create a property proxy:
51 class MyObject(GObject.GObject):
52 ... prop = GObject.Property(type=str)
57 obj.prop # now is 'value'
59 The API is similar to the builtin property:
61 class AnotherObject(GObject.GObject):
64 '''Read only property.'''
67 @GObject.Property(type=int)
69 '''Read-write integer property.'''
73 def propInt(self, value):
76 _type_from_pytype_lookup = {
77 # Put long_ first in case long_ and int are the same so int clobbers long_
83 object: TYPE_PYOBJECT,
90 # Remember that G_MINFLOAT and G_MINDOUBLE are something different.
91 TYPE_FLOAT: -G_MAXFLOAT,
92 TYPE_DOUBLE: -G_MAXDOUBLE,
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,
106 TYPE_LONG: G_MAXLONG,
121 class __metaclass__(type):
123 return "<class 'GObject.Property'>"
125 def __init__(self, getter=None, setter=None, type=None, default=None,
126 nick='', blurb='', flags=_gobject.PARAM_READWRITE,
127 minimum=None, maximum=None):
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
135 @param default: default value
136 @param nick: short description
138 @param blurb: long description
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)
155 self.type = self._type_from_python(type)
156 self.default = self._get_default(default)
157 self._check_default()
159 if not isinstance(nick, _basestring):
160 raise TypeError("nick must be a string")
163 if not isinstance(blurb, _basestring):
164 raise TypeError("blurb must be a string")
166 # Always clobber __doc__ with blurb even if blurb is empty because
167 # we don't want the lengthy Property class documentation showing up
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
181 # do not call self.setter() here, as this defines the property name
185 if minimum is not None:
186 if minimum < self._get_minimum():
188 "Minimum for type %s cannot be lower than %d" %
189 (self.type, self._get_minimum()))
191 minimum = self._get_minimum()
192 self.minimum = minimum
193 if maximum is not None:
194 if maximum > self._get_maximum():
196 "Maximum for type %s cannot be higher than %d" %
197 (self.type, self._get_maximum()))
199 maximum = self._get_maximum()
200 self.maximum = maximum
205 return '<GObject Property %s (%s)>' % (
206 self.name or '(uninitialized)',
207 _gobject.type_name(self.type))
209 def __get__(self, instance, klass):
214 value = instance.get_property(self.name)
222 def __set__(self, instance, value):
227 instance.set_property(self.name, value)
233 def __call__(self, fget):
234 """Allows application of the getter along with init arguments."""
235 return self.getter(fget)
237 def getter(self, fget):
238 """Set the getter function to fget. For use as a decorator."""
240 # Always clobber docstring and blurb with the getter docstring.
241 self.blurb = fget.__doc__
242 self.__doc__ = fget.__doc__
246 def setter(self, fset):
247 """Set the setter function to fset. For use as a decorator."""
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.
253 self.name = self.fget.__name__
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,
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):
274 raise TypeError("Unsupported type: %r" % (type_,))
276 def _get_default(self, default):
277 if default is not None:
279 return self._default_lookup.get(self.type, None)
281 def _check_default(self):
283 default = self.default
284 if (ptype == TYPE_BOOLEAN and (default not in (True, False))):
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):
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" %
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" %
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))
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" %
314 def _get_minimum(self):
315 return self._min_value_lookup.get(self.type, None)
317 def _get_maximum(self):
318 return self._max_value_lookup.get(self.type, None)
324 def _default_setter(self, instance, value):
325 setattr(instance, '_property_helper_' + self.name, value)
327 def _default_getter(self, instance):
328 return getattr(instance, '_property_helper_' + self.name, self.default)
330 def _readonly_setter(self, instance, value):
331 self._exc = TypeError("%s property of %s is read-only" % (
332 self.name, type(instance).__name__))
334 def _writeonly_getter(self, instance):
335 self._exc = TypeError("%s property of %s is write-only" % (
336 self.name, type(instance).__name__))
342 def get_pspec_args(self):
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):
353 elif ptype.is_a(TYPE_OBJECT) or ptype.is_a(TYPE_BOXED):
356 raise NotImplementedError(ptype)
358 return (self.type, self.nick, self.blurb) + args + (self.flags,)
361 def install_properties(cls):
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.
366 gproperties = cls.__dict__.get('__gproperties__', {})
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
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():
381 raise ValueError('Property %s was already found in __gproperties__' % prop.name)
382 gproperties[prop.name] = prop.get_pspec_args()
388 cls.__gproperties__ = gproperties
390 if 'do_get_property' in cls.__dict__ or 'do_set_property' in cls.__dict__:
392 if prop.fget != prop._default_getter or prop.fset != prop._default_setter:
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" %
399 def obj_get_property(self, pspec):
400 name = pspec.name.replace('-', '_')
401 prop = getattr(cls, name, None)
403 return prop.fget(self)
404 cls.do_get_property = obj_get_property
406 def obj_set_property(self, pspec, value):
407 name = pspec.name.replace('-', '_')
408 prop = getattr(cls, name, None)
410 prop.fset(self, value)
411 cls.do_set_property = obj_set_property