make DriverManager callable

Signed-off-by: Doug Hellmann <doug.hellmann@dreamhost.com>

announce.rst

@@ -27,6 +27,8 @@ What's New?
 
  - Added dispatch managers for selecting among a set of plugins at
    runtime instead of load time.
+ - Added ``__call__`` method to ``DriverManager`` so it can be invoked
+   in a more natural fashion for a single plugin.
 
 Installing
 ==========

docs/source/history.rst

@@ -6,6 +6,9 @@
 
   - Added dispatch managers for selecting among a set of plugins at
     runtime instead of load time.
+  - Added ``__call__`` method to
+    :class:`~stevedore.driver.DriverManager` so it can be invoked in a
+    more natural fashion for a single plugin.
 
 0.2
 

docs/source/managers.rst

@@ -8,6 +8,7 @@ DriverManager
 .. autoclass:: stevedore.driver.DriverManager
    :members:
    :show-inheritance:
+   :special-members:
 
 HookManager
 ===========

stevedore/driver.py

@@ -38,3 +38,25 @@ class DriverManager(HookManager):
                                 ','.join('%s:%s' % (e.module_name, e.attrs[0])
                                          for e in self.extensions))
                                )
+
+    def __call__(self, func, *args, **kwds):
+        """Invokes func() for the single loaded extension.
+
+        The signature for func() should be::
+
+            def func(ext, *args, **kwds):
+                pass
+
+        The first argument to func(), 'ext', is the
+        :class:`~stevedore.extension.Extension` instance.
+
+        Exceptions raised from within func() are logged and ignored.
+
+        :param func: Callable to invoke for each extension.
+        :param args: Variable arguments to pass to func()
+        :param kwds: Keyword arguments to pass to func()
+        :returns: List of values returned from func()
+        """
+        results = self.map(func, *args, **kwds)
+        if results:
+            return results[0]

stevedore/extension.py

@@ -17,7 +17,7 @@ class Extension(object):
     :param entry_point: The EntryPoint instance returned by :mod:`pkg_resources`.
     :type entry_point: EntryPoint
     :param plugin: The value returned by entry_point.load()
-    :param obj: The object returned by plugin(*args, **kwds) if the
+    :param obj: The object returned by ``plugin(*args, **kwds)`` if the
                 manager invoked the extension on load.
     """
 

stevedore/tests/test_driver.py

@@ -10,6 +10,14 @@ def test_detect_plugins():
     assert names == ['t1']
 
 
+def test_call():
+    def invoke(ext, *args, **kwds):
+        return (ext.name, args, kwds)
+    em = driver.DriverManager('stevedore.test.extension', 't1')
+    result = em(invoke, 'a', b='C')
+    assert result == ('t1', ('a',), {'b': 'C'})
+
+
 def test_no_drivers():
     try:
         driver.DriverManager('stevedore.test.extension.none', 't1')