Deprecate all arguments called named_service; use bus_name instead

3 files changed, 137 insertions, 39 deletions

diff --git a/dbus/bus.py b/dbus/bus.py
index f5eeaf8..80118aa 100644
--- a/dbus/bus.py
+++ b/dbus/bus.py
@@ -115,18 +115,29 @@ class BusConnection(Connection):
         return bus
 
     def add_signal_receiver(self, handler_function, signal_name=None,
-                            dbus_interface=None, named_service=None,
+                            dbus_interface=None, bus_name=None,
                             path=None, **keywords):
+        named_service = keywords.pop('named_service', None)
+        if named_service is not None:
+            if bus_name is not None:
+                raise TypeError('bus_name and named_service cannot both be '
+                                'specified')
+            bus_name = named_service
+            from warnings import warn
+            warn('Passing the named_service parameter to add_signal_receiver '
+                 'by name is deprecated: please use positional parameters',
+                 DeprecationWarning, stacklevel=2)
+
         match = super(BusConnection, self).add_signal_receiver(
-                handler_function, signal_name, dbus_interface, named_service,
+                handler_function, signal_name, dbus_interface, bus_name,
                 path, **keywords)
 
         # The bus daemon is special - its unique-name is org.freedesktop.DBus
         # rather than starting with :
-        if (named_service is not None
-            and named_service[:1] != ':'
-            and named_service != BUS_DAEMON_NAME):
-            watch = self.watch_name_owner(named_service,
+        if (bus_name is not None
+            and bus_name[:1] != ':'
+            and bus_name != BUS_DAEMON_NAME):
+            watch = self.watch_name_owner(bus_name,
                                           match.set_sender_name_owner)
             self._signal_sender_matches[match] = watch
 
@@ -157,17 +168,18 @@ class BusConnection(Connection):
             # already unique
             return bus_name
 
-    def get_object(self, named_service, object_path, introspect=True,
-                   follow_name_owner_changes=False):
+    def get_object(self, bus_name, object_path, introspect=True,
+                   follow_name_owner_changes=False, **kwargs):
         """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
+            `bus_name` : str
                 A bus name (either the unique name or a well-known name)
-                of the application owning the object
+                of the application owning the object. The keyword argument
+                named_service is a deprecated alias for this.
             `object_path` : str
                 The object path of the desired object
             `introspect` : bool
@@ -194,7 +206,22 @@ class BusConnection(Connection):
         """
         if follow_name_owner_changes:
             self._require_main_loop()   # we don't get the signals otherwise
-        return self.ProxyObjectClass(self, named_service, object_path,
+
+        named_service = kwargs.pop('named_service', None)
+        if named_service is not None:
+            if bus_name is not None:
+                raise TypeError('bus_name and named_service cannot both '
+                                'be specified')
+            from warnings import warn
+            warn('Passing the named_service parameter to get_object by name '
+                 'is deprecated: please use positional parameters',
+                 DeprecationWarning, stacklevel=2)
+            bus_name = named_service
+        if kwargs:
+            raise TypeError('get_object does not take these keyword '
+                            'arguments: %s' % ', '.join(kwargs.iterkeys()))
+
+        return self.ProxyObjectClass(self, bus_name, object_path,
                                      introspect=introspect,
                                      follow_name_owner_changes=follow_name_owner_changes)
 
diff --git a/dbus/connection.py b/dbus/connection.py
index c2bd110..fd0fe7a 100644
--- a/dbus/connection.py
+++ b/dbus/connection.py
@@ -265,16 +265,18 @@ class Connection(_Connection):
         """
         return bus_name
 
-    def get_object(self, named_service, object_path, introspect=True):
+    def get_object(self, bus_name=None, object_path=None, introspect=True,
+                   **kwargs):
         """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
+            `bus_name` : str
                 A bus name (either the unique name or a well-known name)
-                of the application owning the object
+                of the application owning the object. The keyword argument
+                named_service is a deprecated alias for this.
             `object_path` : str
                 The object path of the desired object
             `introspect` : bool
@@ -283,13 +285,27 @@ class Connection(_Connection):
 
         :Returns: a `dbus.proxies.ProxyObject`
         """
-        return self.ProxyObjectClass(self, named_service, object_path,
+        named_service = kwargs.pop('named_service', None)
+        if named_service is not None:
+            if bus_name is not None:
+                raise TypeError('bus_name and named_service cannot both '
+                                'be specified')
+            from warnings import warn
+            warn('Passing the named_service parameter to get_object by name '
+                 'is deprecated: please use positional parameters',
+                 DeprecationWarning, stacklevel=2)
+            bus_name = named_service
+        if kwargs:
+            raise TypeError('get_object does not take these keyword '
+                            'arguments: %s' % ', '.join(kwargs.iterkeys()))
+
+        return self.ProxyObjectClass(self, bus_name, object_path,
                                      introspect=introspect)
 
     def add_signal_receiver(self, handler_function,
                                   signal_name=None,
                                   dbus_interface=None,
-                                  named_service=None,
+                                  bus_name=None,
                                   path=None,
                                   **keywords):
         """Arrange for the given function to be called when a signal matching
@@ -306,10 +322,10 @@ class Connection(_Connection):
             `dbus_interface` : str
                 The D-Bus interface name with which to qualify the signal;
                 None (the default) matches all interface names
-            `named_service` : str
+            `bus_name` : str
                 A bus name for the sender, which will be resolved to a
                 unique name if it is not already; None (the default) matches
-                any sender
+                any sender.
             `path` : str
                 The object path of the object which must have emitted the
                 signal; None (the default) matches any object path
@@ -354,10 +370,23 @@ class Connection(_Connection):
                 is the value given for that keyword parameter. As of this
                 time only string arguments can be matched (in particular,
                 object paths and signatures can't).
+            `named_service` : str
+                A deprecated alias for `bus_name`.
         """
         self._require_main_loop()
 
-        match = SignalMatch(self, named_service, path, dbus_interface,
+        named_service = keywords.pop('named_service', None)
+        if named_service is not None:
+            if bus_name is not None:
+                raise TypeError('bus_name and named_service cannot both be '
+                                'specified')
+            bus_name = named_service
+            from warnings import warn
+            warn('Passing the named_service parameter to add_signal_receiver '
+                 'by name is deprecated: please use positional parameters',
+                 DeprecationWarning, stacklevel=2)
+
+        match = SignalMatch(self, bus_name, path, dbus_interface,
                             signal_name, handler_function, **keywords)
         by_interface = self._signal_recipients_by_object_path.setdefault(path,
                                                                          {})
@@ -405,9 +434,21 @@ class Connection(_Connection):
     def remove_signal_receiver(self, handler_or_match,
                                signal_name=None,
                                dbus_interface=None,
-                               named_service=None,
+                               bus_name=None,
                                path=None,
                                **keywords):
+        named_service = keywords.pop('named_service', None)
+        if named_service is not None:
+            if bus_name is not None:
+                raise TypeError('bus_name and named_service cannot both be '
+                                'specified')
+            bus_name = named_service
+            from warnings import warn
+            warn('Passing the named_service parameter to '
+                 'remove_signal_receiver by name is deprecated: please use '
+                 'positional parameters',
+                 DeprecationWarning, stacklevel=2)
+
         by_interface = self._signal_recipients_by_object_path.get(path, None)
         if by_interface is None:
             return
@@ -422,7 +463,7 @@ class Connection(_Connection):
             new = []
             for match in matches:
                 if (handler_or_match is match
-                    or match.matches_removal_spec(named_service,
+                    or match.matches_removal_spec(bus_name,
                                                   path,
                                                   dbus_interface,
                                                   signal_name,
diff --git a/dbus/proxies.py b/dbus/proxies.py
index 5934b56..354e3b7 100644
--- a/dbus/proxies.py
+++ b/dbus/proxies.py
@@ -73,7 +73,8 @@ class _ProxyMethod:
     method produce messages that travel over the Bus and are routed
     to a specific named Service.
     """
-    def __init__(self, proxy, connection, named_service, object_path, method_name, iface):
+    def __init__(self, proxy, connection, bus_name, object_path, method_name,
+                 iface):
         if object_path == LOCAL_PATH:
             raise DBusException('Methods may not be called on the reserved '
                                 'path %s' % LOCAL_PATH)
@@ -81,7 +82,7 @@ class _ProxyMethod:
         # trust that the proxy, and the properties it had, are OK
         self._proxy          = proxy
         self._connection     = connection
-        self._named_service  = named_service
+        self._named_service  = bus_name
         self._object_path    = object_path
         # fail early if the method name is bad
         _dbus_bindings.validate_member_name(method_name)
@@ -169,41 +170,70 @@ class ProxyObject(object):
     INTROSPECT_STATE_INTROSPECT_IN_PROGRESS = 1
     INTROSPECT_STATE_INTROSPECT_DONE = 2
 
-    def __init__(self, bus, named_service, object_path, introspect=True,
-                 follow_name_owner_changes=False):
+    def __init__(self, conn=None, bus_name=None, object_path=None,
+                 introspect=True, follow_name_owner_changes=False, **kwargs):
         """Initialize the proxy object.
 
         :Parameters:
-            `bus` : `dbus.Bus`
-                The bus on which to find this object
-            `named_service` : str
-                A bus name for the endpoint owning the object (need not
-                actually be a service name)
+            `conn` : `dbus.connection.Connection`
+                The bus or connection on which to find this object.
+                The keyword argument `bus` is a deprecated alias for this.
+            `bus_name` : str
+                A bus name for the application owning the object, to be used
+                as the destination for method calls and the sender for
+                signal matches. The keyword argument `named_service` is a
+                deprecated alias for this.
             `object_path` : str
-                The object path at which the endpoint exports the object
+                The object path at which the application exports the 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 true (default is false) and the `named_service` is a
+                If true (default is false) and the `bus_name` is a
                 well-known name, follow ownership changes for that name
         """
+        bus = kwargs.pop('bus', None)
+        if bus is not None:
+            if conn is not None:
+                raise TypeError('conn and bus cannot both be specified')
+            conn = bus
+            from warnings import warn
+            warn('Passing the bus parameter to ProxyObject by name is '
+                 'deprecated: please use positional parameters',
+                 DeprecationWarning, stacklevel=2)
+        named_service = kwargs.pop('named_service', None)
+        if named_service is not None:
+            if bus_name is not None:
+                raise TypeError('bus_name and named_service cannot both be '
+                                'specified')
+            bus_name = named_service
+            from warnings import warn
+            warn('Passing the named_service parameter to ProxyObject by name '
+                 'is deprecated: please use positional parameters',
+                 DeprecationWarning, stacklevel=2)
+        if kwargs:
+            raise TypeError('ProxyObject.__init__ does not take these '
+                            'keyword arguments: %s'
+                            % ', '.join(kwargs.iterkeys()))
+
         if follow_name_owner_changes:
             # we don't get the signals unless the Bus has a main loop
             # XXX: using Bus internals
-            bus._require_main_loop()
+            conn._require_main_loop()
 
-        self._bus           = bus
+        self._bus = conn
 
-        if named_service is not None:
-            _dbus_bindings.validate_bus_name(named_service)
-        self._named_service = self._requested_bus_name = named_service
+        if bus_name is not None:
+            _dbus_bindings.validate_bus_name(bus_name)
+        # the attribute is still called _named_service for the moment,
+        # for the benefit of telepathy-python
+        self._named_service = self._requested_bus_name = bus_name
 
         _dbus_bindings.validate_object_path(object_path)
         self.__dbus_object_path__ = object_path
 
         if not follow_name_owner_changes:
-            self._named_service = bus.activate_name_owner(named_service)
+            self._named_service = conn.activate_name_owner(bus_name)
 
         #PendingCall object for Introspect call
         self._pending_introspect = None
@@ -322,7 +352,7 @@ class ProxyObject(object):
         self._bus.add_signal_receiver(handler_function,
                                       signal_name=signal_name,
                                       dbus_interface=dbus_interface,
-                                      named_service=self._named_service,
+                                      bus_name=self._named_service,
                                       path=self.__dbus_object_path__,
                                       **keywords)