gi/overrides/GObject.py

   1 # -*- Mode: Python; py-indent-offset: 4 -*-
   2 # vim: tabstop=4 shiftwidth=4 expandtab
   3 #
   4 # Copyright (C) 2012 Canonical Ltd.
   5 # Author: Martin Pitt <martin.pitt@ubuntu.com>
   6 # Copyright (C) 2012-2013 Simon Feltman <sfeltman@src.gnome.org>
   7 # Copyright (C) 2012 Bastian Winkler <buz@netbuz.org>
   8 #
   9 # This library is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU Lesser General Public
  11 # License as published by the Free Software Foundation; either
  12 # version 2.1 of the License, or (at your option) any later version.
  13 #
  14 # This library is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # Lesser General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU Lesser General Public
  20 # License along with this library; if not, write to the Free Software
  21 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  22 # USA
  23
  24 import sys
  25 import warnings
  26 from collections import namedtuple
  27
  28 import gi.overrides
  29 import gi.module
  30 from gi.overrides import override, deprecated_attr
  31 from gi.repository import GLib
  32 from gi import PyGIDeprecationWarning
  33
  34 from gi import _propertyhelper as propertyhelper
  35 from gi import _signalhelper as signalhelper
  36
  37 _gobject = gi._gi._gobject
  38
  39 GObjectModule = gi.module.get_introspection_module('GObject')
  40
  41 __all__ = []
  42
  43
  44 from gi import _option as option
  45 sys.modules['gi._gobject.option'] = option
  46
  47
  48 # API aliases for backwards compatibility
  49 for name in ['markup_escape_text', 'get_application_name',
  50              'set_application_name', 'get_prgname', 'set_prgname',
  51              'main_depth', 'filename_display_basename',
  52              'filename_display_name', 'filename_from_utf8',
  53              'uri_list_extract_uris',
  54              'MainLoop', 'MainContext', 'main_context_default',
  55              'source_remove', 'Source', 'Idle', 'Timeout', 'PollFD',
  56              'idle_add', 'timeout_add', 'timeout_add_seconds',
  57              'io_add_watch', 'child_watch_add', 'get_current_time',
  58              'spawn_async']:
  59     globals()[name] = getattr(GLib, name)
  60     deprecated_attr("GObject", name, "GLib." + name)
  61     __all__.append(name)
  62
  63 # deprecated constants
  64 for name in ['PRIORITY_DEFAULT', 'PRIORITY_DEFAULT_IDLE', 'PRIORITY_HIGH',
  65              'PRIORITY_HIGH_IDLE', 'PRIORITY_LOW',
  66              'IO_IN', 'IO_OUT', 'IO_PRI', 'IO_ERR', 'IO_HUP', 'IO_NVAL',
  67              'IO_STATUS_ERROR', 'IO_STATUS_NORMAL', 'IO_STATUS_EOF',
  68              'IO_STATUS_AGAIN', 'IO_FLAG_APPEND', 'IO_FLAG_NONBLOCK',
  69              'IO_FLAG_IS_READABLE', 'IO_FLAG_IS_WRITEABLE',
  70              'IO_FLAG_IS_SEEKABLE', 'IO_FLAG_MASK', 'IO_FLAG_GET_MASK',
  71              'IO_FLAG_SET_MASK',
  72              'SPAWN_LEAVE_DESCRIPTORS_OPEN', 'SPAWN_DO_NOT_REAP_CHILD',
  73              'SPAWN_SEARCH_PATH', 'SPAWN_STDOUT_TO_DEV_NULL',
  74              'SPAWN_STDERR_TO_DEV_NULL', 'SPAWN_CHILD_INHERITS_STDIN',
  75              'SPAWN_FILE_AND_ARGV_ZERO',
  76              'OPTION_FLAG_HIDDEN', 'OPTION_FLAG_IN_MAIN', 'OPTION_FLAG_REVERSE',
  77              'OPTION_FLAG_NO_ARG', 'OPTION_FLAG_FILENAME', 'OPTION_FLAG_OPTIONAL_ARG',
  78              'OPTION_FLAG_NOALIAS', 'OPTION_ERROR_UNKNOWN_OPTION',
  79              'OPTION_ERROR_BAD_VALUE', 'OPTION_ERROR_FAILED', 'OPTION_REMAINING',
  80              'glib_version']:
  81     with warnings.catch_warnings():
  82         # TODO: this uses deprecated Glib attributes, silence for now
  83         warnings.simplefilter('ignore', PyGIDeprecationWarning)
  84         globals()[name] = getattr(GLib, name)
  85     deprecated_attr("GObject", name, "GLib." + name)
  86     __all__.append(name)
  87
  88
  89 for name in ['G_MININT8', 'G_MAXINT8', 'G_MAXUINT8', 'G_MININT16',
  90              'G_MAXINT16', 'G_MAXUINT16', 'G_MININT32', 'G_MAXINT32',
  91              'G_MAXUINT32', 'G_MININT64', 'G_MAXINT64', 'G_MAXUINT64']:
  92     new_name = name.split("_", 1)[-1]
  93     globals()[name] = getattr(GLib, new_name)
  94     deprecated_attr("GObject", name, "GLib." + new_name)
  95     __all__.append(name)
  96
  97 # these are not currently exported in GLib gir, presumably because they are
  98 # platform dependent; so get them from our static bindings
  99 for name in ['G_MINFLOAT', 'G_MAXFLOAT', 'G_MINDOUBLE', 'G_MAXDOUBLE',
 100              'G_MINSHORT', 'G_MAXSHORT', 'G_MAXUSHORT', 'G_MININT', 'G_MAXINT',
 101              'G_MAXUINT', 'G_MINLONG', 'G_MAXLONG', 'G_MAXULONG', 'G_MAXSIZE',
 102              'G_MINSSIZE', 'G_MAXSSIZE', 'G_MINOFFSET', 'G_MAXOFFSET']:
 103     new_name = name.split("_", 1)[-1]
 104     globals()[name] = getattr(GLib, new_name)
 105     deprecated_attr("GObject", name, "GLib." + new_name)
 106     __all__.append(name)
 107
 108
 109 TYPE_INVALID = GObjectModule.type_from_name('invalid')
 110 TYPE_NONE = GObjectModule.type_from_name('void')
 111 TYPE_INTERFACE = GObjectModule.type_from_name('GInterface')
 112 TYPE_CHAR = GObjectModule.type_from_name('gchar')
 113 TYPE_UCHAR = GObjectModule.type_from_name('guchar')
 114 TYPE_BOOLEAN = GObjectModule.type_from_name('gboolean')
 115 TYPE_INT = GObjectModule.type_from_name('gint')
 116 TYPE_UINT = GObjectModule.type_from_name('guint')
 117 TYPE_LONG = GObjectModule.type_from_name('glong')
 118 TYPE_ULONG = GObjectModule.type_from_name('gulong')
 119 TYPE_INT64 = GObjectModule.type_from_name('gint64')
 120 TYPE_UINT64 = GObjectModule.type_from_name('guint64')
 121 TYPE_ENUM = GObjectModule.type_from_name('GEnum')
 122 TYPE_FLAGS = GObjectModule.type_from_name('GFlags')
 123 TYPE_FLOAT = GObjectModule.type_from_name('gfloat')
 124 TYPE_DOUBLE = GObjectModule.type_from_name('gdouble')
 125 TYPE_STRING = GObjectModule.type_from_name('gchararray')
 126 TYPE_POINTER = GObjectModule.type_from_name('gpointer')
 127 TYPE_BOXED = GObjectModule.type_from_name('GBoxed')
 128 TYPE_PARAM = GObjectModule.type_from_name('GParam')
 129 TYPE_OBJECT = GObjectModule.type_from_name('GObject')
 130 TYPE_PYOBJECT = GObjectModule.type_from_name('PyObject')
 131 TYPE_GTYPE = GObjectModule.type_from_name('GType')
 132 TYPE_STRV = GObjectModule.type_from_name('GStrv')
 133 TYPE_VARIANT = GObjectModule.type_from_name('GVariant')
 134 TYPE_GSTRING = GObjectModule.type_from_name('GString')
 135 TYPE_VALUE = GObjectModule.Value.__gtype__
 136 TYPE_UNICHAR = TYPE_UINT
 137 __all__ += ['TYPE_INVALID', 'TYPE_NONE', 'TYPE_INTERFACE', 'TYPE_CHAR',
 138             'TYPE_UCHAR', 'TYPE_BOOLEAN', 'TYPE_INT', 'TYPE_UINT', 'TYPE_LONG',
 139             'TYPE_ULONG', 'TYPE_INT64', 'TYPE_UINT64', 'TYPE_ENUM', 'TYPE_FLAGS',
 140             'TYPE_FLOAT', 'TYPE_DOUBLE', 'TYPE_STRING', 'TYPE_POINTER',
 141             'TYPE_BOXED', 'TYPE_PARAM', 'TYPE_OBJECT', 'TYPE_PYOBJECT',
 142             'TYPE_GTYPE', 'TYPE_STRV', 'TYPE_VARIANT', 'TYPE_GSTRING',
 143             'TYPE_UNICHAR', 'TYPE_VALUE']
 144
 145
 146 # Deprecated, use GLib directly
 147 for name in ['Pid', 'GError', 'OptionGroup', 'OptionContext']:
 148     globals()[name] = getattr(GLib, name)
 149     deprecated_attr("GObject", name, "GLib." + name)
 150     __all__.append(name)
 151
 152
 153 # Deprecated, use: GObject.ParamFlags.* directly
 154 for name in ['PARAM_CONSTRUCT', 'PARAM_CONSTRUCT_ONLY', 'PARAM_LAX_VALIDATION',
 155              'PARAM_READABLE', 'PARAM_WRITABLE']:
 156     new_name = name.split("_", 1)[-1]
 157     globals()[name] = getattr(GObjectModule.ParamFlags, new_name)
 158     deprecated_attr("GObject", name, "GObject.ParamFlags." + new_name)
 159     __all__.append(name)
 160
 161 # PARAM_READWRITE should come from the gi module but cannot due to:
 162 # https://bugzilla.gnome.org/show_bug.cgi?id=687615
 163 PARAM_READWRITE = GObjectModule.ParamFlags.READABLE | \
 164     GObjectModule.ParamFlags.WRITABLE
 165 __all__.append("PARAM_READWRITE")
 166
 167 # READWRITE is part of ParamFlags since glib 2.42. Only mark PARAM_READWRITE as
 168 # deprecated in case ParamFlags.READWRITE is available. Also include the glib
 169 # version in the warning so it's clear that this needs a newer glib, unlike
 170 # the other ParamFlags related deprecations.
 171 # https://bugzilla.gnome.org/show_bug.cgi?id=726037
 172 if hasattr(GObjectModule.ParamFlags, "READWRITE"):
 173     deprecated_attr("GObject", "PARAM_READWRITE",
 174                     "GObject.ParamFlags.READWRITE (glib 2.42+)")
 175
 176
 177 # Deprecated, use: GObject.SignalFlags.* directly
 178 for name in ['SIGNAL_ACTION', 'SIGNAL_DETAILED', 'SIGNAL_NO_HOOKS',
 179              'SIGNAL_NO_RECURSE', 'SIGNAL_RUN_CLEANUP', 'SIGNAL_RUN_FIRST',
 180              'SIGNAL_RUN_LAST']:
 181     new_name = name.split("_", 1)[-1]
 182     globals()[name] = getattr(GObjectModule.SignalFlags, new_name)
 183     deprecated_attr("GObject", name, "GObject.SignalFlags." + new_name)
 184     __all__.append(name)
 185
 186 # Static types
 187 GBoxed = _gobject.GBoxed
 188 GEnum = _gobject.GEnum
 189 GFlags = _gobject.GFlags
 190 GInterface = _gobject.GInterface
 191 GObject = _gobject.GObject
 192 GObjectWeakRef = _gobject.GObjectWeakRef
 193 GParamSpec = _gobject.GParamSpec
 194 GPointer = _gobject.GPointer
 195 GType = _gobject.GType
 196 Warning = _gobject.Warning
 197 __all__ += ['GBoxed', 'GEnum', 'GFlags', 'GInterface', 'GObject',
 198             'GObjectWeakRef', 'GParamSpec', 'GPointer', 'GType',
 199             'Warning']
 200
 201
 202 features = _gobject.features
 203 list_properties = _gobject.list_properties
 204 new = _gobject.new
 205 pygobject_version = _gobject.pygobject_version
 206 threads_init = GLib.threads_init
 207 type_register = _gobject.type_register
 208 __all__ += ['features', 'list_properties', 'new',
 209             'pygobject_version', 'threads_init', 'type_register']
 210
 211
 212 class Value(GObjectModule.Value):
 213     def __init__(self, value_type=None, py_value=None):
 214         GObjectModule.Value.__init__(self)
 215         if value_type is not None:
 216             self.init(value_type)
 217             if py_value is not None:
 218                 self.set_value(py_value)
 219
 220     def __del__(self):
 221         if self._free_on_dealloc and self.g_type != TYPE_INVALID:
 222             self.unset()
 223
 224         # We must call base class __del__() after unset.
 225         super(Value, self).__del__()
 226
 227     def set_boxed(self, boxed):
 228         # Workaround the introspection marshalers inability to know
 229         # these methods should be marshaling boxed types. This is because
 230         # the type information is stored on the GValue.
 231         _gobject._gvalue_set(self, boxed)
 232
 233     def get_boxed(self):
 234         return _gobject._gvalue_get(self)
 235
 236     def set_value(self, py_value):
 237         gtype = self.g_type
 238
 239         if gtype == _gobject.TYPE_INVALID:
 240             raise TypeError("GObject.Value needs to be initialized first")
 241         elif gtype == TYPE_BOOLEAN:
 242             self.set_boolean(py_value)
 243         elif gtype == TYPE_CHAR:
 244             self.set_char(py_value)
 245         elif gtype == TYPE_UCHAR:
 246             self.set_uchar(py_value)
 247         elif gtype == TYPE_INT:
 248             self.set_int(py_value)
 249         elif gtype == TYPE_UINT:
 250             self.set_uint(py_value)
 251         elif gtype == TYPE_LONG:
 252             self.set_long(py_value)
 253         elif gtype == TYPE_ULONG:
 254             self.set_ulong(py_value)
 255         elif gtype == TYPE_INT64:
 256             self.set_int64(py_value)
 257         elif gtype == TYPE_UINT64:
 258             self.set_uint64(py_value)
 259         elif gtype == TYPE_FLOAT:
 260             self.set_float(py_value)
 261         elif gtype == TYPE_DOUBLE:
 262             self.set_double(py_value)
 263         elif gtype == TYPE_STRING:
 264             if isinstance(py_value, str):
 265                 py_value = str(py_value)
 266             elif sys.version_info < (3, 0):
 267                 if isinstance(py_value, unicode):
 268                     py_value = py_value.encode('UTF-8')
 269                 else:
 270                     raise ValueError("Expected string or unicode but got %s%s" %
 271                                      (py_value, type(py_value)))
 272             else:
 273                 raise ValueError("Expected string but got %s%s" %
 274                                  (py_value, type(py_value)))
 275             self.set_string(py_value)
 276         elif gtype == TYPE_PARAM:
 277             self.set_param(py_value)
 278         elif gtype.is_a(TYPE_ENUM):
 279             self.set_enum(py_value)
 280         elif gtype.is_a(TYPE_FLAGS):
 281             self.set_flags(py_value)
 282         elif gtype.is_a(TYPE_BOXED):
 283             self.set_boxed(py_value)
 284         elif gtype == TYPE_POINTER:
 285             self.set_pointer(py_value)
 286         elif gtype.is_a(TYPE_OBJECT):
 287             self.set_object(py_value)
 288         elif gtype == TYPE_UNICHAR:
 289             self.set_uint(int(py_value))
 290         # elif gtype == TYPE_OVERRIDE:
 291         #     pass
 292         elif gtype == TYPE_GTYPE:
 293             self.set_gtype(py_value)
 294         elif gtype == TYPE_VARIANT:
 295             self.set_variant(py_value)
 296         elif gtype == TYPE_PYOBJECT:
 297             self.set_boxed(py_value)
 298         else:
 299             raise TypeError("Unknown value type %s" % gtype)
 300
 301     def get_value(self):
 302         gtype = self.g_type
 303
 304         if gtype == TYPE_BOOLEAN:
 305             return self.get_boolean()
 306         elif gtype == TYPE_CHAR:
 307             return self.get_char()
 308         elif gtype == TYPE_UCHAR:
 309             return self.get_uchar()
 310         elif gtype == TYPE_INT:
 311             return self.get_int()
 312         elif gtype == TYPE_UINT:
 313             return self.get_uint()
 314         elif gtype == TYPE_LONG:
 315             return self.get_long()
 316         elif gtype == TYPE_ULONG:
 317             return self.get_ulong()
 318         elif gtype == TYPE_INT64:
 319             return self.get_int64()
 320         elif gtype == TYPE_UINT64:
 321             return self.get_uint64()
 322         elif gtype == TYPE_FLOAT:
 323             return self.get_float()
 324         elif gtype == TYPE_DOUBLE:
 325             return self.get_double()
 326         elif gtype == TYPE_STRING:
 327             return self.get_string()
 328         elif gtype == TYPE_PARAM:
 329             return self.get_param()
 330         elif gtype.is_a(TYPE_ENUM):
 331             return self.get_enum()
 332         elif gtype.is_a(TYPE_FLAGS):
 333             return self.get_flags()
 334         elif gtype.is_a(TYPE_BOXED):
 335             return self.get_boxed()
 336         elif gtype == TYPE_POINTER:
 337             return self.get_pointer()
 338         elif gtype.is_a(TYPE_OBJECT):
 339             return self.get_object()
 340         elif gtype == TYPE_UNICHAR:
 341             return self.get_uint()
 342         elif gtype == TYPE_GTYPE:
 343             return self.get_gtype()
 344         elif gtype == TYPE_VARIANT:
 345             return self.get_variant()
 346         elif gtype == TYPE_PYOBJECT:
 347             pass
 348         else:
 349             return None
 350
 351     def __repr__(self):
 352         return '<Value (%s) %s>' % (self.g_type.name, self.get_value())
 353
 354
 355 Value = override(Value)
 356 __all__.append('Value')
 357
 358
 359 def type_from_name(name):
 360     type_ = GObjectModule.type_from_name(name)
 361     if type_ == TYPE_INVALID:
 362         raise RuntimeError('unknown type name: %s' % name)
 363     return type_
 364
 365
 366 __all__.append('type_from_name')
 367
 368
 369 def type_parent(type_):
 370     parent = GObjectModule.type_parent(type_)
 371     if parent == TYPE_INVALID:
 372         raise RuntimeError('no parent for type')
 373     return parent
 374
 375
 376 __all__.append('type_parent')
 377
 378
 379 def _validate_type_for_signal_method(type_):
 380     if hasattr(type_, '__gtype__'):
 381         type_ = type_.__gtype__
 382     if not type_.is_instantiatable() and not type_.is_interface():
 383         raise TypeError('type must be instantiable or an interface, got %s' % type_)
 384
 385
 386 def signal_list_ids(type_):
 387     _validate_type_for_signal_method(type_)
 388     return GObjectModule.signal_list_ids(type_)
 389
 390
 391 __all__.append('signal_list_ids')
 392
 393
 394 def signal_list_names(type_):
 395     ids = signal_list_ids(type_)
 396     return tuple(GObjectModule.signal_name(i) for i in ids)
 397
 398
 399 __all__.append('signal_list_names')
 400
 401
 402 def signal_lookup(name, type_):
 403     _validate_type_for_signal_method(type_)
 404     return GObjectModule.signal_lookup(name, type_)
 405
 406
 407 __all__.append('signal_lookup')
 408
 409
 410 SignalQuery = namedtuple('SignalQuery',
 411                          ['signal_id',
 412                           'signal_name',
 413                           'itype',
 414                           'signal_flags',
 415                           'return_type',
 416                           # n_params',
 417                           'param_types'])
 418
 419
 420 def signal_query(id_or_name, type_=None):
 421     if type_ is not None:
 422         id_or_name = signal_lookup(id_or_name, type_)
 423
 424     res = GObjectModule.signal_query(id_or_name)
 425     if res is None:
 426         return None
 427
 428     if res.signal_id == 0:
 429         return None
 430
 431     # Return a named tuple to allows indexing which is compatible with the
 432     # static bindings along with field like access of the gi struct.
 433     # Note however that the n_params was not returned from the static bindings
 434     # so we must skip over it.
 435     return SignalQuery(res.signal_id, res.signal_name, res.itype,
 436                        res.signal_flags, res.return_type,
 437                        tuple(res.param_types))
 438
 439
 440 __all__.append('signal_query')
 441
 442
 443 class _HandlerBlockManager(object):
 444     def __init__(self, obj, handler_id):
 445         self.obj = obj
 446         self.handler_id = handler_id
 447
 448     def __enter__(self):
 449         pass
 450
 451     def __exit__(self, exc_type, exc_value, traceback):
 452         GObjectModule.signal_handler_unblock(self.obj, self.handler_id)
 453
 454
 455 def signal_handler_block(obj, handler_id):
 456     """Blocks the signal handler from being invoked until
 457     handler_unblock() is called.
 458
 459     :param GObject.Object obj:
 460         Object instance to block handlers for.
 461     :param int handler_id:
 462         Id of signal to block.
 463     :returns:
 464         A context manager which optionally can be used to
 465         automatically unblock the handler:
 466
 467     .. code-block:: python
 468
 469         with GObject.signal_handler_block(obj, id):
 470             pass
 471     """
 472     GObjectModule.signal_handler_block(obj, handler_id)
 473     return _HandlerBlockManager(obj, handler_id)
 474
 475
 476 __all__.append('signal_handler_block')
 477
 478
 479 def signal_parse_name(detailed_signal, itype, force_detail_quark):
 480     """Parse a detailed signal name into (signal_id, detail).
 481
 482     :param str detailed_signal:
 483         Signal name which can include detail.
 484         For example: "notify:prop_name"
 485     :returns:
 486         Tuple of (signal_id, detail)
 487     :raises ValueError:
 488         If the given signal is unknown.
 489     """
 490     res, signal_id, detail = GObjectModule.signal_parse_name(detailed_signal, itype,
 491                                                              force_detail_quark)
 492     if res:
 493         return signal_id, detail
 494     else:
 495         raise ValueError('%s: unknown signal name: %s' % (itype, detailed_signal))
 496
 497
 498 __all__.append('signal_parse_name')
 499
 500
 501 def remove_emission_hook(obj, detailed_signal, hook_id):
 502     signal_id, detail = signal_parse_name(detailed_signal, obj, True)
 503     GObjectModule.signal_remove_emission_hook(signal_id, hook_id)
 504
 505
 506 __all__.append('remove_emission_hook')
 507
 508
 509 # GObject accumulators with pure Python implementations
 510 # These return a tuple of (continue_emission, accumulation_result)
 511
 512 def signal_accumulator_first_wins(ihint, return_accu, handler_return, user_data=None):
 513     # Stop emission but return the result of the last handler
 514     return (False, handler_return)
 515
 516
 517 __all__.append('signal_accumulator_first_wins')
 518
 519
 520 def signal_accumulator_true_handled(ihint, return_accu, handler_return, user_data=None):
 521     # Stop emission if the last handler returns True
 522     return (not handler_return, handler_return)
 523
 524
 525 __all__.append('signal_accumulator_true_handled')
 526
 527
 528 # Statically bound signal functions which need to clobber GI (for now)
 529
 530 add_emission_hook = _gobject.add_emission_hook
 531 signal_new = _gobject.signal_new
 532
 533 __all__ += ['add_emission_hook', 'signal_new']
 534
 535
 536 class _FreezeNotifyManager(object):
 537     def __init__(self, obj):
 538         self.obj = obj
 539
 540     def __enter__(self):
 541         pass
 542
 543     def __exit__(self, exc_type, exc_value, traceback):
 544         self.obj.thaw_notify()
 545
 546
 547 def _signalmethod(func):
 548     # Function wrapper for signal functions used as instance methods.
 549     # This is needed when the signal functions come directly from GI.
 550     # (they are not already wrapped)
 551     @gi.overrides.wraps(func)
 552     def meth(*args, **kwargs):
 553         return func(*args, **kwargs)
 554     return meth
 555
 556
 557 class Object(GObjectModule.Object):
 558     def _unsupported_method(self, *args, **kargs):
 559         raise RuntimeError('This method is currently unsupported.')
 560
 561     def _unsupported_data_method(self, *args, **kargs):
 562         raise RuntimeError('Data access methods are unsupported. '
 563                            'Use normal Python attributes instead')
 564
 565     # Generic data methods are not needed in python as it can be handled
 566     # with standard attribute access: https://bugzilla.gnome.org/show_bug.cgi?id=641944
 567     get_data = _unsupported_data_method
 568     get_qdata = _unsupported_data_method
 569     set_data = _unsupported_data_method
 570     steal_data = _unsupported_data_method
 571     steal_qdata = _unsupported_data_method
 572     replace_data = _unsupported_data_method
 573     replace_qdata = _unsupported_data_method
 574
 575     # The following methods as unsupported until we verify
 576     # they work as gi methods.
 577     bind_property_full = _unsupported_method
 578     compat_control = _unsupported_method
 579     interface_find_property = _unsupported_method
 580     interface_install_property = _unsupported_method
 581     interface_list_properties = _unsupported_method
 582     notify_by_pspec = _unsupported_method
 583     run_dispose = _unsupported_method
 584     watch_closure = _unsupported_method
 585
 586     # Make all reference management methods private but still accessible.
 587     _ref = GObjectModule.Object.ref
 588     _ref_sink = GObjectModule.Object.ref_sink
 589     _unref = GObjectModule.Object.unref
 590     _force_floating = GObjectModule.Object.force_floating
 591
 592     ref = _unsupported_method
 593     ref_sink = _unsupported_method
 594     unref = _unsupported_method
 595     force_floating = _unsupported_method
 596
 597     # The following methods are static APIs which need to leap frog the
 598     # gi methods until we verify the gi methods can replace them.
 599     get_property = _gobject.GObject.get_property
 600     get_properties = _gobject.GObject.get_properties
 601     set_property = _gobject.GObject.set_property
 602     set_properties = _gobject.GObject.set_properties
 603     bind_property = _gobject.GObject.bind_property
 604     connect = _gobject.GObject.connect
 605     connect_after = _gobject.GObject.connect_after
 606     connect_object = _gobject.GObject.connect_object
 607     connect_object_after = _gobject.GObject.connect_object_after
 608     disconnect_by_func = _gobject.GObject.disconnect_by_func
 609     handler_block_by_func = _gobject.GObject.handler_block_by_func
 610     handler_unblock_by_func = _gobject.GObject.handler_unblock_by_func
 611     emit = _gobject.GObject.emit
 612     chain = _gobject.GObject.chain
 613     weak_ref = _gobject.GObject.weak_ref
 614     __copy__ = _gobject.GObject.__copy__
 615     __deepcopy__ = _gobject.GObject.__deepcopy__
 616
 617     def freeze_notify(self):
 618         """Freezes the object's property-changed notification queue.
 619
 620         :returns:
 621             A context manager which optionally can be used to
 622             automatically thaw notifications.
 623
 624         This will freeze the object so that "notify" signals are blocked until
 625         the thaw_notify() method is called.
 626
 627         .. code-block:: python
 628
 629             with obj.freeze_notify():
 630                 pass
 631         """
 632         super(Object, self).freeze_notify()
 633         return _FreezeNotifyManager(self)
 634
 635     def connect_data(self, detailed_signal, handler, *data, **kwargs):
 636         """Connect a callback to the given signal with optional user data.
 637
 638         :param str detailed_signal:
 639             A detailed signal to connect to.
 640         :param callable handler:
 641             Callback handler to connect to the signal.
 642         :param *data:
 643             Variable data which is passed through to the signal handler.
 644         :param GObject.ConnectFlags connect_flags:
 645             Flags used for connection options.
 646         :returns:
 647             A signal id which can be used with disconnect.
 648         """
 649         flags = kwargs.get('connect_flags', 0)
 650         if flags & GObjectModule.ConnectFlags.AFTER:
 651             connect_func = _gobject.GObject.connect_after
 652         else:
 653             connect_func = _gobject.GObject.connect
 654
 655         if flags & GObjectModule.ConnectFlags.SWAPPED:
 656             if len(data) != 1:
 657                 raise ValueError('Using GObject.ConnectFlags.SWAPPED requires exactly '
 658                                  'one argument for user data, got: %s' % [data])
 659
 660             def new_handler(obj, *args):
 661                 # Swap obj with the last element in args which will be the user
 662                 # data passed to the connect function.
 663                 args = list(args)
 664                 swap = args.pop()
 665                 args = args + [obj]
 666                 return handler(swap, *args)
 667         else:
 668             new_handler = handler
 669
 670         return connect_func(self, detailed_signal, new_handler, *data)
 671
 672     #
 673     # Aliases
 674     #
 675
 676     handler_block = signal_handler_block
 677     handler_unblock = _signalmethod(GObjectModule.signal_handler_unblock)
 678     disconnect = _signalmethod(GObjectModule.signal_handler_disconnect)
 679     handler_disconnect = _signalmethod(GObjectModule.signal_handler_disconnect)
 680     handler_is_connected = _signalmethod(GObjectModule.signal_handler_is_connected)
 681     stop_emission_by_name = _signalmethod(GObjectModule.signal_stop_emission_by_name)
 682
 683     #
 684     # Deprecated Methods
 685     #
 686
 687     def stop_emission(self, detailed_signal):
 688         """Deprecated, please use stop_emission_by_name."""
 689         warnings.warn(self.stop_emission.__doc__, PyGIDeprecationWarning, stacklevel=2)
 690         return self.stop_emission_by_name(detailed_signal)
 691
 692     emit_stop_by_name = stop_emission
 693
 694
 695 Object = override(Object)
 696 GObject = Object
 697 __all__ += ['Object', 'GObject']
 698
 699
 700 class Binding(GObjectModule.Binding):
 701     def __call__(self):
 702         warnings.warn('Using parentheses (binding()) to retrieve the Binding object is no '
 703                       'longer needed because the binding is returned directly from "bind_property.',
 704                       PyGIDeprecationWarning, stacklevel=2)
 705         return self
 706
 707     def unbind(self):
 708         if hasattr(self, '_unbound'):
 709             raise ValueError('binding has already been cleared out')
 710         else:
 711             setattr(self, '_unbound', True)
 712             super(Binding, self).unbind()
 713
 714
 715 Binding = override(Binding)
 716 __all__.append('Binding')
 717
 718
 719 Property = propertyhelper.Property
 720 Signal = signalhelper.Signal
 721 SignalOverride = signalhelper.SignalOverride
 722 # Deprecated naming "property" available for backwards compatibility.
 723 # Keep this at the end of the file to avoid clobbering the builtin.
 724 property = Property
 725 deprecated_attr("GObject", "property", "GObject.Property")
 726 __all__ += ['Property', 'Signal', 'SignalOverride', 'property']