[PATCH 12/17] Move get_object,
constants into Connection and BusConnection. Add docstrings
Simon McVittie
simon.mcvittie at collabora.co.uk
Mon Apr 30 04:36:37 PDT 2007
diff --git a/dbus/_dbus.py b/dbus/_dbus.py
index 48c623b..bab195a 100644
--- a/dbus/_dbus.py
+++ b/dbus/_dbus.py
@@ -227,30 +227,21 @@ class SignalMatch(object):
class Bus(BusConnection):
- """A connection to a DBus daemon.
+ """A connection to one of three possible standard buses, the SESSION,
+ SYSTEM, or STARTER bus. This class manages shared connections to those
+ buses.
- One of three possible standard buses, the SESSION, SYSTEM,
- or STARTER bus
+ If you're trying to subclass `Bus`, you may be better off subclassing
+ `BusConnection`, which doesn't have all this magic.
"""
- TYPE_SESSION = BUS_SESSION
- """Represents a session bus (same as the global dbus.BUS_SESSION)"""
-
- TYPE_SYSTEM = BUS_SYSTEM
- """Represents the system bus (same as the global dbus.BUS_SYSTEM)"""
-
- TYPE_STARTER = BUS_STARTER
- """Represents the bus that started this service by activation (same as
- the global dbus.BUS_STARTER)"""
-
- ProxyObjectClass = ProxyObject
-
START_REPLY_SUCCESS = DBUS_START_REPLY_SUCCESS
START_REPLY_ALREADY_RUNNING = DBUS_START_REPLY_ALREADY_RUNNING
_shared_instances = {}
- def __new__(cls, bus_type=TYPE_SESSION, private=False, mainloop=None):
+ def __new__(cls, bus_type=BusConnection.TYPE_SESSION, private=False,
+ mainloop=None):
"""Constructor, returning an existing instance where appropriate.
The returned instance is actually always an instance of `SessionBus`,
@@ -370,47 +361,6 @@ class Bus(BusConnection):
get_starter = staticmethod(get_starter)
- def get_object(self, named_service, object_path, introspect=True,
- follow_name_owner_changes=False):
- """Return a local proxy for the given remote object.
-
- Method calls on the proxy are translated into method calls on the
- remote object.
-
- :Parameters:
- `named_service` : str
- A bus name (either the unique name or a well-known name)
- of the application owning the object
- `object_path` : str
- The object path of the desired object
- `introspect` : bool
- If true (default), attempt to introspect the remote
- object to find out supported methods and their signatures
- `follow_name_owner_changes` : bool
- If the object path is a well-known name and this parameter
- is false (default), resolve the well-known name to the unique
- name of its current owner and bind to that instead; if the
- ownership of the well-known name changes in future,
- keep communicating with the original owner.
- This is necessary if the D-Bus API used is stateful.
-
- If the object path is a well-known name and this parameter
- is true, whenever the well-known name changes ownership in
- future, bind to the new owner, if any.
-
- If the given object path is a unique name, this parameter
- has no effect.
-
- :Returns: a `dbus.proxies.ProxyObject`
- :Raises `DBusException`: if resolving the well-known name to a
- unique name fails
- """
- if follow_name_owner_changes:
- self._require_main_loop() # we don't get the signals otherwise
- return self.ProxyObjectClass(self, named_service, object_path,
- introspect=introspect,
- follow_name_owner_changes=follow_name_owner_changes)
-
def add_signal_receiver(self, handler_function,
signal_name=None,
dbus_interface=None,
diff --git a/dbus/bus.py b/dbus/bus.py
index e5356d2..45c8505 100644
--- a/dbus/bus.py
+++ b/dbus/bus.py
@@ -16,20 +16,33 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+__all__ = ('BusConnection',)
+__docformat__ = 'reStructuredText'
+
from _dbus_bindings import validate_interface_name, validate_member_name,\
validate_bus_name, validate_object_path,\
validate_error_name,\
DBusException, \
+ BUS_SESSION, BUS_STARTER, BUS_SYSTEM, \
BUS_DAEMON_NAME, BUS_DAEMON_PATH, BUS_DAEMON_IFACE
from dbus.connection import Connection
class BusConnection(Connection):
- """This mixin provides simple blocking wrappers for various methods on
- the org.freedesktop.DBus bus-daemon object, to reduce the amount of C
- code we need.
+ """A connection to a D-Bus daemon that implements the
+ ``org.freedesktop.DBus`` pseudo-service.
"""
+ TYPE_SESSION = BUS_SESSION
+ """Represents a session bus (same as the global dbus.BUS_SESSION)"""
+
+ TYPE_SYSTEM = BUS_SYSTEM
+ """Represents the system bus (same as the global dbus.BUS_SYSTEM)"""
+
+ TYPE_STARTER = BUS_STARTER
+ """Represents the bus that started this service by activation (same as
+ the global dbus.BUS_STARTER)"""
+
def activate_name_owner(self, bus_name):
if (bus_name is not None and bus_name[:1] != ':'
and bus_name != BUS_DAEMON_NAME):
@@ -46,6 +59,47 @@ class BusConnection(Connection):
# already unique
return bus_name
+ def get_object(self, named_service, object_path, introspect=True,
+ follow_name_owner_changes=False):
+ """Return a local proxy for the given remote object.
+
+ Method calls on the proxy are translated into method calls on the
+ remote object.
+
+ :Parameters:
+ `named_service` : str
+ A bus name (either the unique name or a well-known name)
+ of the application owning the object
+ `object_path` : str
+ The object path of the desired object
+ `introspect` : bool
+ If true (default), attempt to introspect the remote
+ object to find out supported methods and their signatures
+ `follow_name_owner_changes` : bool
+ If the object path is a well-known name and this parameter
+ is false (default), resolve the well-known name to the unique
+ name of its current owner and bind to that instead; if the
+ ownership of the well-known name changes in future,
+ keep communicating with the original owner.
+ This is necessary if the D-Bus API used is stateful.
+
+ If the object path is a well-known name and this parameter
+ is true, whenever the well-known name changes ownership in
+ future, bind to the new owner, if any.
+
+ If the given object path is a unique name, this parameter
+ has no effect.
+
+ :Returns: a `dbus.proxies.ProxyObject`
+ :Raises `DBusException`: if resolving the well-known name to a
+ unique name fails
+ """
+ if follow_name_owner_changes:
+ self._require_main_loop() # we don't get the signals otherwise
+ return self.ProxyObjectClass(self, named_service, object_path,
+ introspect=introspect,
+ follow_name_owner_changes=follow_name_owner_changes)
+
def get_unix_user(self, bus_name):
"""Get the numeric uid of the process owning the given bus name.
diff --git a/dbus/connection.py b/dbus/connection.py
index b78e221..1de5ec4 100644
--- a/dbus/connection.py
+++ b/dbus/connection.py
@@ -16,11 +16,15 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+__all__ = ('Connection',)
+__docformat__ = 'reStructuredText'
+
import logging
from _dbus_bindings import Connection as _Connection, ErrorMessage, \
MethodCallMessage, MethodReturnMessage, \
DBusException, LOCAL_PATH, LOCAL_IFACE
+from dbus.proxies import ProxyObject
_logger = logging.getLogger('dbus.methods')
@@ -31,6 +35,32 @@ def _noop(*args, **kwargs):
class Connection(_Connection):
+ """A connection to another application. In this base class there is
+ assumed to be no bus daemon.
+ """
+
+ ProxyObjectClass = ProxyObject
+
+ def get_object(self, named_service, object_path, introspect=True):
+ """Return a local proxy for the given remote object.
+
+ Method calls on the proxy are translated into method calls on the
+ remote object.
+
+ :Parameters:
+ `named_service` : str
+ A bus name (either the unique name or a well-known name)
+ of the application owning the object
+ `object_path` : str
+ The object path of the desired object
+ `introspect` : bool
+ If true (default), attempt to introspect the remote
+ object to find out supported methods and their signatures
+
+ :Returns: a `dbus.proxies.ProxyObject`
+ """
+ return self.ProxyObjectClass(self, named_service, object_path,
+ introspect=introspect)
def activate_name_owner(self, bus_name):
"""Return the unique name for the given bus name, activating it
More information about the dbus
mailing list