dbus/_dbus.py

   1 """Implementation for dbus.Bus. Not to be imported directly."""
   2
   3 # Copyright (C) 2003, 2004, 2005, 2006 Red Hat Inc. <http://www.redhat.com/>
   4 # Copyright (C) 2003 David Zeuthen
   5 # Copyright (C) 2004 Rob Taylor
   6 # Copyright (C) 2005, 2006 Collabora Ltd. <http://www.collabora.co.uk/>
   7 #
   8 # Licensed under the Academic Free License version 2.1
   9 #
  10 # This program is free software; you can redistribute it and/or modify
  11 # it under the terms of the GNU General Public License as published by
  12 # the Free Software Foundation; either version 2 of the License, or
  13 # (at your option) any later version.
  14 #
  15 # This program is distributed in the hope that it will be useful,
  16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 # GNU General Public License for more details.
  19 #
  20 # You should have received a copy of the GNU General Public License
  21 # along with this program; if not, write to the Free Software
  22 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  23
  24 from __future__ import generators
  25
  26 __all__ = ('Bus', 'SystemBus', 'SessionBus', 'StarterBus')
  27 __docformat__ = 'reStructuredText'
  28
  29 import _dbus_bindings
  30 UTF8String = _dbus_bindings.UTF8String
  31 DBusException = _dbus_bindings.DBusException
  32 BusImplementation = _dbus_bindings.BusImplementation
  33
  34 import os
  35 import logging
  36 import sys
  37 import weakref
  38 from traceback import print_exc
  39
  40 from dbus.proxies import ProxyObject, BUS_DAEMON_NAME, BUS_DAEMON_PATH, \
  41         BUS_DAEMON_IFACE
  42
  43 try:
  44     import thread
  45 except ImportError:
  46     import dummy_thread as thread
  47
  48 logger = logging.getLogger('dbus._dbus')
  49
  50 _NAME_OWNER_CHANGE_MATCH = ("type='signal',sender='%s',"
  51                             "interface='%s',member='NameOwnerChanged',"
  52                             "path='%s',arg0='%%s'"
  53                             % (BUS_DAEMON_NAME, BUS_DAEMON_IFACE,
  54                                BUS_DAEMON_PATH))
  55 """(_NAME_OWNER_CHANGE_MATCH % sender) matches relevant NameOwnerChange
  56 messages"""
  57
  58
  59 class SignalMatch(object):
  60     __slots__ = ('sender_unique', '_member', '_interface', '_sender',
  61                  '_path', '_handler', '_args_match', '_rule',
  62                  '_utf8_strings', '_byte_arrays', '_conn_weakref',
  63                  '_destination_keyword', '_interface_keyword',
  64                  '_message_keyword', '_member_keyword',
  65                  '_sender_keyword', '_path_keyword', '_int_args_match')
  66
  67     def __init__(self, conn, sender, object_path, dbus_interface,
  68                  member, handler, utf8_strings=False, byte_arrays=False,
  69                  sender_keyword=None, path_keyword=None,
  70                  interface_keyword=None, member_keyword=None,
  71                  message_keyword=None, destination_keyword=None,
  72                  **kwargs):
  73         if member is not None:
  74             _dbus_bindings.validate_member_name(member)
  75         if dbus_interface is not None:
  76             _dbus_bindings.validate_interface_name(dbus_interface)
  77         if sender is not None:
  78             _dbus_bindings.validate_bus_name(sender)
  79         if object_path is not None:
  80             _dbus_bindings.validate_object_path(object_path)
  81
  82         self._conn_weakref = weakref.ref(conn)
  83         self._sender = sender
  84         self._interface = dbus_interface
  85         self._member = member
  86         self._path = object_path
  87         self._handler = handler
  88         if (sender is not None and sender[:1] != ':'
  89             and sender != BUS_DAEMON_NAME):
  90             self.sender_unique = conn.get_object(BUS_DAEMON_NAME, BUS_DAEMON_PATH).GetNameOwner(sender, dbus_interface=BUS_DAEMON_IFACE)
  91         else:
  92             self.sender_unique = sender
  93         self._utf8_strings = utf8_strings
  94         self._byte_arrays = byte_arrays
  95         self._sender_keyword = sender_keyword
  96         self._path_keyword = path_keyword
  97         self._member_keyword = member_keyword
  98         self._interface_keyword = interface_keyword
  99         self._message_keyword = message_keyword
 100         self._destination_keyword = destination_keyword
 101
 102         self._args_match = kwargs
 103         if not kwargs:
 104             self._int_args_match = None
 105         else:
 106             self._int_args_match = {}
 107             for kwarg in kwargs:
 108                 if not kwarg.startswith('arg'):
 109                     raise TypeError('SignalMatch: unknown keyword argument %s'
 110                                     % kwarg)
 111                 try:
 112                     index = int(kwarg[3:])
 113                 except ValueError:
 114                     raise TypeError('SignalMatch: unknown keyword argument %s'
 115                                     % kwarg)
 116                 if index < 0 or index > 63:
 117                     raise TypeError('SignalMatch: arg match index must be in '
 118                                     'range(64), not %d' % index)
 119                 self._int_args_match[index] = kwargs[kwarg]
 120
 121         # we're always going to have to calculate the match rule for
 122         # the Bus's benefit, so this constructor might as well do the work
 123         rule = ["type='signal'"]
 124         if self._sender is not None:
 125             rule.append("sender='%s'" % self._sender)
 126         if self._path is not None:
 127             rule.append("path='%s'" % self._path)
 128         if self._interface is not None:
 129             rule.append("interface='%s'" % self._interface)
 130         if self._member is not None:
 131             rule.append("member='%s'" % self._member)
 132         for kwarg, value in kwargs.iteritems():
 133             rule.append("%s='%s'" % (kwarg, value))
 134
 135         self._rule = ','.join(rule)
 136
 137     def __str__(self):
 138         return self._rule
 139
 140     def __repr__(self):
 141         return ('<%s at %x "%s" on conn %r>'
 142                 % (self.__class__, id(self), self._rule, self._conn_weakref()))
 143
 144     def matches_removal_spec(self, sender, object_path,
 145                              dbus_interface, member, handler, **kwargs):
 146         if handler not in (None, self._handler):
 147             return False
 148         if sender != self._sender:
 149             return False
 150         if object_path != self._path:
 151             return False
 152         if dbus_interface != self._interface:
 153             return False
 154         if member != self._member:
 155             return False
 156         if kwargs != self._args_match:
 157             return False
 158         return True
 159
 160     def maybe_handle_message(self, message):
 161         args = None
 162
 163         # these haven't been checked yet by the match tree
 164         if self.sender_unique not in (None, message.get_sender()):
 165             return False
 166         if self._int_args_match is not None:
 167             # extracting args with utf8_strings and byte_arrays is less work
 168             args = message.get_args_list(utf8_strings=True, byte_arrays=True)
 169             for index, value in self._int_args_match.iteritems():
 170                 if (index >= len(args)
 171                     or not isinstance(args[index], UTF8String)
 172                     or args[index] != value):
 173                     return False
 174
 175         # these have likely already been checked by the match tree
 176         if self._member not in (None, message.get_member()):
 177             return False
 178         if self._interface not in (None, message.get_interface()):
 179             return False
 180         if self._path not in (None, message.get_path()):
 181             return False
 182
 183         try:
 184             # minor optimization: if we already extracted the args with the
 185             # right calling convention to do the args match, don't bother
 186             # doing so again
 187             if args is None or not self._utf8_strings or not self._byte_arrays:
 188                 args = message.get_args_list(utf8_strings=self._utf8_strings,
 189                                              byte_arrays=self._byte_arrays)
 190             kwargs = {}
 191             if self._sender_keyword is not None:
 192                 kwargs[self._sender_keyword] = message.get_sender()
 193             if self._destination_keyword is not None:
 194                 kwargs[self._destination_keyword] = message.get_destination()
 195             if self._path_keyword is not None:
 196                 kwargs[self._path_keyword] = message.get_path()
 197             if self._member_keyword is not None:
 198                 kwargs[self._member_keyword] = message.get_member()
 199             if self._interface_keyword is not None:
 200                 kwargs[self._interface_keyword] = message.get_interface()
 201             if self._message_keyword is not None:
 202                 kwargs[self._message_keyword] = message
 203             self._handler(*args, **kwargs)
 204         except:
 205             # FIXME: need to decide whether dbus-python uses logging, or
 206             # stderr, or what, and make it consistent
 207             sys.stderr.write('Exception in handler for D-Bus signal:\n')
 208             print_exc()
 209
 210         return True
 211
 212     def remove(self):
 213         #logger.debug('%r: removing', self)
 214         conn = self._conn_weakref()
 215         # do nothing if the connection has already vanished
 216         if conn is not None:
 217             #logger.debug('%r: removing from connection %r', self, conn)
 218             conn.remove_signal_receiver(self, self._member,
 219                                         self._interface, self._sender,
 220                                         self._path,
 221                                         **self._args_match)
 222
 223
 224 class Bus(BusImplementation):
 225     """A connection to a DBus daemon.
 226
 227     One of three possible standard buses, the SESSION, SYSTEM,
 228     or STARTER bus
 229     """
 230
 231     TYPE_SESSION    = _dbus_bindings.BUS_SESSION
 232     """Represents a session bus (same as the global dbus.BUS_SESSION)"""
 233
 234     TYPE_SYSTEM     = _dbus_bindings.BUS_SYSTEM
 235     """Represents the system bus (same as the global dbus.BUS_SYSTEM)"""
 236
 237     TYPE_STARTER = _dbus_bindings.BUS_STARTER
 238     """Represents the bus that started this service by activation (same as
 239     the global dbus.BUS_STARTER)"""
 240
 241     ProxyObjectClass = ProxyObject
 242
 243     START_REPLY_SUCCESS = _dbus_bindings.DBUS_START_REPLY_SUCCESS
 244     START_REPLY_ALREADY_RUNNING = _dbus_bindings.DBUS_START_REPLY_ALREADY_RUNNING
 245
 246     _shared_instances = {}
 247
 248     def __new__(cls, bus_type=TYPE_SESSION, private=False, mainloop=None):
 249         """Constructor, returning an existing instance where appropriate.
 250
 251         The returned instance is actually always an instance of `SessionBus`,
 252         `SystemBus` or `StarterBus`.
 253
 254         :Parameters:
 255             `bus_type` : cls.TYPE_SESSION, cls.TYPE_SYSTEM or cls.TYPE_STARTER
 256                 Connect to the appropriate bus
 257             `private` : bool
 258                 If true, never return an existing shared instance, but instead
 259                 return a private connection
 260             `mainloop` : dbus.mainloop.NativeMainLoop
 261                 The main loop to use. The default is to use the default
 262                 main loop if one has been set up, or raise an exception
 263                 if none has been.
 264         :ToDo:
 265             - There is currently no way to connect this class to a custom
 266               address.
 267             - Some of this functionality should be available on
 268               peer-to-peer D-Bus connections too.
 269         :Changed: in dbus-python 0.80:
 270             converted from a wrapper around a Connection to a Connection
 271             subclass.
 272         """
 273         if (not private and bus_type in cls._shared_instances):
 274             return cls._shared_instances[bus_type]
 275
 276         # this is a bit odd, but we create instances of the subtypes
 277         # so we can return the shared instances if someone tries to
 278         # construct one of them (otherwise we'd eg try and return an
 279         # instance of Bus from __new__ in SessionBus). why are there
 280         # three ways to construct this class? we just don't know.
 281         if bus_type == cls.TYPE_SESSION:
 282             subclass = SessionBus
 283         elif bus_type == cls.TYPE_SYSTEM:
 284             subclass = SystemBus
 285         elif bus_type == cls.TYPE_STARTER:
 286             subclass = StarterBus
 287         else:
 288             raise ValueError('invalid bus_type %s' % bus_type)
 289
 290         bus = _dbus_bindings.BusImplementation.__new__(subclass, bus_type,
 291                                                        mainloop=mainloop)
 292
 293         bus._bus_type = bus_type
 294         # _bus_names is used by dbus.service.BusName!
 295         bus._bus_names = weakref.WeakValueDictionary()
 296
 297         bus._signal_recipients_by_object_path = {}
 298         """Map from object path to dict mapping dbus_interface to dict
 299         mapping member to list of SignalMatch objects."""
 300
 301         bus._signal_sender_matches = {}
 302         """Map from sender well-known name to list of match rules for all
 303         signal handlers that match on sender well-known name."""
 304
 305         bus._signals_lock = thread.allocate_lock()
 306         """Lock used to protect signal data structures if doing two
 307         removals at the same time (everything else is atomic, thanks to
 308         the GIL)"""
 309
 310         bus.add_message_filter(bus.__class__._signal_func)
 311
 312         if not private:
 313             cls._shared_instances[bus_type] = bus
 314
 315         return bus
 316
 317     def close(self):
 318         t = self._bus_type
 319         if self.__class__._shared_instances[t] is self:
 320             del self.__class__._shared_instances[t]
 321         BusImplementation.close(self)
 322
 323     def get_connection(self):
 324         """(Deprecated - in new code, just use self)
 325
 326         Return self, for backwards compatibility with earlier dbus-python
 327         versions where Bus was not a subclass of Connection.
 328         """
 329         return self
 330     _connection = property(get_connection, None, None,
 331                            """self._connection == self, for backwards
 332                            compatibility with earlier dbus-python versions
 333                            where Bus was not a subclass of Connection.""")
 334
 335     def get_session(private=False):
 336         """Static method that returns a connection to the session bus.
 337
 338         :Parameters:
 339             `private` : bool
 340                 If true, do not return a shared connection.
 341         """
 342         return SessionBus(private=private)
 343
 344     get_session = staticmethod(get_session)
 345
 346     def get_system(private=False):
 347         """Static method that returns a connection to the system bus.
 348
 349         :Parameters:
 350             `private` : bool
 351                 If true, do not return a shared connection.
 352         """
 353         return SystemBus(private=private)
 354
 355     get_system = staticmethod(get_system)
 356
 357
 358     def get_starter(private=False):
 359         """Static method that returns a connection to the starter bus.
 360
 361         :Parameters:
 362             `private` : bool
 363                 If true, do not return a shared connection.
 364         """
 365         return StarterBus(private=private)
 366
 367     get_starter = staticmethod(get_starter)
 368
 369     def get_object(self, named_service, object_path, introspect=True,
 370                    follow_name_owner_changes=False):
 371         """Return a local proxy for the given remote object.
 372
 373         Method calls on the proxy are translated into method calls on the
 374         remote object.
 375
 376         :Parameters:
 377             `named_service` : str
 378                 A bus name (either the unique name or a well-known name)
 379                 of the application owning the object
 380             `object_path` : str
 381                 The object path of the desired object
 382             `introspect` : bool
 383                 If true (default), attempt to introspect the remote
 384                 object to find out supported methods and their signatures
 385             `follow_name_owner_changes` : bool
 386                 If the object path is a well-known name and this parameter
 387                 is false (default), resolve the well-known name to the unique
 388                 name of its current owner and bind to that instead; if the
 389                 ownership of the well-known name changes in future,
 390                 keep communicating with the original owner.
 391                 This is necessary if the D-Bus API used is stateful.
 392
 393                 If the object path is a well-known name and this parameter
 394                 is true, whenever the well-known name changes ownership in
 395                 future, bind to the new owner, if any.
 396
 397                 If the given object path is a unique name, this parameter
 398                 has no effect.
 399
 400         :Returns: a `dbus.proxies.ProxyObject`
 401         :Raises `DBusException`: if resolving the well-known name to a
 402             unique name fails
 403         """
 404         if follow_name_owner_changes:
 405             self._require_main_loop()   # we don't get the signals otherwise
 406         return self.ProxyObjectClass(self, named_service, object_path,
 407                                      introspect=introspect,
 408                                      follow_name_owner_changes=follow_name_owner_changes)
 409
 410     def add_signal_receiver(self, handler_function,
 411                                   signal_name=None,
 412                                   dbus_interface=None,
 413                                   named_service=None,
 414                                   path=None,
 415                                   **keywords):
 416         """Arrange for the given function to be called when a signal matching
 417         the parameters is received.
 418
 419         :Parameters:
 420             `handler_function` : callable
 421                 The function to be called. Its positional arguments will
 422                 be the arguments of the signal. By default it will receive
 423                 no keyword arguments, but see the description of
 424                 the optional keyword arguments below.
 425             `signal_name` : str
 426                 The signal name; None (the default) matches all names
 427             `dbus_interface` : str
 428                 The D-Bus interface name with which to qualify the signal;
 429                 None (the default) matches all interface names
 430             `named_service` : str
 431                 A bus name for the sender, which will be resolved to a
 432                 unique name if it is not already; None (the default) matches
 433                 any sender
 434             `path` : str
 435                 The object path of the object which must have emitted the
 436                 signal; None (the default) matches any object path
 437         :Keywords:
 438             `utf8_strings` : bool
 439                 If True, the handler function will receive any string
 440                 arguments as dbus.UTF8String objects (a subclass of str
 441                 guaranteed to be UTF-8). If False (default) it will receive
 442                 any string arguments as dbus.String objects (a subclass of
 443                 unicode).
 444             `byte_arrays` : bool
 445                 If True, the handler function will receive any byte-array
 446                 arguments as dbus.ByteArray objects (a subclass of str).
 447                 If False (default) it will receive any byte-array
 448                 arguments as a dbus.Array of dbus.Byte (subclasses of:
 449                 a list of ints).
 450             `sender_keyword` : str
 451                 If not None (the default), the handler function will receive
 452                 the unique name of the sending endpoint as a keyword
 453                 argument with this name.
 454             `destination_keyword` : str
 455                 If not None (the default), the handler function will receive
 456                 the bus name of the destination (or None if the signal is a
 457                 broadcast, as is usual) as a keyword argument with this name.
 458             `interface_keyword` : str
 459                 If not None (the default), the handler function will receive
 460                 the signal interface as a keyword argument with this name.
 461             `member_keyword` : str
 462                 If not None (the default), the handler function will receive
 463                 the signal name as a keyword argument with this name.
 464             `path_keyword` : str
 465                 If not None (the default), the handler function will receive
 466                 the object-path of the sending object as a keyword argument
 467                 with this name.
 468             `message_keyword` : str
 469                 If not None (the default), the handler function will receive
 470                 the `dbus.lowlevel.SignalMessage` as a keyword argument with
 471                 this name.
 472             `arg...` : unicode or UTF-8 str
 473                 If there are additional keyword parameters of the form
 474                 ``arg``\ *n*, match only signals where the *n*\ th argument
 475                 is the value given for that keyword parameter. As of this
 476                 time only string arguments can be matched (in particular,
 477                 object paths and signatures can't).
 478         """
 479         self._require_main_loop()
 480
 481         match = SignalMatch(self, named_service, path, dbus_interface,
 482                             signal_name, handler_function, **keywords)
 483         by_interface = self._signal_recipients_by_object_path.setdefault(path,
 484                                                                          {})
 485         by_member = by_interface.setdefault(dbus_interface, {})
 486         matches = by_member.setdefault(signal_name, [])
 487         # The bus daemon is special - its unique-name is org.freedesktop.DBus
 488         # rather than starting with :
 489         if (named_service is not None and named_service[:1] != ':'
 490             and named_service != BUS_DAEMON_NAME):
 491             notification = self._signal_sender_matches.setdefault(named_service,
 492                                                                   [])
 493             if not notification:
 494                 self.add_match_string(_NAME_OWNER_CHANGE_MATCH % named_service)
 495             notification.append(match)
 496         # make sure nobody is currently manipulating the list
 497         self._signals_lock.acquire()
 498         try:
 499             matches.append(match)
 500         finally:
 501             self._signals_lock.release()
 502         self.add_match_string(str(match))
 503         return match
 504
 505     def _iter_easy_matches(self, path, dbus_interface, member):
 506         if path is not None:
 507             path_keys = (None, path)
 508         else:
 509             path_keys = (None,)
 510         if dbus_interface is not None:
 511             interface_keys = (None, dbus_interface)
 512         else:
 513             interface_keys = (None,)
 514         if member is not None:
 515             member_keys = (None, member)
 516         else:
 517             member_keys = (None,)
 518
 519         for path in path_keys:
 520             by_interface = self._signal_recipients_by_object_path.get(path,
 521                                                                       None)
 522             if by_interface is None:
 523                 continue
 524             for dbus_interface in interface_keys:
 525                 by_member = by_interface.get(dbus_interface, None)
 526                 if by_member is None:
 527                     continue
 528                 for member in member_keys:
 529                     matches = by_member.get(member, None)
 530                     if matches is None:
 531                         continue
 532                     for m in matches:
 533                         yield m
 534
 535     def _remove_name_owner_changed_for_match(self, named_service, match):
 536         notification = self._signal_sender_matches.get(named_service, False)
 537         if notification:
 538             try:
 539                 notification.remove(match)
 540             except LookupError:
 541                 pass
 542             if not notification:
 543                 self.remove_match_string(_NAME_OWNER_CHANGE_MATCH
 544                                          % named_service)
 545
 546     def remove_signal_receiver(self, handler_or_match,
 547                                signal_name=None,
 548                                dbus_interface=None,
 549                                named_service=None,
 550                                path=None,
 551                                **keywords):
 552         #logger.debug('%r: removing signal receiver %r: member=%s, '
 553                      #'iface=%s, sender=%s, path=%s, kwargs=%r',
 554                      #self, handler_or_match, signal_name,
 555                      #dbus_interface, named_service, path, keywords)
 556         #logger.debug('%r', self._signal_recipients_by_object_path)
 557         by_interface = self._signal_recipients_by_object_path.get(path, None)
 558         if by_interface is None:
 559             return
 560         by_member = by_interface.get(dbus_interface, None)
 561         if by_member is None:
 562             return
 563         matches = by_member.get(signal_name, None)
 564         if matches is None:
 565             return
 566         self._signals_lock.acquire()
 567         #logger.debug(matches)
 568         try:
 569             new = []
 570             for match in matches:
 571                 if (handler_or_match is match
 572                     or match.matches_removal_spec(named_service,
 573                                                   path,
 574                                                   dbus_interface,
 575                                                   signal_name,
 576                                                   handler_or_match,
 577                                                   **keywords)):
 578                     #logger.debug('Removing match string: %s', match)
 579                     self.remove_match_string(str(match))
 580                     self._remove_name_owner_changed_for_match(named_service,
 581                                                               match)
 582                 else:
 583                     new.append(match)
 584             by_member[signal_name] = new
 585         finally:
 586             self._signals_lock.release()
 587
 588     def _signal_func(self, message):
 589         """D-Bus filter function. Handle signals by dispatching to Python
 590         callbacks kept in the match-rule tree.
 591         """
 592
 593         #logger.debug('Incoming message %r with args %r', message,
 594                      #message.get_args_list())
 595
 596         if (message.get_type() != _dbus_bindings.MESSAGE_TYPE_SIGNAL):
 597             return _dbus_bindings.HANDLER_RESULT_NOT_YET_HANDLED
 598
 599         # If it's NameOwnerChanged, we'll need to update our
 600         # sender well-known name -> sender unique name mappings
 601         if (message.is_signal(BUS_DAEMON_IFACE, 'NameOwnerChanged')
 602             and message.has_sender(BUS_DAEMON_NAME)
 603             and message.has_path(BUS_DAEMON_PATH)):
 604                 name, unused, new = message.get_args_list()
 605                 for match in self._signal_sender_matches.get(name, (None,))[1:]:
 606                     match.sender_unique = new
 607
 608         # See if anyone else wants to know
 609         dbus_interface = message.get_interface()
 610         path = message.get_path()
 611         signal_name = message.get_member()
 612
 613         ret = _dbus_bindings.HANDLER_RESULT_NOT_YET_HANDLED
 614         for match in self._iter_easy_matches(path, dbus_interface,
 615                                              signal_name):
 616             if match.maybe_handle_message(message):
 617                 ret = _dbus_bindings.HANDLER_RESULT_HANDLED
 618         return ret
 619
 620     def __repr__(self):
 621         if self._bus_type == self.TYPE_SESSION:
 622             name = 'SESSION'
 623         elif self._bus_type == self.TYPE_SYSTEM:
 624             name = 'SYSTEM'
 625         elif self._bus_type == self.TYPE_STARTER:
 626             name = 'STARTER'
 627         else:
 628             raise AssertionError('Unable to represent unknown bus type.')
 629
 630         return '<dbus.Bus on %s at %#x>' % (name, id(self))
 631     __str__ = __repr__
 632
 633
 634 # FIXME: Drop the subclasses here? I can't think why we'd ever want
 635 # polymorphism
 636 class SystemBus(Bus):
 637     """The system-wide message bus."""
 638     def __new__(cls, private=False, mainloop=None):
 639         """Return a connection to the system bus.
 640
 641         :Parameters:
 642             `private` : bool
 643                 If true, never return an existing shared instance, but instead
 644                 return a private connection.
 645             `mainloop` : dbus.mainloop.NativeMainLoop
 646                 The main loop to use. The default is to use the default
 647                 main loop if one has been set up, or raise an exception
 648                 if none has been.
 649         """
 650         return Bus.__new__(cls, Bus.TYPE_SYSTEM, mainloop=mainloop,
 651                            private=private)
 652
 653 class SessionBus(Bus):
 654     """The session (current login) message bus."""
 655     def __new__(cls, private=False, mainloop=None):
 656         """Return a connection to the session bus.
 657
 658         :Parameters:
 659             `private` : bool
 660                 If true, never return an existing shared instance, but instead
 661                 return a private connection.
 662             `mainloop` : dbus.mainloop.NativeMainLoop
 663                 The main loop to use. The default is to use the default
 664                 main loop if one has been set up, or raise an exception
 665                 if none has been.
 666         """
 667         return Bus.__new__(cls, Bus.TYPE_SESSION, private=private,
 668                            mainloop=mainloop)
 669
 670 class StarterBus(Bus):
 671     """The bus that activated this process (only valid if
 672     this process was launched by DBus activation).
 673     """
 674     def __new__(cls, private=False, mainloop=None):
 675         """Return a connection to the bus that activated this process.
 676
 677         :Parameters:
 678             `private` : bool
 679                 If true, never return an existing shared instance, but instead
 680                 return a private connection.
 681             `mainloop` : dbus.mainloop.NativeMainLoop
 682                 The main loop to use. The default is to use the default
 683                 main loop if one has been set up, or raise an exception
 684                 if none has been.
 685         """
 686         return Bus.__new__(cls, Bus.TYPE_STARTER, private=private,
 687                            mainloop=mainloop)
 688
 689
 690 _dbus_bindings_warning = DeprecationWarning("""\
 691 The dbus_bindings module is deprecated and will go away soon.
 692
 693 dbus-python 0.80 provides only a partial emulation of the old
 694 dbus_bindings, which was never meant to be public API.
 695
 696 Most uses of dbus_bindings are applications catching the exception
 697 dbus.dbus_bindings.DBusException. You should use dbus.DBusException
 698 instead (this is compatible with all dbus-python versions since 0.40.2).
 699
 700 If you need additional public API, please contact the maintainers via
 701 <dbus@lists.freedesktop.org>.
 702 """)
 703
 704 if 'DBUS_PYTHON_NO_DEPRECATED' not in os.environ:
 705
 706     class _DBusBindingsEmulation:
 707         """A partial emulation of the dbus_bindings module."""
 708         _module = None
 709         def __str__(self):
 710             return '_DBusBindingsEmulation()'
 711         def __repr__(self):
 712             return '_DBusBindingsEmulation()'
 713         def __getattr__(self, attr):
 714             if self._module is None:
 715                 from warnings import warn as _warn
 716                 _warn(_dbus_bindings_warning, DeprecationWarning, stacklevel=2)
 717
 718                 import dbus.dbus_bindings as m
 719                 self._module = m
 720             return getattr(self._module, attr)
 721
 722     dbus_bindings = _DBusBindingsEmulation()
 723     """Deprecated, don't use."""