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 import functools
  27 from collections import namedtuple
  28
  29 import gi.overrides
  30 import gi.module
  31 from gi.overrides import override
  32 from gi.repository import GLib
  33 from gi import PyGIDeprecationWarning
  34
  35 from gi._gobject import _gobject
  36 from gi._gobject import propertyhelper
  37 from gi._gobject import signalhelper
  38
  39 GObjectModule = gi.module.get_introspection_module('GObject')
  40
  41 __all__ = []
  42
  43
  44 from gi._glib import 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] = gi.overrides.deprecated(getattr(GLib, name), 'GLib.' + name)
  60     __all__.append(name)
  61
  62 # constants are also deprecated, but cannot mark them as such
  63 for name in ['PRIORITY_DEFAULT', 'PRIORITY_DEFAULT_IDLE', 'PRIORITY_HIGH',
  64              'PRIORITY_HIGH_IDLE', 'PRIORITY_LOW',
  65              'IO_IN', 'IO_OUT', 'IO_PRI', 'IO_ERR', 'IO_HUP', 'IO_NVAL',
  66              'IO_STATUS_ERROR', 'IO_STATUS_NORMAL', 'IO_STATUS_EOF',
  67              'IO_STATUS_AGAIN', 'IO_FLAG_APPEND', 'IO_FLAG_NONBLOCK',
  68              'IO_FLAG_IS_READABLE', 'IO_FLAG_IS_WRITEABLE',
  69              'IO_FLAG_IS_SEEKABLE', 'IO_FLAG_MASK', 'IO_FLAG_GET_MASK',
  70              'IO_FLAG_SET_MASK',
  71              'SPAWN_LEAVE_DESCRIPTORS_OPEN', 'SPAWN_DO_NOT_REAP_CHILD',
  72              'SPAWN_SEARCH_PATH', 'SPAWN_STDOUT_TO_DEV_NULL',
  73              'SPAWN_STDERR_TO_DEV_NULL', 'SPAWN_CHILD_INHERITS_STDIN',
  74              'SPAWN_FILE_AND_ARGV_ZERO',
  75              'OPTION_FLAG_HIDDEN', 'OPTION_FLAG_IN_MAIN', 'OPTION_FLAG_REVERSE',
  76              'OPTION_FLAG_NO_ARG', 'OPTION_FLAG_FILENAME', 'OPTION_FLAG_OPTIONAL_ARG',
  77              'OPTION_FLAG_NOALIAS', 'OPTION_ERROR_UNKNOWN_OPTION',
  78              'OPTION_ERROR_BAD_VALUE', 'OPTION_ERROR_FAILED', 'OPTION_REMAINING',
  79              'glib_version']:
  80     globals()[name] = getattr(GLib, name)
  81     __all__.append(name)
  82
  83
  84 G_MININT8 = GLib.MININT8
  85 G_MAXINT8 = GLib.MAXINT8
  86 G_MAXUINT8 = GLib.MAXUINT8
  87 G_MININT16 = GLib.MININT16
  88 G_MAXINT16 = GLib.MAXINT16
  89 G_MAXUINT16 = GLib.MAXUINT16
  90 G_MININT32 = GLib.MININT32
  91 G_MAXINT32 = GLib.MAXINT32
  92 G_MAXUINT32 = GLib.MAXUINT32
  93 G_MININT64 = GLib.MININT64
  94 G_MAXINT64 = GLib.MAXINT64
  95 G_MAXUINT64 = GLib.MAXUINT64
  96 __all__ += ['G_MININT8', 'G_MAXINT8', 'G_MAXUINT8', 'G_MININT16',
  97             'G_MAXINT16', 'G_MAXUINT16', 'G_MININT32', 'G_MAXINT32',
  98             'G_MAXUINT32', 'G_MININT64', 'G_MAXINT64', 'G_MAXUINT64']
  99
 100 # these are not currently exported in GLib gir, presumably because they are
 101 # platform dependent; so get them from our static bindings
 102 for name in ['G_MINFLOAT', 'G_MAXFLOAT', 'G_MINDOUBLE', 'G_MAXDOUBLE',
 103              'G_MINSHORT', 'G_MAXSHORT', 'G_MAXUSHORT', 'G_MININT', 'G_MAXINT',
 104              'G_MAXUINT', 'G_MINLONG', 'G_MAXLONG', 'G_MAXULONG', 'G_MAXSIZE',
 105              'G_MINSSIZE', 'G_MAXSSIZE', 'G_MINOFFSET', 'G_MAXOFFSET']:
 106     globals()[name] = getattr(_gobject, name)
 107     __all__.append(name)
 108
 109
 110 TYPE_INVALID = GObjectModule.type_from_name('invalid')
 111 TYPE_NONE = GObjectModule.type_from_name('void')
 112 TYPE_INTERFACE = GObjectModule.type_from_name('GInterface')
 113 TYPE_CHAR = GObjectModule.type_from_name('gchar')
 114 TYPE_UCHAR = GObjectModule.type_from_name('guchar')
 115 TYPE_BOOLEAN = GObjectModule.type_from_name('gboolean')
 116 TYPE_INT = GObjectModule.type_from_name('gint')
 117 TYPE_UINT = GObjectModule.type_from_name('guint')
 118 TYPE_LONG = GObjectModule.type_from_name('glong')
 119 TYPE_ULONG = GObjectModule.type_from_name('gulong')
 120 TYPE_INT64 = GObjectModule.type_from_name('gint64')
 121 TYPE_UINT64 = GObjectModule.type_from_name('guint64')
 122 TYPE_ENUM = GObjectModule.type_from_name('GEnum')
 123 TYPE_FLAGS = GObjectModule.type_from_name('GFlags')
 124 TYPE_FLOAT = GObjectModule.type_from_name('gfloat')
 125 TYPE_DOUBLE = GObjectModule.type_from_name('gdouble')
 126 TYPE_STRING = GObjectModule.type_from_name('gchararray')
 127 TYPE_POINTER = GObjectModule.type_from_name('gpointer')
 128 TYPE_BOXED = GObjectModule.type_from_name('GBoxed')
 129 TYPE_PARAM = GObjectModule.type_from_name('GParam')
 130 TYPE_OBJECT = GObjectModule.type_from_name('GObject')
 131 TYPE_PYOBJECT = GObjectModule.type_from_name('PyObject')
 132 TYPE_GTYPE = GObjectModule.type_from_name('GType')
 133 TYPE_STRV = GObjectModule.type_from_name('GStrv')
 134 TYPE_VARIANT = GObjectModule.type_from_name('GVariant')
 135 TYPE_GSTRING = GObjectModule.type_from_name('GString')
 136 TYPE_VALUE = GObjectModule.Value.__gtype__
 137 TYPE_UNICHAR = TYPE_UINT
 138 __all__ += ['TYPE_INVALID', 'TYPE_NONE', 'TYPE_INTERFACE', 'TYPE_CHAR',
 139             'TYPE_UCHAR', 'TYPE_BOOLEAN', 'TYPE_INT', 'TYPE_UINT', 'TYPE_LONG',
 140             'TYPE_ULONG', 'TYPE_INT64', 'TYPE_UINT64', 'TYPE_ENUM', 'TYPE_FLAGS',
 141             'TYPE_FLOAT', 'TYPE_DOUBLE', 'TYPE_STRING', 'TYPE_POINTER',
 142             'TYPE_BOXED', 'TYPE_PARAM', 'TYPE_OBJECT', 'TYPE_PYOBJECT',
 143             'TYPE_GTYPE', 'TYPE_STRV', 'TYPE_VARIANT', 'TYPE_GSTRING',
 144             'TYPE_UNICHAR', 'TYPE_VALUE']
 145
 146
 147 # Deprecated, use GLib directly
 148 Pid = GLib.Pid
 149 GError = GLib.GError
 150 OptionGroup = GLib.OptionGroup
 151 OptionContext = GLib.OptionContext
 152 __all__ += ['Pid', 'GError', 'OptionGroup', 'OptionContext']
 153
 154
 155 # Deprecated, use: GObject.ParamFlags.* directly
 156 PARAM_CONSTRUCT = GObjectModule.ParamFlags.CONSTRUCT
 157 PARAM_CONSTRUCT_ONLY = GObjectModule.ParamFlags.CONSTRUCT_ONLY
 158 PARAM_LAX_VALIDATION = GObjectModule.ParamFlags.LAX_VALIDATION
 159 PARAM_READABLE = GObjectModule.ParamFlags.READABLE
 160 PARAM_WRITABLE = GObjectModule.ParamFlags.WRITABLE
 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 = PARAM_READABLE | PARAM_WRITABLE
 164 __all__ += ['PARAM_CONSTRUCT', 'PARAM_CONSTRUCT_ONLY', 'PARAM_LAX_VALIDATION',
 165             'PARAM_READABLE', 'PARAM_WRITABLE', 'PARAM_READWRITE']
 166
 167
 168 # Deprecated, use: GObject.SignalFlags.* directly
 169 SIGNAL_ACTION = GObjectModule.SignalFlags.ACTION
 170 SIGNAL_DETAILED = GObjectModule.SignalFlags.DETAILED
 171 SIGNAL_NO_HOOKS = GObjectModule.SignalFlags.NO_HOOKS
 172 SIGNAL_NO_RECURSE = GObjectModule.SignalFlags.NO_RECURSE
 173 SIGNAL_RUN_CLEANUP = GObjectModule.SignalFlags.RUN_CLEANUP
 174 SIGNAL_RUN_FIRST = GObjectModule.SignalFlags.RUN_FIRST
 175 SIGNAL_RUN_LAST = GObjectModule.SignalFlags.RUN_LAST
 176 __all__ += ['SIGNAL_ACTION', 'SIGNAL_DETAILED', 'SIGNAL_NO_HOOKS',
 177             'SIGNAL_NO_RECURSE', 'SIGNAL_RUN_CLEANUP', 'SIGNAL_RUN_FIRST',
 178             'SIGNAL_RUN_LAST']
 179
 180
 181 # Static types
 182 GBoxed = _gobject.GBoxed
 183 GEnum = _gobject.GEnum
 184 GFlags = _gobject.GFlags
 185 GInterface = _gobject.GInterface
 186 GObject = _gobject.GObject
 187 GObjectWeakRef = _gobject.GObjectWeakRef
 188 GParamSpec = _gobject.GParamSpec
 189 GPointer = _gobject.GPointer
 190 GType = _gobject.GType
 191 Warning = _gobject.Warning
 192 __all__ += ['GBoxed', 'GEnum', 'GFlags', 'GInterface', 'GObject',
 193             'GObjectWeakRef', 'GParamSpec', 'GPointer', 'GType',
 194             'Warning']
 195
 196
 197 features = _gobject.features
 198 list_properties = _gobject.list_properties
 199 new = _gobject.new
 200 pygobject_version = _gobject.pygobject_version
 201 threads_init = _gobject.threads_init
 202 type_register = _gobject.type_register
 203 __all__ += ['features', 'list_properties', 'new',
 204             'pygobject_version', 'threads_init', 'type_register']
 205
 206
 207 class Value(GObjectModule.Value):
 208     def __new__(cls, *args, **kwargs):
 209         return GObjectModule.Value.__new__(cls)
 210
 211     def __init__(self, value_type=None, py_value=None):
 212         GObjectModule.Value.__init__(self)
 213         if value_type is not None:
 214             self.init(value_type)
 215             if py_value is not None:
 216                 self.set_value(py_value)
 217
 218     def __del__(self):
 219         if self._free_on_dealloc and self.g_type != TYPE_INVALID:
 220             self.unset()
 221
 222     def set_value(self, py_value):
 223         gtype = self.g_type
 224
 225         if gtype == _gobject.TYPE_INVALID:
 226             raise TypeError("GObject.Value needs to be initialized first")
 227         elif gtype == TYPE_BOOLEAN:
 228             self.set_boolean(py_value)
 229         elif gtype == TYPE_CHAR:
 230             self.set_char(py_value)
 231         elif gtype == TYPE_UCHAR:
 232             self.set_uchar(py_value)
 233         elif gtype == TYPE_INT:
 234             self.set_int(py_value)
 235         elif gtype == TYPE_UINT:
 236             self.set_uint(py_value)
 237         elif gtype == TYPE_LONG:
 238             self.set_long(py_value)
 239         elif gtype == TYPE_ULONG:
 240             self.set_ulong(py_value)
 241         elif gtype == TYPE_INT64:
 242             self.set_int64(py_value)
 243         elif gtype == TYPE_UINT64:
 244             self.set_uint64(py_value)
 245         elif gtype == TYPE_FLOAT:
 246             self.set_float(py_value)
 247         elif gtype == TYPE_DOUBLE:
 248             self.set_double(py_value)
 249         elif gtype == TYPE_STRING:
 250             if isinstance(py_value, str):
 251                 py_value = str(py_value)
 252             elif sys.version_info < (3, 0):
 253                 if isinstance(py_value, unicode):
 254                     py_value = py_value.encode('UTF-8')
 255                 else:
 256                     raise ValueError("Expected string or unicode but got %s%s" %
 257                                      (py_value, type(py_value)))
 258             else:
 259                 raise ValueError("Expected string but got %s%s" %
 260                                  (py_value, type(py_value)))
 261             self.set_string(py_value)
 262         elif gtype == TYPE_PARAM:
 263             self.set_param(py_value)
 264         elif gtype.is_a(TYPE_ENUM):
 265             self.set_enum(py_value)
 266         elif gtype.is_a(TYPE_FLAGS):
 267             self.set_flags(py_value)
 268         elif gtype.is_a(TYPE_BOXED):
 269             self.set_boxed(py_value)
 270         elif gtype == TYPE_POINTER:
 271             self.set_pointer(py_value)
 272         elif gtype.is_a(TYPE_OBJECT):
 273             self.set_object(py_value)
 274         elif gtype == TYPE_UNICHAR:
 275             self.set_uint(int(py_value))
 276         # elif gtype == TYPE_OVERRIDE:
 277         #     pass
 278         elif gtype == TYPE_GTYPE:
 279             self.set_gtype(py_value)
 280         elif gtype == TYPE_VARIANT:
 281             self.set_variant(py_value)
 282         elif gtype == TYPE_PYOBJECT:
 283             self.set_boxed(py_value)
 284         else:
 285             raise TypeError("Unknown value type %s" % gtype)
 286
 287     def get_value(self):
 288         gtype = self.g_type
 289
 290         if gtype == TYPE_BOOLEAN:
 291             return self.get_boolean()
 292         elif gtype == TYPE_CHAR:
 293             return self.get_char()
 294         elif gtype == TYPE_UCHAR:
 295             return self.get_uchar()
 296         elif gtype == TYPE_INT:
 297             return self.get_int()
 298         elif gtype == TYPE_UINT:
 299             return self.get_uint()
 300         elif gtype == TYPE_LONG:
 301             return self.get_long()
 302         elif gtype == TYPE_ULONG:
 303             return self.get_ulong()
 304         elif gtype == TYPE_INT64:
 305             return self.get_int64()
 306         elif gtype == TYPE_UINT64:
 307             return self.get_uint64()
 308         elif gtype == TYPE_FLOAT:
 309             return self.get_float()
 310         elif gtype == TYPE_DOUBLE:
 311             return self.get_double()
 312         elif gtype == TYPE_STRING:
 313             return self.get_string()
 314         elif gtype == TYPE_PARAM:
 315             return self.get_param()
 316         elif gtype.is_a(TYPE_ENUM):
 317             return self.get_enum()
 318         elif gtype.is_a(TYPE_FLAGS):
 319             return self.get_flags()
 320         elif gtype.is_a(TYPE_BOXED):
 321             return self.get_boxed()
 322         elif gtype == TYPE_POINTER:
 323             return self.get_pointer()
 324         elif gtype.is_a(TYPE_OBJECT):
 325             return self.get_object()
 326         elif gtype == TYPE_UNICHAR:
 327             return self.get_uint()
 328         elif gtype == TYPE_GTYPE:
 329             return self.get_gtype()
 330         elif gtype == TYPE_VARIANT:
 331             return self.get_variant()
 332         elif gtype == TYPE_PYOBJECT:
 333             pass
 334         else:
 335             return None
 336
 337     def __repr__(self):
 338         return '<Value (%s) %s>' % (self.g_type.name, self.get_value())
 339
 340 Value = override(Value)
 341 __all__.append('Value')
 342
 343
 344 def type_from_name(name):
 345     type_ = GObjectModule.type_from_name(name)
 346     if type_ == TYPE_INVALID:
 347         raise RuntimeError('unknown type name: %s' % name)
 348     return type_
 349
 350 __all__.append('type_from_name')
 351
 352
 353 def type_parent(type_):
 354     parent = GObjectModule.type_parent(type_)
 355     if parent == TYPE_INVALID:
 356         raise RuntimeError('no parent for type')
 357     return parent
 358
 359 __all__.append('type_parent')
 360
 361
 362 def _validate_type_for_signal_method(type_):
 363     if hasattr(type_, '__gtype__'):
 364         type_ = type_.__gtype__
 365     if not type_.is_instantiatable() and not type_.is_interface():
 366         raise TypeError('type must be instantiable or an interface, got %s' % type_)
 367
 368
 369 def signal_list_ids(type_):
 370     _validate_type_for_signal_method(type_)
 371     return GObjectModule.signal_list_ids(type_)
 372
 373 __all__.append('signal_list_ids')
 374
 375
 376 def signal_list_names(type_):
 377     ids = signal_list_ids(type_)
 378     return tuple(GObjectModule.signal_name(i) for i in ids)
 379
 380 __all__.append('signal_list_names')
 381
 382
 383 def signal_lookup(name, type_):
 384     _validate_type_for_signal_method(type_)
 385     return GObjectModule.signal_lookup(name, type_)
 386
 387 __all__.append('signal_lookup')
 388
 389
 390 def signal_query(id_or_name, type_=None):
 391     SignalQuery = namedtuple('SignalQuery',
 392                              ['signal_id',
 393                               'signal_name',
 394                               'itype',
 395                               'signal_flags',
 396                               'return_type',
 397                               # n_params',
 398                               'param_types'])
 399
 400     # signal_query needs to use a static method until the following bugs are fixed:
 401     # https://bugzilla.gnome.org/show_bug.cgi?id=687550
 402     # https://bugzilla.gnome.org/show_bug.cgi?id=687545
 403     # https://bugzilla.gnome.org/show_bug.cgi?id=687541
 404     if type_ is not None:
 405         id_or_name = signal_lookup(id_or_name, type_)
 406
 407     res = _gobject.signal_query(id_or_name)
 408     if res is None:
 409         return None
 410
 411     # Return a named tuple which allows indexing like the static bindings
 412     # along with field like access of the gi struct.
 413     # Note however that the n_params was not returned from the static bindings.
 414     return SignalQuery(*res)
 415
 416 __all__.append('signal_query')
 417
 418
 419 def _get_instance_for_signal(obj):
 420     if isinstance(obj, GObjectModule.Object):
 421         return obj.__gpointer__
 422     else:
 423         raise TypeError('Unsupported object "%s" for signal function' % obj)
 424
 425
 426 def _wrap_signal_func(func):
 427     @functools.wraps(func)
 428     def wrapper(obj, *args, **kwargs):
 429         return func(_get_instance_for_signal(obj), *args, **kwargs)
 430     return wrapper
 431
 432
 433 class _HandlerBlockManager(object):
 434     def __init__(self, obj, handler_id):
 435         self.obj = obj
 436         self.handler_id = handler_id
 437
 438     def __enter__(self):
 439         pass
 440
 441     def __exit__(self, exc_type, exc_value, traceback):
 442         signal_handler_unblock(self.obj, self.handler_id)
 443
 444
 445 def signal_handler_block(obj, handler_id):
 446     """Blocks the signal handler from being invoked until handler_unblock() is called.
 447
 448     Returns a context manager which optionally can be used to
 449     automatically unblock the handler:
 450
 451     >>> with GObject.signal_handler_block(obj, id):
 452     >>>    pass
 453     """
 454     GObjectModule.signal_handler_block(_get_instance_for_signal(obj), handler_id)
 455     return _HandlerBlockManager(obj, handler_id)
 456
 457 __all__.append('signal_handler_block')
 458
 459
 460 # The following functions wrap GI functions but coerce the first arg into
 461 # something compatible with gpointer
 462
 463 signal_handler_unblock = _wrap_signal_func(GObjectModule.signal_handler_unblock)
 464 signal_handler_disconnect = _wrap_signal_func(GObjectModule.signal_handler_disconnect)
 465 signal_handler_is_connected = _wrap_signal_func(GObjectModule.signal_handler_is_connected)
 466 signal_stop_emission = _wrap_signal_func(GObjectModule.signal_stop_emission)
 467 signal_stop_emission_by_name = _wrap_signal_func(GObjectModule.signal_stop_emission_by_name)
 468 signal_has_handler_pending = _wrap_signal_func(GObjectModule.signal_has_handler_pending)
 469 signal_get_invocation_hint = _wrap_signal_func(GObjectModule.signal_get_invocation_hint)
 470 signal_connect_closure = _wrap_signal_func(GObjectModule.signal_connect_closure)
 471 signal_connect_closure_by_id = _wrap_signal_func(GObjectModule.signal_connect_closure_by_id)
 472 signal_handler_find = _wrap_signal_func(GObjectModule.signal_handler_find)
 473 signal_handlers_destroy = _wrap_signal_func(GObjectModule.signal_handlers_destroy)
 474 signal_handlers_block_matched = _wrap_signal_func(GObjectModule.signal_handlers_block_matched)
 475 signal_handlers_unblock_matched = _wrap_signal_func(GObjectModule.signal_handlers_unblock_matched)
 476 signal_handlers_disconnect_matched = _wrap_signal_func(GObjectModule.signal_handlers_disconnect_matched)
 477
 478 __all__ += ['signal_handler_unblock',
 479             'signal_handler_disconnect', 'signal_handler_is_connected',
 480             'signal_stop_emission', 'signal_stop_emission_by_name',
 481             'signal_has_handler_pending', 'signal_get_invocation_hint',
 482             'signal_connect_closure', 'signal_connect_closure_by_id',
 483             'signal_handler_find', 'signal_handlers_destroy',
 484             'signal_handlers_block_matched', 'signal_handlers_unblock_matched',
 485             'signal_handlers_disconnect_matched']
 486
 487
 488 def signal_parse_name(detailed_signal, itype, force_detail_quark):
 489     """Parse a detailed signal name into (signal_id, detail).
 490
 491     :Raises ValueError:
 492         If the given signal is unknown.
 493
 494     :Returns:
 495         Tuple of (signal_id, detail)
 496     """
 497     res, signal_id, detail = GObjectModule.signal_parse_name(detailed_signal, itype,
 498                                                              force_detail_quark)
 499     if res:
 500         return signal_id, detail
 501     else:
 502         raise ValueError('%s: unknown signal name: %s' % (itype, detailed_signal))
 503
 504 __all__.append('signal_parse_name')
 505
 506
 507 def remove_emission_hook(obj, detailed_signal, hook_id):
 508     signal_id, detail = signal_parse_name(detailed_signal, obj, True)
 509     GObjectModule.signal_remove_emission_hook(signal_id, hook_id)
 510
 511 __all__.append('remove_emission_hook')
 512
 513
 514 # GObject accumulators with pure Python implementations
 515 # These return a tuple of (continue_emission, accumulation_result)
 516
 517 def signal_accumulator_first_wins(ihint, return_accu, handler_return, user_data=None):
 518     # Stop emission but return the result of the last handler
 519     return (False, handler_return)
 520
 521 __all__.append('signal_accumulator_first_wins')
 522
 523
 524 def signal_accumulator_true_handled(ihint, return_accu, handler_return, user_data=None):
 525     # Stop emission if the last handler returns True
 526     return (not handler_return, handler_return)
 527
 528 __all__.append('signal_accumulator_true_handled')
 529
 530
 531 # Statically bound signal functions which need to clobber GI (for now)
 532
 533 add_emission_hook = _gobject.add_emission_hook
 534 signal_new = _gobject.signal_new
 535
 536 __all__ += ['add_emission_hook', 'signal_new']
 537
 538
 539 class _FreezeNotifyManager(object):
 540     def __init__(self, obj):
 541         self.obj = obj
 542
 543     def __enter__(self):
 544         pass
 545
 546     def __exit__(self, exc_type, exc_value, traceback):
 547         self.obj.thaw_notify()
 548
 549
 550 class Object(GObjectModule.Object):
 551     def _unsupported_method(self, *args, **kargs):
 552         raise RuntimeError('This method is currently unsupported.')
 553
 554     def _unsupported_data_method(self, *args, **kargs):
 555         raise RuntimeError('Data access methods are unsupported. '
 556                            'Use normal Python attributes instead')
 557
 558     # Generic data methods are not needed in python as it can be handled
 559     # with standard attribute access: https://bugzilla.gnome.org/show_bug.cgi?id=641944
 560     get_data = _unsupported_data_method
 561     get_qdata = _unsupported_data_method
 562     set_data = _unsupported_data_method
 563     steal_data = _unsupported_data_method
 564     steal_qdata = _unsupported_data_method
 565     replace_data = _unsupported_data_method
 566     replace_qdata = _unsupported_data_method
 567
 568     # The following methods as unsupported until we verify
 569     # they work as gi methods.
 570     bind_property_full = _unsupported_method
 571     compat_control = _unsupported_method
 572     interface_find_property = _unsupported_method
 573     interface_install_property = _unsupported_method
 574     interface_list_properties = _unsupported_method
 575     notify_by_pspec = _unsupported_method
 576     run_dispose = _unsupported_method
 577     watch_closure = _unsupported_method
 578
 579     # Make all reference management methods private but still accessible.
 580     _ref = GObjectModule.Object.ref
 581     _ref_sink = GObjectModule.Object.ref_sink
 582     _unref = GObjectModule.Object.unref
 583     _force_floating = GObjectModule.Object.force_floating
 584
 585     ref = _unsupported_method
 586     ref_sink = _unsupported_method
 587     unref = _unsupported_method
 588     force_floating = _unsupported_method
 589
 590     # The following methods are static APIs which need to leap frog the
 591     # gi methods until we verify the gi methods can replace them.
 592     get_property = _gobject.GObject.get_property
 593     get_properties = _gobject.GObject.get_properties
 594     set_property = _gobject.GObject.set_property
 595     set_properties = _gobject.GObject.set_properties
 596     bind_property = _gobject.GObject.bind_property
 597     connect = _gobject.GObject.connect
 598     connect_after = _gobject.GObject.connect_after
 599     connect_object = _gobject.GObject.connect_object
 600     connect_object_after = _gobject.GObject.connect_object_after
 601     disconnect_by_func = _gobject.GObject.disconnect_by_func
 602     handler_block_by_func = _gobject.GObject.handler_block_by_func
 603     handler_unblock_by_func = _gobject.GObject.handler_unblock_by_func
 604     emit = _gobject.GObject.emit
 605     chain = _gobject.GObject.chain
 606     weak_ref = _gobject.GObject.weak_ref
 607     __copy__ = _gobject.GObject.__copy__
 608     __deepcopy__ = _gobject.GObject.__deepcopy__
 609
 610     def freeze_notify(self):
 611         """Freezes the object's property-changed notification queue.
 612
 613         This will freeze the object so that "notify" signals are blocked until
 614         the thaw_notify() method is called.
 615
 616         Returns a context manager which optionally can be used to
 617         automatically thaw notifications:
 618
 619         >>> with obj.freeze_notify():
 620         >>>     pass
 621         """
 622         super(Object, self).freeze_notify()
 623         return _FreezeNotifyManager(self)
 624
 625     #
 626     # Aliases
 627     #
 628
 629     disconnect = signal_handler_disconnect
 630     handler_block = signal_handler_block
 631     handler_unblock = signal_handler_unblock
 632     handler_disconnect = signal_handler_disconnect
 633     handler_is_connected = signal_handler_is_connected
 634     stop_emission_by_name = signal_stop_emission_by_name
 635
 636     #
 637     # Deprecated Methods
 638     #
 639
 640     def stop_emission(self, detailed_signal):
 641         """Deprecated, please use stop_emission_by_name."""
 642         warnings.warn(self.stop_emission.__doc__, PyGIDeprecationWarning, stacklevel=2)
 643         return signal_stop_emission_by_name(self, detailed_signal)
 644
 645     emit_stop_by_name = stop_emission
 646
 647
 648 Object = override(Object)
 649 GObject = Object
 650 __all__ += ['Object', 'GObject']
 651
 652
 653 Property = propertyhelper.Property
 654 Signal = signalhelper.Signal
 655 SignalOverride = signalhelper.SignalOverride
 656 # Deprecated naming "property" available for backwards compatibility.
 657 # Keep this at the end of the file to avoid clobbering the builtin.
 658 property = Property
 659 __all__ += ['Property', 'Signal', 'SignalOverride', 'property']