From 80087699c8449dd862f73ae4edeb949efd36cc61 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 4 Dec 2012 13:56:26 -0600 Subject: doc: wrote devel docs for client tool base objects --- doc/development/client-driver.txt | 108 ++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 56 deletions(-) (limited to 'doc/development') diff --git a/doc/development/client-driver.txt b/doc/development/client-driver.txt index 67bbd0dce..29216acd5 100644 --- a/doc/development/client-driver.txt +++ b/doc/development/client-driver.txt @@ -2,73 +2,69 @@ .. _development-client-driver: -Writing A Client Tool Driver -============================ +============================== + Writing A Client Tool Driver +============================== This page describes the step-by-step process of writing a client tool driver for a configuration element type. The included example describes an existing driver, and the process that was used to create it. #. Pick a name for the driver. In this case, we picked the name RPM. -#. Create a file in ``src/lib/Client/Tools`` with the same name (RPM.py) -#. Create a class in this file with the same name (class RPM) +#. Create a file in ``src/lib/Bcfg2/Client/Tools`` with the same name + (RPM.py) +#. Create a class in this file with the same name (``class RPM``) - * If it handles **Package** entries, subclass ``Bcfg2.Client.Tools.PkgTool`` - (from here referenced as branch [P]) - * If it handles **Service** entries, subclass ``Bcfg2.Client.Tools.SvcTool`` - (from here referenced as branch [S]) - * Otherwise, subclass ``Bcfg2.Client.Tools.Tool`` (from here referenced - as branch [T]) + * If it handles **Package** entries, subclass + :class:`Bcfg2.Client.Tools.PkgTool` + * If it handles **Service** entries, subclass + :class:`Bcfg2.Client.Tools.SvcTool` + * Otherwise, subclass :class:`Bcfg2.Client.Tools.Tool`. -#. Set ``name`` to "RPM" -#. Add any required executable programs to ``__execs__`` -#. Set ``__handles__`` to a list of (**entry.tag**, **entry.get('type')**) - tuples. This determines which entries the Tool module can be used - on. In this case, we set ``__handles__ = [('Package', 'rpm')]``. -#. Add verification. This method should return True/False depending - on current entry installation status. +#. Add any required executable programs to + :attr:`Bcfg2.Client.Tools.Tool.__execs__` +#. Set :attr:`Bcfg2.Client.Tools.Tool.__handles__` to a list of + ``(, )`` tuples. This determines which entries the Tool + module can be used on. In this case, we set ``__handles__ = + [('Package', 'rpm')]``. +#. Add verification support by defining a method named + ``Verify``. See :func:`Bcfg2.Client.Tools.Tool.Inventory` for + details. This method should return True/False depending on current + entry installation status. In the failure path, the current state + of failing entry attributes should be set in the entry, to aid in + auditing. (For example, if a file should be mode 644, and is + currently mode 600, then set attribute current_mode='600' in the + input entry) +#. Add installation support by defining a method named + ``Install method. - * [P] Add a VerifyPackage method. - * [S] Add a VerifyService method. - * In the failure path, the current state of failing entry - attributes should be set in the entry, to aid in auditing. - (For example, if a file should be mode 644, and is currently - mode 600, then set attribute current_mode='600' in the input - entry) + If you are writing a tool to handle Package entries, PkgTool class + has a generic mechanism for performing all-at-once installations, + followed, in the case of failures, by single installations. See + :func:`Bcfg2.Client.Tools.PkgTool.Install` for details. +#. Optionally, add support for removing extra entries by defining a + :func:`Bcfg2.Client.Tools.Tool.Remove` method. +#. Optionally, add a :func:`Bcfg2.Client.Tools.Tool.FindExtra` method + that locates entries not included in the configuration. +#. Package drivers require a + :func:`Bcfg2.Client.Tools.PkgTool.RefreshPackages` method that + updates the internal representation of the package database. -#. Add installation support. This method should return True/False - depending on the results of the installation process. +Client Tool API +=============== - * [T,S] Add an Install method. - * [P] The PkgTool baseclass has a generic mechanism for performing - all-at-once installations, followed, in the case of failures, - by single installations. To enable this support, set the pkgtype - attribute to the package type handled by this driver. Set the - pkgtool to a tuple ("command string %s", ("per-package string - format", [list of package entry fields])). For RPM, we have - setup ``pkgtool = ("rpm --oldpackage --replacepkgs --quiet -U %s", ("%s", ["url"]))`` +Base Classes +------------ -#. Implement entry removal +.. autoclass:: Bcfg2.Client.Tools.Tool +.. autoclass:: Bcfg2.Client.Tools.PkgTool +.. autoclass:: Bcfg2.Client.Tools.SvcTool - * [T,S] Implement a ``Remove`` method that removes all specified - entries (``prototype Remove(self, entries)``) - * [P] Implement a ``RemovePackages`` that removes all specified - entries (same prototype as Remove) - -#. Add a ``FindExtra`` method that locates entries not included in the - configuration. This may or may not be required, certain drivers - do not have the capability to find extra entries. -#. [P] Package drivers require a ``RefreshPackages`` method that updates - the internal representation of the package database. - -Writing Tool Driver Methods ---------------------------- - -#. Programs can be run using ``self.cmd.run``. This function returns a - (return code, stdout list) tuple. -#. The configuration is available as ``self.config`` -#. Runtime options are available in a dictionary as ``self.setup`` -#. Informational, error, and debug messages can be produced by - running ``self.logger.info/error/debug``. +Helper Classes +-------------- +.. autoclass:: Bcfg2.Client.Tools.ClassName +.. autoclass:: Bcfg2.Client.Tools.Executor +.. autoclass:: Bcfg2.Client.Tools.ToolInstantiationError -- cgit v1.2.3-1-g7c22