[Docstring-checkins] CVS: dps/dps utils.py,1.12,1.13

[David G. <go...@us...>]

Update of /cvsroot/docstring/dps/dps
In directory usw-pr-cvs1:/tmp/cvs-serv9321/dps/dps

Modified Files:
	utils.py 
Log Message:
docstrings

Index: utils.py
===================================================================
RCS file: /cvsroot/docstring/dps/dps/utils.py,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** utils.py	2002/02/06 02:53:53	1.12
--- utils.py	2002/02/07 02:00:45	1.13
***************
*** 24,30 ****
  
      """
!     The concept of "categories" was inspired by the log4j__ project.
  
!     __ http://jakarta.apache.org/log4j/
      """
  
--- 24,52 ----
  
      """
!     Info/warning/error reporter and ``system_warning`` element generator.
  
!     Five levels of system warnings are defined, along with corresponding
!     methods: `debug()`, `info()`, `warning()`, `error()`, and `severe()`.
! 
!     There is typically one Reporter object per process. A Reporter object is
!     instantiated with thresholds for generating warnings and errors (raising
!     exceptions), a switch to turn debug output on or off, and a I/O stream for
!     warnings. These are stored in the default reporting category, ''.
! 
!     Multiple reporting categories [#]_ may be set, each with its own warning
!     and error thresholds, debugging switch, and warning stream. Categories are
!     hierarchically-named strings that look like attribute references: 'spam',
!     'spam.eggs', 'neeeow.wum.ping'. The 'spam' category is the ancestor of
!     'spam.bacon.eggs'. Unset categories inherit stored values from their
!     closest ancestor category that has been set.
! 
!     When a system warning is generated, the stored values from its category
!     (or ancestor if unset) are retrieved. The system warning level is compared
!     to the thresholds stored in the category, and a warning or error is
!     generated as appropriate. Debug warnings are produced iff the stored debug
!     switch is on. Warning output is sent to the stored warning stream.
! 
!     .. [#]_ The concept of "categories" was inspired by the log4j project:
!        http://jakarta.apache.org/log4j/.
      """
  
***************
*** 35,41 ****
          """
          Initialize the `Reporter`'s default logging category.
!         
          Parameters:
!         
          - `warninglevel`: The level at or above which warning output will be
            sent to `warningstream`.
--- 57,63 ----
          """
          Initialize the `Reporter`'s default logging category.
! 
          Parameters:
! 
          - `warninglevel`: The level at or above which warning output will be
            sent to `warningstream`.
***************
*** 49,55 ****
          if warningstream is None:
              warningstream = sys.stderr
!  
          self.categories = {'': (debug, warninglevel, errorlevel, warningstream)}
!         """Mapping of category names to levels. Default is ''."""
  
      def setcategory(self, category, warninglevel, errorlevel,
--- 71,77 ----
          if warningstream is None:
              warningstream = sys.stderr
! 
          self.categories = {'': (debug, warninglevel, errorlevel, warningstream)}
!         """Mapping of category names to levels. Default category is ''."""
  
      def setcategory(self, category, warninglevel, errorlevel,
***************
*** 88,103 ****
--- 110,147 ----
  
      def debug(self, comment=None, children=[], category=''):
+         """
+         Level-0, "DEBUG": an internal reporting issue. Typically, there is no
+         effect on the processing. Level-0 system warnings are handled
+         separately from the others.
+         """
          return self.system_warning(0, comment, children, category)
  
      def info(self, comment=None, children=[], category=''):
+         """
+         Level-1, "INFO": a minor issue that can be ignored. Typically there is
+         no effect on processing, and level-1 system warnings are not reported.
+         """
          return self.system_warning(1, comment, children, category)
  
      def warning(self, comment=None, children=[], category=''):
+         """
+         Level-2, "WARNING": an issue that should be addressed. If ignored,
+         there may be unpredictable problems with the output.
+         """
          return self.system_warning(2, comment, children, category)
  
      def error(self, comment=None, children=[], category=''):
+         """
+         Level-3, "ERROR": an error that should be addressed. If ignored, the
+         output will contain errors.
+         """
          return self.system_warning(3, comment, children, category)
  
      def severe(self, comment=None, children=[], category=''):
+         """
+         Level-4, "SEVERE": a severe error that must be addressed. If ignored,
+         the output will contain severe errors. Typically level-4 system
+         warnings are turned into exceptions which halt processing.
+         """
          return self.system_warning(4, comment, children, category)
  
***************
*** 115,119 ****
      :Parameters:
          - `lines`: List of one-line strings of the form::
!           
              ['[name1=value1 name2=value2]', '[name3="value 3"]']
  
--- 159,163 ----
      :Parameters:
          - `lines`: List of one-line strings of the form::
! 
              ['[name1=value1 name2=value2]', '[name3="value 3"]']