diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/development/index.txt | 1 | ||||
-rw-r--r-- | doc/development/plugins.txt | 4 | ||||
-rw-r--r-- | doc/development/unit-testing.txt | 25 | ||||
-rw-r--r-- | doc/server/plugins/connectors/templatehelper.txt | 72 |
4 files changed, 98 insertions, 4 deletions
diff --git a/doc/development/index.txt b/doc/development/index.txt index 352000dc8..2a54bfad8 100644 --- a/doc/development/index.txt +++ b/doc/development/index.txt @@ -39,3 +39,4 @@ git access. Mail the :ref:`help-mailinglist` for details. testing documentation docstyleguide + unit-testing diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt index 15b512365..b2b70f553 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -164,7 +164,6 @@ Example Connector Bcfg2.Server.Plugin.Connector): '''The Foo plugin is here to illustrate a barebones connector''' name = 'Foo' - version = '$Revision: $' experimental = True def __init__(self, core, datastore): @@ -195,13 +194,10 @@ do so. We will call our new plugin `MyMetadata`. .. code-block:: python - __revision__ = '$Revision$' - import Bcfg2.Server.Plugins.Metadata class MyMetadata(Bcfg2.Server.Plugins.Metadata.Metadata): '''This class contains data for bcfg2 server metadata''' - __version__ = '$Id$' __author__ = 'bcfg-dev@mcs.anl.gov' def __init__(self, core, datastore, watch_clients=True): diff --git a/doc/development/unit-testing.txt b/doc/development/unit-testing.txt new file mode 100644 index 000000000..30217dcc5 --- /dev/null +++ b/doc/development/unit-testing.txt @@ -0,0 +1,25 @@ +.. -*- mode: rst -*- + +.. _development-unit-testing: + +================== +Bcfg2 unit testing +================== + +.. _Python Mock Module: http://python-mock.sourceforge.net/ +.. _Python Nose: http://readthedocs.org/docs/nose/en/latest/ + +You will first need to install the `Python Mock Module`_ and `Python +Nose`_ modules. You can then run the existing tests with the +following.:: + + cd testsuite + nosetests + +You should see output something like the following:: + + .................................................. + ---------------------------------------------------------------------- + Ran 50 tests in 0.121s + + OK diff --git a/doc/server/plugins/connectors/templatehelper.txt b/doc/server/plugins/connectors/templatehelper.txt new file mode 100644 index 000000000..67219109f --- /dev/null +++ b/doc/server/plugins/connectors/templatehelper.txt @@ -0,0 +1,72 @@ +.. -*- mode: rst -*- + +.. _server-plugins-connectors-templatehelper: + +============== +TemplateHelper +============== + +The TemplateHelper plugin is a connector plugin that adds Python +classes and methods to client metadata instances for use in +templates. This allows you to easily reuse code that is common +amongst multiple templates and add convenience methods. + +Using TemplateHelper +==================== + +First, ``mkdir /var/lib/bcfg2/TemplateHelper`` and add +**TemplateHelper** to your ``plugins`` line in ``/etc/bcfg2.conf``. +Restart ``bcfg2-server``. + +Now, any ``.py`` file placed in ``/var/lib/bcfg2/TemplateHelper/`` +will be read and added to matching client metadata objects. See +:ref:`Writing Helpers` below for more information on how to write +TemplateHelper scripts. + +TemplateHelper supports group- and host-specific helpers, so you could +create, e.g., ``foo.py.G80_test`` to create a helper that only applied +to machines in the group ``test``. + +Writing Helpers +=============== + +A helper module is just a Python module with three special conditions: + +* The filename must end with ``.py`` (before any specificity + strings, e.g., ``.G80_foo`` or ``.H_blah.example.com`` +* The module must have an attribute, ``__export__``, that lists all of + the classes, functions, variables, or other symbols you wish to + export from the module. +* ``data``, ``handle_event``, ``name``, and ``specific`` are reserved + names. You should not include symbols with a reserved name in + ``__export__``. Additionally, including symbols that start with an + underscore or double underscore is bad form, and may also produce + errors. + +See ``examples/TemplateHelper`` for examples of helper modules. + +Usage +===== + +Specific helpers can be referred to in +templates as ``metadata.TemplateHelper[<modulename>]``. That accesses +a HelperModule object will has, as attributes, all symbols listed in +``__export__``. For example, consider this helper module:: + + __export__ = ["hello"] + + def hello(metadata): + return "Hello, %s!" % metadata.hostname + +To use this in a TGenshi template, we could do:: + + ${metadata.TemplateHelper['hello'].hello(metadata)} + +The template would produce:: + + Hello, foo.example.com! + +Note that the client metadata object is not passed to a helper module +in any magical way; if you want to access the client metadata object +in a helper function or class, you must pass the object to the +function manually. |