From 48c8393c5eedd030909aa7902d9704c7109eece0 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Wed, 5 Jun 2013 18:02:12 -0400 Subject: [PATCH] Add example of loading as a driver Create an example program to load the formatters from the tutorial as a driver and print some data. Update run_sphinx to watch .txt files. Signed-off-by: Doug Hellmann --- docs/source/tutorial/driver_output.txt | 36 +++++++++++++++++ docs/source/tutorial/loading.rst | 54 ++++++++++++++++++++++++++ run_sphinx | 2 +- stevedore/example/load_as_driver.py | 37 ++++++++++++++++++ 4 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 docs/source/tutorial/driver_output.txt create mode 100644 stevedore/example/load_as_driver.py diff --git a/docs/source/tutorial/driver_output.txt b/docs/source/tutorial/driver_output.txt new file mode 100644 index 0000000..a0ec45e --- /dev/null +++ b/docs/source/tutorial/driver_output.txt @@ -0,0 +1,36 @@ +$ python -m stevedore.example.load_as_driver a = A +b = B +long = word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word word + +$ python -m stevedore.example.load_as_driver field +: a : A +: b : B +: long : word word word word word word word word word word + word word word word word word word word word word word + word word word word word word word word word word word + word word word word word word word word word word word + word word word word word word word word word word word + word word word word word word word word word word word + word word word word word word word word word word word + word word word word + +$ python -m stevedore.example.load_as_driver field --width 30 +: a : A +: b : B +: long : word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word word word word word + word diff --git a/docs/source/tutorial/loading.rst b/docs/source/tutorial/loading.rst index f47501e..fab092e 100644 --- a/docs/source/tutorial/loading.rst +++ b/docs/source/tutorial/loading.rst @@ -2,7 +2,61 @@ Loading the Plugins ===================== +Load plugins using stevedore is as easy as creating them. There are +several different enabling and invocation patterns to choose from, +depending on your needs. + +Loading Drivers +=============== + +The most common way plugins are used is as individual drivers. There +may be many plugin options to choose from, but only one needs to be +loaded and called. The :class:`~stevedore.driver.DriverManager` class +supports this pattern. + +This example program uses a :class:`DriverManager` to load a formatter +defined in the examples for stevedore. It then uses the formatter to +convert a data structure to a text format, which it can print. + +.. literalinclude:: ../../../stevedore/example/load_as_driver.py + :language: python + :linenos: + :prepend: # stevedore/example/load_as_driver.py + +The manager takes the plugin namespace and name as arguments, and uses +them to find the plugin. Then, because ``invoke_on_load`` is true, it +calls the object loaded. In this case that object is the plugin class +registered as a formatter. The ``invoke_args`` are positional +arguments passed to the class constructor, and are used to set the +maximum width parameter. + +.. literalinclude:: ../../../stevedore/example/load_as_driver.py + :language: python + :lines: 30-35 + +After the manager is created, it holds a reference to a single object +returned by calling the code registered for the plugin. That object is +the actual driver, in this case an instance of the formatter class +from the plugin. The single driver can be accessed via the +:attr:`driver` property of the manager, and then its methods can be +called directly. + +.. literalinclude:: ../../../stevedore/example/load_as_driver.py + :language: python + :lines: 36-37 + +Running the example program produces this output: + +.. literalinclude:: driver_output.txt + + .. talk about when to do this, and that it should be done as few times as possible (on app startup, rather than on each event) .. explain invoke_on_load use case + + +.. seealso:: + + * :doc:`/patterns_loading` + * :doc:`/patterns_enabling` diff --git a/run_sphinx b/run_sphinx index 147bab1..b501058 100755 --- a/run_sphinx +++ b/run_sphinx @@ -4,7 +4,7 @@ set -x watchmedo shell-command \ - --patterns='*.rst;*.py' \ + --patterns='*.rst;*.py;*.txt' \ --ignore-pattern='docs/build/*;*flymake*' \ --recursive \ --command='python setup.py build_sphinx' diff --git a/stevedore/example/load_as_driver.py b/stevedore/example/load_as_driver.py new file mode 100644 index 0000000..d8c47f5 --- /dev/null +++ b/stevedore/example/load_as_driver.py @@ -0,0 +1,37 @@ +from __future__ import print_function + +import argparse + +from stevedore import driver + + +if __name__ == '__main__': + parser = argparse.ArgumentParser() + parser.add_argument( + 'format', + nargs='?', + default='simple', + help='the output format', + ) + parser.add_argument( + '--width', + default=60, + type=int, + help='maximum output width for text', + ) + parsed_args = parser.parse_args() + + data = { + 'a': 'A', + 'b': 'B', + 'long': 'word ' * 80, + } + + mgr = driver.DriverManager( + namespace='stevedore.example.formatter', + name=parsed_args.format, + invoke_on_load=True, + invoke_args=(parsed_args.width,), + ) + for chunk in mgr.driver.format(data): + print(chunk, end='')