Commits

htgoebel committed 1cbdb9a

Added documentation on doctest

Comments (0)

Files changed (1)

shinken_plugins/__init__.py

 #!/usr/bin/env python
+"""
+Implement shinken plugins easily.
+"""
 #
 # Copyright (C) 2009-2010 by Hartmut Goebel <h.goebel@goebel-consult.de>
 #
 
 class Check:
     def __init__(self):
-        self._name = self.__class__.__name__
-        self._parser = argparse.ArgumentParser(prog=self._name)
+        self.name = self.__class__.__name__
+        self._parser = argparse.ArgumentParser(prog=self.name)
         self.add_arguments(self._parser)
         
     def _parse_args(self, args):
 
 
 class Result:
+    """
+    Class representing a result passed back to the shinken poller.
+    """
     def __init__(self, rc=OK, message=None, perfdata=None, lines=None):
         self.rc = rc
         self.message = message
         self.perfdata = perfdata or {}
         self.lines = lines or []
 
-    def _validate_(self):
-        raise NotImpementedError
+    def __str__(self):
+        """
+        Compute the 'informal' string representation of a result.
 
-    def __str__(self):
+        This string is compatible with the format Nagios is expecting
+        as a result.
+        """
         parts = []
         if self.message:
             parts.append('%s - %s' % (rc_names[self.rc], self.message))
                 parts.append('%s=%s' % (k, v))
         return os.linesep.join(parts)   
 
+    def update_rc(self, rc):
+        """
+        Update the results return code to a new value if and only if
+        the new value is higher (more critical) than the current one. This allows easy collecting results within a loop.
+
+        Example:
+
+        >>> r = Result(OK)
+        >>> r.update_rc(WARNING) ; print r
+        WARNING
+
+        >>> r.update_rc(OK) ; print r
+        WARNING
+        >>> r.update_rc(CRITICAL) ; print r
+        CRITICAL
+        >>> 
+        """
+        self.rc = max(self.rc, rc)
+
+
     def add_perfdata(self, name, value):
+        """
+        Add another performance data entry to the result.
+        """
         self.perfdata[name] = value
 
+
+    def add_message(self, line):
+        """
+        Add another message line to the results LONGSERVICEOUTPUT
+        lines.
+        """
+        if isinstance(line, basestring):
+            self.lines.append(line)
+        else:
+            self.lines.extend(line)
+
+
     def __iadd__(self, other):
+        """
+        >>> r1 = Result(OK, 'result1', {'free': '10%'}, ['10% free'])
+        >>> r3 = Result(CRITICAL, perfdata={'cpu': '100%'})
+
+        >>> r1 += r3
+        >>> print r1
+        CRITICAL - result1
+        10% free
+        |
+        cpu=100%
+        free=10%
+        >>> print r3
+        CRITICAL
+        |
+        cpu=100%
+        >>>
+        """
+
         self.rc = max(self.rc, other.rc)
         self.perfdata.update(other.perfdata)
         if other.message:
         self.lines.extend(other.lines)
         return self
 
+
     def __add__(self, other):
+        """
+        >>> print Result(OK)
+        OK
+        >>> print Result(OK) + Result(CRITICAL) + Result(WARNING)
+        CRITICAL
+
+        >>> r1 = Result(OK, 'result1', {'free': '10%'}, ['10% free'])
+        >>> r2 = Result(WARNING, 'not do good')
+
+        >>> r = r1+r2
+        >>> print r1
+        OK - result1
+        10% free
+        |
+        free=10%
+        >>> print r2
+        WARNING - not do good
+        >>> print r
+        WARNING - result1
+        10% free
+        not do good
+        |
+        free=10%
+        >>>
+        """
         new = Result(self.rc, self.message, self.perfdata.copy(),
                      self.lines[:])
         new += other
 
 
 def __main__(klass, args=None):
+    """
+    Run a check plugin class from command line. The result is printed
+    to stdout and the programm terminates with the resturn code of the
+    result.
+    """
     check = klass()
     args = check._parse_args(args)
     result = check.run(args)
         sys.exit('Error: check must return a Result() instance')
     print result
     sys.exit(result.rc)
+
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod()