[gnue] r7145 - trunk/gnue-common/src/apps

[reinhard]

Author: reinhard
Date: 2005-03-09 15:49:35 -0600 (Wed, 09 Mar 2005)
New Revision: 7145

Modified:
   trunk/gnue-common/src/apps/GDebug.py
   trunk/gnue-common/src/apps/__init__.py
   trunk/gnue-common/src/apps/checktype.py
   trunk/gnue-common/src/apps/errors.py
   trunk/gnue-common/src/apps/i18n.py
   trunk/gnue-common/src/apps/plugin.py
Log:
More work on docstrings.


Modified: trunk/gnue-common/src/apps/GDebug.py
===================================================================
--- trunk/gnue-common/src/apps/GDebug.py        2005-03-09 17:54:16 UTC (rev 
7144)
+++ trunk/gnue-common/src/apps/GDebug.py        2005-03-09 21:49:35 UTC (rev 
7145)
@@ -21,6 +21,11 @@
 #
 # $Id$
 
+"""
+Support for debugging messages with independent debug levels and redirection of
+messages to a file.
+"""
+
 # Do this at the very start so we lose as little time as possible
 import time
 __starttime = time.time ()
@@ -51,8 +56,10 @@
 # Class to catch the stderr stream
 # -----------------------------------------------------------------------------
 
-class _stderrcatcher:
+class __stderrcatcher:
   """
+  Output stream for error message.
+
   sys.stderr is redirected to this class. It prepends "DB000: " in front of
   each line and writes everything to the debug file or stderr.
   """
@@ -76,11 +83,11 @@
 # redirect stderr and all debugging output to the given filehandle
 # -----------------------------------------------------------------------------
 
-def catchStderr (filehandle):
+def __catchStderr (filehandle):
 
   global _fh
   _fh = filehandle
-  sys.stderr = _stderrcatcher (filehandle)
+  sys.stderr = __stderrcatcher (filehandle)
 
 
 # =============================================================================
@@ -128,15 +135,14 @@
 
 def __dumpMessage (level, filename, message, dropToDebugger = False):
   """
-  This function writes a message to the debug-output adding the time elapsed
-  since __starttime.
+  Write a message to the debug-output.
 
   @param level: the debug-level the message will be logged in
   @param filename: the filename the message originated from
   @param message: the message to be logged
   @param dropToDebugger: if set to True, Python's interactive debugger will be
-      switched to trace mode. This requires that setDebugger has been called
-      before.
+    switched to trace mode. This requires that setDebugger has been called
+    before.
   """
 
   global _fh, _DEBUGGER
@@ -160,14 +166,14 @@
 
 def gDebug (level, message, dropToDebugger = False):
   """
-  This function writes a message to the debug-output. It is available in the
+  Write a message to the debug-output. This function is available in the
   global namespace.
 
   @param level: the debug-level the message will be logged in
   @param message: the message to be logged
   @param dropToDebugger: if set to True, Python's interactive debugger will be
-      switched to trace mode. This requires that setDebugger has been called
-      before.
+    switched to trace mode. This requires that setDebugger has been called
+    before.
   """
 
   if level in _DEBUG_LEVELS :
@@ -195,9 +201,11 @@
 
 def gEnter (level = 1):
   """
-  This function adds another line to the debug-output, describing the caller's
-  function with all it's arguments. It is available in the global namespace.
+  Write information about the current function and its parameters to
+  debug-output. This function is available in the global namespace.
 
+  gEnter is intended to be called at the begin of a function.
+
   @param level: the debug-level the message will be logged in
   """
 
@@ -255,12 +263,14 @@
 
 def gLeave (level = 1, *result):
   """
-  This function adds a line to the debug-output describing the end of a
-  function call, optionally containing the function's result. It is available
-  in the global namespace.
+  Write information about the current function and its return value to
+  debug-output. This function is available in the global namespace.
 
+  gLeave is intended to be called at the end of a function.
+
   @param level: debug-level to send the message to
   @param result: the function's result (if any)
+  @return: the result parameter
   """
 
   # We cannot use something like 'retVal = len (result) and result [0] or None'
@@ -312,10 +322,9 @@
 
 def setDebug (level, file = None):
   """
-  This function initializes and configures the debug message system.
+  Initialize and configure the debug message system
 
   @param level: A string with the debug levels to output, e.g. "0-3,5,7"
-  
   @param file: Filename to output debug messages to (instead of stderr)
   """
 
@@ -341,9 +350,9 @@
 
   # Redirect debugging and error output to a file if requested
   if (file):
-    catchStderr (open (file, 'w'))
+    __catchStderr (open (file, 'w'))
   else:
-    catchStderr (sys.__stderr__)
+    __catchStderr (sys.__stderr__)
 
 
 # -----------------------------------------------------------------------------

Modified: trunk/gnue-common/src/apps/__init__.py
===================================================================
--- trunk/gnue-common/src/apps/__init__.py      2005-03-09 17:54:16 UTC (rev 
7144)
+++ trunk/gnue-common/src/apps/__init__.py      2005-03-09 21:49:35 UTC (rev 
7145)
@@ -21,6 +21,9 @@
 #
 # $Id$
 
+"""
+Basic services for all GNUe based applications
+"""
 
 # Python 2.2 introduced True/False types
 # For Python 2.0/2.1, we add them ourselves

Modified: trunk/gnue-common/src/apps/checktype.py
===================================================================
--- trunk/gnue-common/src/apps/checktype.py     2005-03-09 17:54:16 UTC (rev 
7144)
+++ trunk/gnue-common/src/apps/checktype.py     2005-03-09 21:49:35 UTC (rev 
7145)
@@ -20,9 +20,11 @@
 # Copyright 2001-2005 Free Software Foundation
 #
 # $Id$
+
 """
-Support for checking the type of variables
+Support for checking the type of variables.
 """
+
 from types import *
 
 import string
@@ -91,9 +93,9 @@
 
   This function is available as builtin function.
 
-  @param variable: the variable to check
-  @param validtype: the type, the class, or a list of types and classes that
-    are valid
+  @param variable: Variable to check.
+  @param validtype: Type, class, or a list of types and classes that are valid.
+  @raise TypeError: The variable has a type not listed in the valid types.
   """
   if isinstance (validtype, ListType):
     for t in validtype:

Modified: trunk/gnue-common/src/apps/errors.py
===================================================================
--- trunk/gnue-common/src/apps/errors.py        2005-03-09 17:54:16 UTC (rev 
7144)
+++ trunk/gnue-common/src/apps/errors.py        2005-03-09 21:49:35 UTC (rev 
7145)
@@ -21,6 +21,10 @@
 #
 # $Id$
 
+"""
+General exception classes.
+"""
+
 import sys
 import traceback
 import types
@@ -40,6 +44,15 @@
   unicode strings.  This exception is available as the builtin class
   "gException".  All other user-defined exceptions should be derived from this
   class.
+
+  @ivar message: The error message.
+  @type message: Unicode
+  @ivar group: The group or category of the exception. Can be one of 'system',
+    'admin', 'application', or 'user'.
+  @ivar name: The name of the exception. If set, this will be returned by
+    L{getName} and L{getException} instead of the class name of the exception.
+  @ivar detail: The detail information to the exception. If set, this will be
+    returned by L{getDetail} and L{getException} instead of the traceback.
   """
   def __init__ (self, message, group = 'system'):
     self.message = message
@@ -54,8 +67,10 @@
 
   def getGroup (self):
     """
-    This function returns the group of the exception.
-    @return: group of the exception as string
+    Return the group of the exception.
+
+    @return: Group of the exception, one of 'system', 'admin', 'application',
+      or 'user'.
     """
     return self.group
 
@@ -66,8 +81,11 @@
 
   def getName (self, aType = None):
     """
-    This function returns the name of the exception (i.e. 'FooBarError')
-    @return: name of the exception as unicode string
+    Return the exception's name, which is the classname of the exception class
+      unless overwritten with L{name}.
+
+    @return: Name of the exception.
+    @rtype: Unicode
     """
     rep = self.name or "%s" % (sys.exc_info () [0] or aType)
     return self._fmtUnicode (rep.split ('.') [-1])
@@ -79,10 +97,15 @@
 
   def getDetail (self, count = None, type = None, value = None, trace = None):
     """
-    This function returns the exception's detail which is a traceback for
-    gException instances.
-    @param count: number of lines to skip in the traceback
-    @return: unicode string with the exception's traceback
+    Return the exception's detail, which is the traceback unless overwritten
+      with L{detail}.
+
+    Optionally, a number of lines can be skipped at the beginning of the
+    traceback (if the detail I{is} the traceback).
+
+    @param count: Number of lines to skip at the beginning of the traceback.
+    @return: Detail information for the exception.
+    @rtype: Unicode
     """
     if self.detail is not None:
       return self._fmtUnicode (self.detail, i18n.getencoding ())
@@ -102,8 +125,9 @@
 
   def getMessage (self):
     """
-    This function returns the message of an exception
-    @return: unicode string with the message of the exception
+    Return the message of an exception.
+    @return: Message of the exception.
+    @rtype: Unicode
     """
     return self._fmtUnicode (self.message)
 
@@ -114,11 +138,14 @@
 
   def _fmtUnicode (self, text, encoding = None):
     """
-    This function returns a given text as unicode string using an optional
-    encoding or the system's default encoding.
-    @param text: the string to be encoded. If this string is already unicode no
-        modification will take place.
-    @return: unicode representation of @text.
+    Return a given text as unicode string using an optional encoding or the
+    system's default encoding.
+
+    @param text: String to be encoded. If this string is already unicode no
+      modification will take place.
+    @param encoding: Encoding to use (if None, system default encoding will
+      take place)
+    @return: Unicode representation of the text parameter.
     """
     if isinstance (text, types.UnicodeType):
       return text
@@ -178,7 +205,7 @@
   This class should be used for exceptions where a user did something wrong, or
   a situation has occured which isn't dramatic, but the user has to be informed
   of. Example: wrong password or the user has entered non-numeric data into a
-  numeric field, and so on
+  numeric field, and so on.
   """
   def __init__ (self, message):
     gException.__init__ (self, message, 'user')
@@ -207,11 +234,17 @@
 
 def getException (count = None, aType = None, aValue = None, aTrace = None):
   """
+  Return textual information about an exception.
+
   This function creates a tuple (type, name, message, detail) for the last
   exception raised. The optional parameter determines the number of lines
   skipped from the detail traceback.
+
+  The intended use of this function is to get the text to be displayed in error
+  messages.
+
   @param count: number of lines to skip in the traceback
-  @returns: tuple with type, name, message and detail of the last exception.
+  @return: tuple with type, name, message and detail of the last exception.
   """
   (sType, sValue, sTrace) = sys.exc_info ()
   aType  = aType  or sType

Modified: trunk/gnue-common/src/apps/i18n.py
===================================================================
--- trunk/gnue-common/src/apps/i18n.py  2005-03-09 17:54:16 UTC (rev 7144)
+++ trunk/gnue-common/src/apps/i18n.py  2005-03-09 21:49:35 UTC (rev 7145)
@@ -20,9 +20,14 @@
 # Copyright 2001-2005 Free Software Foundation
 #
 # $Id$
+
 """
-Internationalization support
+Internationalization support.
+
address@hidden language: Preferred language of the user running the program.
address@hidden encoding: Encoding to be used for console input and output.
 """
+
 from types import *
 
 import exceptions
@@ -45,7 +50,6 @@
 
 language = None
 encoding = None
-enc_policy = "replace"                  # policy to use if an unicode character
 
 
 # -----------------------------------------------------------------------------
@@ -126,8 +130,8 @@
 
 def translate (message):
   """
-  Translates a message and returns an 8 bit string, encoded with @encoding (the
-  current locale's encoding).  This function is available as the builtin
+  Translates a message and returns an 8 bit string, encoded with L{encoding}
+  (the current locale's encoding).  This function is available as the builtin
   function "_()".
   """
   catalog = __find_catalog ()
@@ -135,7 +139,7 @@
   if catalog is None:
     return message
 
-  return (catalog.ugettext (message)).encode (encoding, enc_policy)
+  return (catalog.ugettext (message)).encode (encoding, 'replace')
 
 
 # -----------------------------------------------------------------------------
@@ -144,24 +148,39 @@
 
 def outconv (message):
   """
-  Encodes a message to @encoding (the current locale's encoding).  This
+  Encodes a message to L{encoding} (the current locale's encoding).  This
   function is available as the builtin function "o()".
   """
   if isinstance (message, UnicodeType):
-    return message.encode (encoding, enc_policy)
+    return message.encode (encoding, 'replace')
   else:
     return message
 
 
 # -----------------------------------------------------------------------------
+# Get the current language
+# -----------------------------------------------------------------------------
+
+def getlanguage ():
+  """
+  Returns the language of the currently acitve locale. This can be changed with
+  L{setcurrentlocale}.
+
+  @return: language of the current locale.
+  """
+  return __userlanguage or 'C'
+
+
+# -----------------------------------------------------------------------------
 # Get the current encoding
 # -----------------------------------------------------------------------------
 
 def getencoding ():
   """
-  This function returns the encoding of the currently active locale. This can
-  be changed with setcurrentlocale.
-  @returns: encoding of the current locale
+  Returns the encoding of the currently active locale. This can be changed with
+  L{setcurrentlocale}.
+
+  @return: encoding of the current locale.
   """
   # For Windows, getlocale () is broken - it returns e.g. ('Hungarian_Hungary',
   # '1250') instead of ('hu_HU', 'cp1250'). So we have to use getdefaultlocale.
@@ -174,29 +193,16 @@
 
 
 # -----------------------------------------------------------------------------
-# Get the current language
+# Get the locale string of the current user
 # -----------------------------------------------------------------------------
 
-def getlanguage ():
+def getuserlocale ():
   """
-  This function return the language of the currently acitve locale. This can be
-  changed with setcurrentlocale.
-  @returns: language of the current locale
-  """
-  return __userlanguage or 'C'
+  Try to find out which locale the user is using.  This is always the locale of
+  the user running the program and is not touched by setcurrentlocale.
 
-
-# ---------------------------------------------------------------------------
-# Get the locale string of the current user
-# ---------------------------------------------------------------------------
-
-def getuserlocale ():
+  @return: localestring of the user's locale, i.e. address@hidden
   """
-  This function tries to find out which locale the user is using. This is
-  always the locale of the user running the program and is not touched by
-  setcurrentlocale.
-  @returns: localestring of the user's locale, i.e. address@hidden
-  """
 
   # *Actually* the following is very much what locale.getdefaultlocale should
   # do anyway.  However, that function is broken for $LANGUAGE containing a
@@ -219,17 +225,20 @@
   return result
 
 
-# ---------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 # Change the current locale
-# ---------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 
 def setcurrentlocale (newLocale):
   """
-  This function changes the current locale. If it fails it tries to succeed
-  using a more general form of the requested locale, i.e. if 'address@hidden'
-  fails, 'de_AT' will be tried next. If that fails too 'de' will be tried.
+  Set the current locale.
+  
+  If it fails it tries to succeed using a more general form of the requested
+  locale, i.e. if 'address@hidden' fails, 'de_AT' will be tried next. If that 
fails
+  too, 'de' will be tried.
+
   @param newLocale: string of the locale to be set, e.g. address@hidden
-      (full blown) or 'de_AT' or 'en_AU'
+    (full blown) or 'de_AT' or 'en_AU'
   """
   if newLocale is None:
     newLocale = ''

Modified: trunk/gnue-common/src/apps/plugin.py
===================================================================
--- trunk/gnue-common/src/apps/plugin.py        2005-03-09 17:54:16 UTC (rev 
7144)
+++ trunk/gnue-common/src/apps/plugin.py        2005-03-09 21:49:35 UTC (rev 
7145)
@@ -54,6 +54,7 @@
 imported, but no submodules of it. This is useful to exclude, for example,
 abstract base drivers.
 """
+
 from types import *
 
 import os