From 71c679e1a0105490bd5845a15de5e8f1a32e2166 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 11 Sep 2012 10:32:30 -0400 Subject: Cfg: documented all Cfg modules, added development docs --- src/lib/Bcfg2/Server/Plugin/base.py | 6 +- src/lib/Bcfg2/Server/Plugin/helpers.py | 131 ++++++++++++++++++++------------- 2 files changed, 79 insertions(+), 58 deletions(-) (limited to 'src/lib/Bcfg2/Server/Plugin') diff --git a/src/lib/Bcfg2/Server/Plugin/base.py b/src/lib/Bcfg2/Server/Plugin/base.py index ad5418d57..6b75bd174 100644 --- a/src/lib/Bcfg2/Server/Plugin/base.py +++ b/src/lib/Bcfg2/Server/Plugin/base.py @@ -85,17 +85,13 @@ class Plugin(Debuggable): __rmi__ = Debuggable.__rmi__ def __init__(self, core, datastore): - """ Initialize the plugin. - + """ :param core: The Bcfg2.Server.Core initializing the plugin :type core: Bcfg2.Server.Core :param datastore: The path to the Bcfg2 repository on the filesystem :type datastore: string :raises: :class:`Bcfg2.Server.Plugin.exceptions.PluginInitError` - - .. autoattribute:: __author__ - .. autoattribute:: __rmi__ """ object.__init__(self) self.Entries = {} diff --git a/src/lib/Bcfg2/Server/Plugin/helpers.py b/src/lib/Bcfg2/Server/Plugin/helpers.py index 51ff36b97..3334dfb27 100644 --- a/src/lib/Bcfg2/Server/Plugin/helpers.py +++ b/src/lib/Bcfg2/Server/Plugin/helpers.py @@ -48,15 +48,16 @@ info_regex = re.compile('owner:(\s)*(?P\S+)|' + 'mtime:(\s)*(?P\w+)|') def bind_info(entry, metadata, infoxml=None, default=default_file_metadata): - """ Bind the file metadata in the given :class:`InfoXML` object to - the given entry. + """ Bind the file metadata in the given + :class:`Bcfg2.Server.Plugin.helpers.InfoXML` object to the given + entry. :param entry: The abstract entry to bind the info to :type entry: lxml.etree._Element :param metadata: The client metadata to get info for :type metadata: Bcfg2.Server.Plugins.Metadata.ClientMetadata :param infoxml: The info.xml file to pull file metadata from - :type infoxml: Bcfg2.Server.Plugins.helpers.InfoXML + :type infoxml: Bcfg2.Server.Plugin.helpers.InfoXML :param default: Default metadata to supply when the info.xml file does not include a particular attribute :type default: dict @@ -78,7 +79,10 @@ def bind_info(entry, metadata, infoxml=None, default=default_file_metadata): class DatabaseBacked(Plugin): """ Provides capabilities for a plugin to read and write to a - database.""" + database. + + .. private-include: _use_db + """ #: The option to look up in :attr:`section` to determine whether or #: not to use the database capabilities of this plugin. The option @@ -96,9 +100,7 @@ class DatabaseBacked(Plugin): @property def _use_db(self): """ Whether or not this plugin is configured to use the - database. - - .. private-include""" + database. """ use_db = self.core.setup.cfp.getboolean(self.section, self.option, default=False) @@ -113,9 +115,9 @@ class DatabaseBacked(Plugin): class PluginDatabaseModel(object): """ A database model mixin that all database models used by - :class:`DatabaseBacked` plugins must inherit from. This is just a - mixin; models must also inherit from django.db.models.Model to be - valid Django models.""" + :class:`Bcfg2.Server.Plugin.helpers.DatabaseBacked` plugins must + inherit from. This is just a mixin; models must also inherit from + django.db.models.Model to be valid Django models.""" class Meta: app_label = "Server" @@ -124,7 +126,7 @@ class PluginDatabaseModel(object): class FileBacked(object): """ This object caches file data in memory. FileBacked objects are principally meant to be used as a part of - :class:`DirectoryBacked`. """ + :class:`Bcfg2.Server.Plugin.helpers.DirectoryBacked`. """ def __init__(self, name, fam=None): """ @@ -174,7 +176,7 @@ class DirectoryBacked(object): #: The type of child objects to create for files contained within #: the directory that is tracked. Default is - #: :class:`FileBacked` + #: :class:`Bcfg2.Server.Plugin.helpers.FileBacked` __child__ = FileBacked #: Only track and include files whose names (not paths) match this @@ -195,7 +197,8 @@ class DirectoryBacked(object): :param fam: The FAM object used to receive notifications of changes :type fam: Bcfg2.Server.FileMonitor.FileMonitor - + + .. ----- .. autoattribute:: __child__ """ object.__init__(self) @@ -367,7 +370,8 @@ class DirectoryBacked(object): class XMLFileBacked(FileBacked): """ This object is caches XML file data in memory. It can be used - as a standalone object or as a part of :class:`XMLDirectoryBacked` + as a standalone object or as a part of + :class:`Bcfg2.Server.Plugin.helpers.XMLDirectoryBacked` """ #: If ``__identifier__`` is not None, then it must be the name of @@ -386,9 +390,12 @@ class XMLFileBacked(FileBacked): changes. It may be useful to disable monitoring when, for instance, the file is monitored by another object (e.g., - an :class:`XMLDirectoryBacked` object). + an + :class:`Bcfg2.Server.Plugin.helpers.XMLDirectoryBacked` + object). :type should_monitor: bool + .. ----- .. autoattribute:: __identifier__ """ FileBacked.__init__(self, filename) @@ -567,7 +574,7 @@ class StructFile(XMLFileBacked): class INode(object): """ INodes provide lists of things available at a particular group intersection. INodes are deprecated; new plugins should use - :class:`StructFile` instead. """ + :class:`Bcfg2.Server.Plugin.helpers.StructFile` instead. """ raw = dict( Client="lambda m, e:'%(name)s' == m.hostname and predicate(m, e)", @@ -636,8 +643,9 @@ class INode(object): class InfoNode (INode): - """ :class:`INode` implementation that includes ```` tags, - suitable for use with :file:`info.xml` files. """ + """ :class:`Bcfg2.Server.Plugin.helpers.INode` implementation that + includes ```` tags, suitable for use with :file:`info.xml` + files.""" raw = {'Client': "lambda m, e:'%(name)s' == m.hostname and predicate(m, e)", 'Group': "lambda m, e:'%(name)s' in m.groups and predicate(m, e)", @@ -649,9 +657,11 @@ class InfoNode (INode): class XMLSrc(XMLFileBacked): - """ XMLSrc files contain a :class:`INode` hierarchy that returns + """ XMLSrc files contain a + :class:`Bcfg2.Server.Plugin.helpers.INode` hierarchy that returns matching entries. XMLSrc objects are deprecated and - :class:`StructFile` should be preferred where possible.""" + :class:`Bcfg2.Server.Plugin.helpers.StructFile` should be + preferred where possible.""" __node__ = INode __cacheobj__ = dict __priority_required__ = True @@ -707,15 +717,16 @@ class XMLSrc(XMLFileBacked): class InfoXML(XMLSrc): - """ InfoXML files contain a :class:`InfoNode` hierarchy that + """ InfoXML files contain a + :class:`Bcfg2.Server.Plugin.helpers.InfoNode` hierarchy that returns matching entries, suitable for use with :file:`info.xml` - files. """ + files.""" __node__ = InfoNode __priority_required__ = False class XMLDirectoryBacked(DirectoryBacked): - """ :class:`DirectoryBacked` for XML files. """ + """ :class:`Bcfg2.Server.Plugin.helpers.DirectoryBacked` for XML files. """ #: Only track and include files whose names (not paths) match this #: compiled regex. @@ -723,25 +734,28 @@ class XMLDirectoryBacked(DirectoryBacked): #: The type of child objects to create for files contained within #: the directory that is tracked. Default is - #: :class:`XMLFileBacked` + #: :class:`Bcfg2.Server.Plugin.helpers.XMLFileBacked` __child__ = XMLFileBacked class PrioDir(Plugin, Generator, XMLDirectoryBacked): """ PrioDir handles a directory of XML files where each file has a - set priority. """ + set priority. + + .. ----- + .. autoattribute:: __child__ + """ #: The type of child objects to create for files contained within #: the directory that is tracked. Default is - #: :class:`XMLSrc` + #: :class:`Bcfg2.Server.Plugin.helpers.XMLSrc` __child__ = XMLSrc def __init__(self, core, datastore): Plugin.__init__(self, core, datastore) Generator.__init__(self) XMLDirectoryBacked.__init__(self, self.data, self.core.fam) - __init__.__doc__ = \ - Plugin.__init__.__doc__ + "\n\n.. autoattribute:: __child__" + __init__.__doc__ = Plugin.__init__.__doc__ def HandleEvent(self, event): XMLDirectoryBacked.HandleEvent(self, event) @@ -926,9 +940,11 @@ class SpecificData(object): """ :param name: The full path to the file :type name: string - :param specific: A :class:`Specificity` object describing what - clients this file applies to. - :type specific: Bcfg2.Server.Plugins.helpers.Specificity + :param specific: A + :class:`Bcfg2.Server.Plugin.helpers.Specificity` + object describing what clients this file + applies to. + :type specific: Bcfg2.Server.Plugin.helpers.Specificity :param encoding: The encoding to use for data in this file :type encoding: string """ @@ -939,11 +955,12 @@ class SpecificData(object): def handle_event(self, event): """ Handle a FAM event. Note that the SpecificData object itself has no FAM, so this must be produced by a parent object - (e.g., :class:`EntrySet`). + (e.g., :class:`Bcfg2.Server.Plugin.helpers.EntrySet`). :param event: The event that applies to this file :type event: Bcfg2.Server.FileMonitor.Event :returns: None + :raises: Bcfg2.Server.Plugin.exceptions.PluginExecutionError """ if event.code2str() == 'deleted': return @@ -957,14 +974,14 @@ class SpecificData(object): class EntrySet(Debuggable): """ EntrySets deal with a collection of host- and group-specific - files (e.g., :class:`SpecificData` objects) in a single - directory. EntrySets are usually used as part of - :class:`GroupSpool` objects.""" + files (e.g., :class:`Bcfg2.Server.Plugin.helpers.SpecificData` + objects) in a single directory. EntrySets are usually used as part + of :class:`Bcfg2.Server.Plugin.helpers.GroupSpool` objects.""" #: Preemptively ignore files whose names (not paths) match this #: compiled regex. ``ignore`` cannot be set to ``None``. If a #: file is encountered that does not match the ``basename`` - #: argument passed to the constructor or : ``ignore``, then a + #: argument passed to the constructor or ``ignore``, then a #: warning will be produced. ignore = re.compile("^(\.#.*|.*~|\\..*\\.(sw[px])|.*\\.genshi_include)$") @@ -1002,18 +1019,20 @@ class EntrySet(Debuggable): :param filepath: Full path to file :type filepath: string - :param specific: A :class:`Specificity` object describing what - clients this file applies to. - :type specific: Bcfg2.Server.Plugins.helpers.Specificity + :param specific: A + :class:`Bcfg2.Server.Plugin.helpers.Specificity` + object describing what clients this file + applies to. + :type specific: Bcfg2.Server.Plugin.helpers.Specificity :param encoding: The encoding to use for data in this file :type encoding: string Additionally, the object returned by ``entry_type`` must have a ``specific`` attribute that is sortable (e.g., a - :class:`Specificity` object). + :class:`Bcfg2.Server.Plugin.helpers.Specificity` object). - See :class:`SpecificData` for an example of a class that can - be used as an ``entry_type``. + See :class:`Bcfg2.Server.Plugin.helpers.SpecificData` for an + example of a class that can be used as an ``entry_type``. """ Debuggable.__init__(self, name=basename) self.path = path @@ -1083,7 +1102,8 @@ class EntrySet(Debuggable): metadata.hostname)) def handle_event(self, event): - """ Handle a FAM event. This will probably be handled by a + """ Dispatch a FAM event to the appropriate function or child + ``entry_type`` object. This will probably be handled by a call to :func:`update_metadata`, :func:`reset_metadata`, :func:`entry_init`, or to the ``entry_type`` ``handle_event()`` function. @@ -1159,8 +1179,10 @@ class EntrySet(Debuggable): self.entries[event.filename].handle_event(event) def specificity_from_filename(self, fname, specific=None): - """ Construct a :class:`Specificity` object from a filename - and regex. See :attr:`specific` for details on the regex. + """ Construct a + :class:`Bcfg2.Server.Plugin.helpers.Specificity` object from a + filename and regex. See :attr:`specific` for details on the + regex. :param fname: The filename (not full path) of a file that is in this EntrySet's directory. It is not @@ -1176,7 +1198,7 @@ class EntrySet(Debuggable): determine the specificity of this entry. :type specific: compiled regular expression object :returns: Object representing the specificity of the file - :rtype: :class:`Specificity` + :rtype: :class:`Bcfg2.Server.Plugin.helpers.Specificity` :raises: :class:`Bcfg2.Server.Plugin.exceptions.SpecificityError` if the regex does not match the filename """ @@ -1267,9 +1289,10 @@ class EntrySet(Debuggable): class GroupSpool(Plugin, Generator): - """ A GroupSpool is a collection of :class:`EntrySet` objects -- - i.e., a directory tree, each directory in which may contain files - that are specific to groups/clients/etc. """ + """ A GroupSpool is a collection of + :class:`Bcfg2.Server.Plugin.helpers.EntrySet` objects -- i.e., a + directory tree, each directory in which may contain files that are + specific to groups/clients/etc. """ #: ``filename_pattern`` is used as the ``basename`` argument to the #: :attr:`es_cls` callable. It may or may not be a regex, @@ -1279,14 +1302,16 @@ class GroupSpool(Plugin, Generator): #: ``es_child_cls`` is a callable that will be used as the #: ``entry_type`` argument to the :attr:`es_cls` callable. It must #: return objects that will represent individual files in the - #: GroupSpool. For instance, :class:`SpecificData`. + #: GroupSpool. For instance, + #: :class:`Bcfg2.Server.Plugin.helpers.SpecificData`. es_child_cls = object #: ``es_cls`` is a callable that must return objects that will be #: used to represent directories (i.e., sets of entries) within the - #: GroupSpool. E.g., :class:`EntrySet`. The returned object must - #: implement a callable called ``bind_entry`` that has the same - #: signature as :attr:`EntrySet.bind_entry`. + #: GroupSpool. E.g., + #: :class:`Bcfg2.Server.Plugin.helpers.EntrySet`. The returned + #: object must implement a callable called ``bind_entry`` that has + #: the same signature as :attr:`EntrySet.bind_entry`. es_cls = EntrySet #: The entry type (i.e., the XML tag) handled by this GroupSpool -- cgit v1.2.3-1-g7c22