updated IncludeHelper TemplateHelper example

1 files changed, 62 insertions, 46 deletions

diff --git a/examples/TemplateHelper/include.py b/examples/TemplateHelper/include.py
index 5fba75558..be0034f52 100644
--- a/examples/TemplateHelper/include.py
+++ b/examples/TemplateHelper/include.py
@@ -1,17 +1,18 @@
-"""IncludeHelper makes it easier to include group- and host-specific files in a template.
+""" IncludeHelper makes it easier to include group- and host-specific
+files in a template.
 
 Synopsis:
 
   {% python
   import os
-  include = metadata.TemplateHelper['include'].IncludeHelper
-  custom = include(metadata, path).files(os.path.basename(name))
+  include = metadata.TemplateHelper['include']
+  custom = include.IncludeHelper(metadata, path).files(os.path.basename(name))
   %}\
   {% for file in custom %}\
-  
-  ########## Start ${include.specificity(file)} ##########
+
+  ########## Start ${include.describe_specificity(file)} ##########
   {% include ${file} %}
-  ########## End ${include.specificity(file)} ##########
+  ########## End ${include.describe_specificity(file)} ##########
   {% end %}\
 
 This would let you include files with the same base name; e.g. in a
@@ -27,71 +28,86 @@ This would result in two different sets of custom files being used,
 one drawn from ''bar.conf.G_<group>.genshi_include'' and the other
 from ''baz.conf.G_<group>.genshi_include''.
 
-==== Methods ====
-
-
-=== files ===
-
-Usage:
-
-
-
 """
 
 import os
 import re
-import Bcfg2.Options
 
-__export__ = ["IncludeHelper"]
+__export__ = ["IncludeHelper", "get_specificity", "describe_specificity"]
+
 
-class IncludeHelper (object):
+class IncludeHelper(object):
     def __init__(self, metadata, path):
         """ Constructor.
 
-        The template path can be found in the ''path'' variable that is set for all Genshi templates."""
+        The template path can be found in the ''path'' variable that
+        is set for all Genshi templates. """
         self.metadata = metadata
         self.path = path
-    
-    def _get_basedir(self):
-        setup = Bcfg2.Options.OptionParser({'repo':
-                                            Bcfg2.Options.SERVER_REPOSITORY})
-        setup.parse('--')
-        return os.path.join(setup['repo'], os.path.dirname(self.path))
-    
-    def files(self, fname):
+
+    def get_basedir(self):
+        return os.path.dirname(self.path)
+
+    def files(self, fname, groups=None):
         """ Return a list of files to include for this host.  Files
         are found in the template directory based on the following
         patterns:
 
           * ''<prefix>.H_<hostname>.genshi_include'': Host-specific files
           * ''<prefix>.G_<group>.genshi_include'': Group-specific files
+          * ''<prefix>.genshi_include'': Non-specific includes
 
         Note that there is no numeric priority on the group-specific
-        files.  All matching files are returned by
-        ''IncludeHelper.files()''. """
+        files; all matching files are returned by
+        ``IncludeHelper.files()``.  If you wish to only include files
+        for a subset of groups, pass the ``groups`` keyword argument.
+        Host-specific files are always included in the return
+        value. """
         files = []
-        hostfile = os.path.join(self._get_basedir(),
+        hostfile = os.path.join(self.get_basedir(),
                                 "%s.H_%s.genshi_include" %
                                 (fname, self.metadata.hostname))
         if os.path.isfile(hostfile):
             files.append(hostfile)
-            
-        for group in self.metadata.groups:
-            filename = os.path.join(self._get_basedir(),
+
+        allfile = os.path.join(self.get_basedir(), "%s.genshi_include" % fname)
+        if os.path.isfile(allfile):
+            files.append(allfile)
+
+        if groups is None:
+            groups = sorted(self.metadata.groups)
+
+        for group in groups:
+            filename = os.path.join(self.get_basedir(),
                                     "%s.G_%s.genshi_include" % (fname, group))
             if os.path.isfile(filename):
                 files.append(filename)
 
-        return sorted(files)
-
-    @staticmethod
-    def specificity(fname):
-        """ Get a string describing the specificity of the given file """
-        match = re.search(r'(G|H)_(.*)\.genshi_include', fname)
-        if match:
-            if match.group(1) == "G":
-                stype = "group"
-            else:
-                stype = "host"
-            return "%s-specific configs for %s" % (stype, match.group(2))
-        return "Unknown specificity"
+        return files
+
+
+SPECIFICITY_RE = re.compile(r'(G|H)_(.*)\.genshi_include')
+
+
+def get_specificity(fname):
+    """ Get a tuple of (<type>, <parameter>) describing the
+    specificity of the given file.  Specificity types are "host",
+    "group", or "all".  The parameter will be either a hostname, a
+    group name, or None (for "all"). """
+    match = SPECIFICITY_RE.search(fname)
+    if match:
+        if match.group(1) == "G":
+            stype = "group"
+        else:
+            stype = "host"
+        return (stype, match.group(2))
+    return ("all", None)
+
+
+def describe_specificity(fname):
+    """ Get a string describing the specificity of the given file """
+    (stype, param) = get_specificity(fname)
+    if stype != "all":
+        return "%s-specific configs for %s" % (stype, param)
+    else:
+        return "Generic configs for all clients"