Browse files

add API documentation

  • Loading branch information...
1 parent 9a47b1c commit 2e7e0ab61e943b6e346353ee6161c1908c30e1c0 @dhellmann dhellmann committed Jul 22, 2012
Showing with 139 additions and 4 deletions.
  1. +1 −0 docs/source/index.rst
  2. +40 −0 docs/source/managers.rst
  3. +2 −2 run_sphinx
  4. +16 −0 stevedore/driver.py
  5. +20 −0 stevedore/enabled.py
  6. +27 −1 stevedore/extension.py
  7. +17 −1 stevedore/hook.py
  8. +16 −0 stevedore/named.py
View
1 docs/source/index.rst
@@ -18,6 +18,7 @@ Contents:
patterns_loading
patterns_enabling
+ managers
history
.. _setuptools entry points: http://packages.python.org/distribute/pkg_resources.html#convenience-api
View
40 docs/source/managers.rst
@@ -0,0 +1,40 @@
+===========================
+ Extension Manager Classes
+===========================
+
+DriverManager
+=============
+
+.. autoclass:: stevedore.driver.DriverManager
+ :members:
+
+HookManager
+===========
+
+.. autoclass:: stevedore.hook.HookManager
+ :members:
+
+NamedExtensionManager
+=====================
+
+.. autoclass:: stevedore.named.NamedExtensionManager
+ :members:
+
+EnabledExtensionManager
+=======================
+
+.. autoclass:: stevedore.enabled.EnabledExtensionManager
+ :members:
+
+ExtensionManager
+================
+
+.. autoclass:: stevedore.extension.ExtensionManager
+ :members:
+
+Extension
+=========
+
+.. autoclass:: stevedore.extension.Extension
+ :members:
+
View
4 run_sphinx
@@ -4,7 +4,7 @@
set -x
watchmedo shell-command \
- --patterns='*.rst' \
- --ignore-pattern='docs/build/*' \
+ --patterns='*.rst;*.py' \
+ --ignore-pattern='docs/build/*;*flymake*' \
--recursive \
--command='python setup.py build_sphinx'
View
16 stevedore/driver.py
@@ -3,6 +3,22 @@
class DriverManager(HookManager):
"""Load a single plugin with a given name from the namespace.
+
+ :param namespace: The namespace for the entry points.
+ :type namespace: str
+ :param name: The name of the driver to load.
+ :type name: str
+ :param invoke_on_load: Boolean controlling whether to invoke the
+ object returned by the entry point after the driver is loaded.
+ :type invoke_on_load: bool
+ :param invoke_args: Positional arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_args: tuple
+ :param invoke_kwds: Named arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_kwds: dict
"""
def __init__(self, namespace, name,
View
20 stevedore/enabled.py
@@ -3,6 +3,26 @@
class EnabledExtensionManager(ExtensionManager):
"""An ExtensionManager that only loads plugins that pass a check function.
+
+ The check_func should return a boolean, with ``True`` indicating
+ that the extension should be loaded and made available and
+ ``False`` indicating that the extension should be ignored.
+
+ :param namespace: The namespace for the entry points.
+ :type namespace: str
+ :param check_func: Function to determine which extensions to load.
+ :type check_func: callable
+ :param invoke_on_load: Boolean controlling whether to invoke the
+ object returned by the entry point after the driver is loaded.
+ :type invoke_on_load: bool
+ :param invoke_args: Positional arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_args: tuple
+ :param invoke_kwds: Named arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_kwds: dict
"""
def __init__(self, namespace, check_func, invoke_on_load=False,
View
28 stevedore/extension.py
@@ -10,6 +10,16 @@
class Extension(object):
+ """Book-keeping object for tracking extensions.
+
+ :param name: The entry point name.
+ :type name: str
+ :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
+ manager invoked the extension on load.
+ """
def __init__(self, name, entry_point, plugin, obj):
self.name = name
@@ -19,6 +29,22 @@ def __init__(self, name, entry_point, plugin, obj):
class ExtensionManager(object):
+ """Base class for all of the other managers.
+
+ :param namespace: The namespace for the entry points.
+ :type namespace: str
+ :param invoke_on_load: Boolean controlling whether to invoke the
+ object returned by the entry point after the driver is loaded.
+ :type invoke_on_load: bool
+ :param invoke_args: Positional arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_args: tuple
+ :param invoke_kwds: Named arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_kwds: dict
+ """
def __init__(self, namespace, invoke_on_load=False, invoke_args=(), invoke_kwds={}):
self.namespace = namespace
@@ -59,7 +85,7 @@ def map(self, func, *args, **kwds):
def func(ext, *args, **kwds):
pass
- The first argument to func(), 'ext', is the Extension
+ The first argument to func(), 'ext', is the :class:`Extension`
instance.
Exceptions raised from within func() are logged and ignored.
View
18 stevedore/hook.py
@@ -2,7 +2,23 @@
class HookManager(NamedExtensionManager):
- """Coordinate execution of extensions using a shared name.
+ """Coordinate execution of multiple extensions using a common name.
+
+ :param namespace: The namespace for the entry points.
+ :type namespace: str
+ :param name: The name of the hooks to load.
+ :type name: str
+ :param invoke_on_load: Boolean controlling whether to invoke the
+ object returned by the entry point after the driver is loaded.
+ :type invoke_on_load: bool
+ :param invoke_args: Positional arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_args: tuple
+ :param invoke_kwds: Named arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_kwds: dict
"""
def __init__(self, namespace, name,
View
16 stevedore/named.py
@@ -6,6 +6,22 @@ class NamedExtensionManager(EnabledExtensionManager):
This is useful for explictly enabling extensions in a
configuration file, for example.
+
+ :param namespace: The namespace for the entry points.
+ :type namespace: str
+ :param name: The names of the extensions to load.
+ :type name: str
+ :param invoke_on_load: Boolean controlling whether to invoke the
+ object returned by the entry point after the driver is loaded.
+ :type invoke_on_load: bool
+ :param invoke_args: Positional arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_args: tuple
+ :param invoke_kwds: Named arguments to pass when invoking
+ the object returned by the entry point. Only used if invoke_on_load
+ is True.
+ :type invoke_kwds: dict
"""
def __init__(self, namespace, names,

0 comments on commit 2e7e0ab

Please sign in to comment.