r5030 - in trunk/gnue-common/src: . apps events utils

[jamest]

Author: jamest
Date: 2004-01-09 22:04:52 -0600 (Fri, 09 Jan 2004)
New Revision: 5030

Modified:
   trunk/gnue-common/src/GCConfig.py
   trunk/gnue-common/src/__init__.py
   trunk/gnue-common/src/apps/GBaseApp.py
   trunk/gnue-common/src/apps/GClientApp.py
   trunk/gnue-common/src/events/Event.py
   trunk/gnue-common/src/events/EventAware.py
   trunk/gnue-common/src/events/EventController.py
   trunk/gnue-common/src/utils/TextUtils.py
Log:
Event.drop() fix
start of adding epydoc docstrings


Modified: trunk/gnue-common/src/GCConfig.py
===================================================================
--- trunk/gnue-common/src/GCConfig.py   2004-01-09 04:49:41 UTC (rev 5029)
+++ trunk/gnue-common/src/GCConfig.py   2004-01-10 04:04:52 UTC (rev 5030)
@@ -22,11 +22,14 @@
 # GCConfig.py
 #
 # DESCRIPTION:
+#
 # Valid configuration options that apply to all GNUe tools
 # (appears under [common] section in gnue.conf or
 # can appear in each individual tool section)
 #
 
+
+
 from gnue.common.formatting import GTypecast
 
 ConfigOptions = (

Modified: trunk/gnue-common/src/__init__.py
===================================================================
--- trunk/gnue-common/src/__init__.py   2004-01-09 04:49:41 UTC (rev 5029)
+++ trunk/gnue-common/src/__init__.py   2004-01-10 04:04:52 UTC (rev 5030)
@@ -31,6 +31,14 @@
 #   4. Set _release = 0
 #   5. Commit to CVS
 
+
+
+"""
+GNUe Common is a set of python modules that provide a 
+large amount of functionality usefull in many python 
+programs.
+"""
+
 _version = (0,5,2)
 _release = 1
 

Modified: trunk/gnue-common/src/apps/GBaseApp.py
===================================================================
--- trunk/gnue-common/src/apps/GBaseApp.py      2004-01-09 04:49:41 UTC (rev 
5029)
+++ trunk/gnue-common/src/apps/GBaseApp.py      2004-01-10 04:04:52 UTC (rev 
5030)
@@ -54,7 +54,15 @@
 from gnue.common.datasources import GConnections
 
 class GBaseApp:
+  """
+  The base class of the various GNUe application classes.
 
+  GBaseApp Provides the following features
+    - Command line argument parsing
+    - Run time debug output levels
+    - An integrated profiler
+    - An integrated debugger
+  """
   # Attributes to be overwritten by subclasses
   VERSION = "0.0.0"
   NAME = "GNUe Application"

Modified: trunk/gnue-common/src/apps/GClientApp.py
===================================================================
--- trunk/gnue-common/src/apps/GClientApp.py    2004-01-09 04:49:41 UTC (rev 
5029)
+++ trunk/gnue-common/src/apps/GClientApp.py    2004-01-10 04:04:52 UTC (rev 
5030)
@@ -33,7 +33,14 @@
 from gnue.common.apps.GBaseApp import GBaseApp
 
 class GClientApp(GBaseApp):
+  """
+  A class designed to be the basis of client type
+  applications.
 
+  GBaseApp Provides the following features
+    - Connection login handler
+  """
+
   #
   #  Set the login handler for this session
   #

Modified: trunk/gnue-common/src/events/Event.py
===================================================================
--- trunk/gnue-common/src/events/Event.py       2004-01-09 04:49:41 UTC (rev 
5029)
+++ trunk/gnue-common/src/events/Event.py       2004-01-10 04:04:52 UTC (rev 
5030)
@@ -37,8 +37,38 @@
 #   event.y == 2, and event.object == MyObject
 #
 class Event:
+  """
+  An Event is the actual event object passed back and forth between the event
+  listeners.
+
+  Any parameters passed to the Event's __init__ are added as attributes of the
+  event. The first attribute, however, should always be the case-sensitive
+  event name.
+
+  Creating an Event:
+
+  >>> myEvent = Event('myEventName', color='Blue', x=1, y=2)
+  >>> myEvent.color
+  'Blue'
+  >>> myEvent.x
+  1
+  >>> myEvent.y
+  2
+  """
+
   def __init__(self, event, data=None, **parms):
-
+    """
+    @param event: The name of the event.  GNUe event listeners
+                  register the names of the events they wish to 
+                  receive.
+    @type event: string
+    @param data: B{OBSOLETE: Do not use}
+    @param parms: Allows the event to accept any argument names you like.
+                  Examples would be things like
+                     - caller=self
+                     - x=15
+                     - vals={'name':'Bob', 'title':'Mr'}
+    """
     self.__dict__.update(parms)
 
     # TODO: Get rid of data=
@@ -51,22 +81,63 @@
     self.__errortext__ = ""
     self.__after__ = []
 
-
   def getResult(self):
+    """
+    Returns the result value stored in the event by the L{setResult} function.
+    @return: The result value of the event.
+    @rtype: Any
+    """
     return self.__result__
 
   def setResult(self, value):
+    """
+    Can be used by an event listener to assign a return value to an event.
+    The result will be returned by the event controller's
+    L{dispatchEvent<gnue.common.events.EventController.EventController>} 
function.
+    It can also be obtained by the L{getResult} function.
+
+    @param value: The result value to assign to the event.  It can 
+                  be anything that is concidered valid python.
+    """
     self.__result__ = value
 
   def getEvent(self):
+    """
+    Returns the name of the event.
+    @return: The name of the event
+    @rtype: string
+    """
     return self.__event__
 
   def drop(self):
-    self.__dropped__ = 0
+    """
+    When called the event will be dropped.  No additional
+    event listeners will receive the event.
+    """
+    self.__dropped__ = 1
 
   def setError(self, text = ""):
+    """
+    Sets the event error flag.  Setting the error
+    also causes the event to be dropped in the
+    same mannor as the L{drop} function.
+
+    @param text: Text describing the error.
+    @type text: string
+    """
     self.__error__ = 1
     self.__errortext__ = text
 
   def dispatchAfter(self, *args, **parms):
+    """
+    Adds an event to the event queue that will be 
+    dispatched upon this events completion.  The arguments
+    to this function match those used in creating an event.
+
+    Sample Usage:
+
+    >>> from gnue.common.events.Event import *
+    >>> myEvent = Event('myEventName', color='Blue', x=1, y=2)
+    >>> myEvent.dispatchAfter('theNextEvent',name='FSF')
+    """    
     self.__after__.append((args, parms))

Modified: trunk/gnue-common/src/events/EventAware.py
===================================================================
--- trunk/gnue-common/src/events/EventAware.py  2004-01-09 04:49:41 UTC (rev 
5029)
+++ trunk/gnue-common/src/events/EventAware.py  2004-01-10 04:04:52 UTC (rev 
5030)
@@ -26,6 +26,7 @@
 # NOTES:
 #
 
+# TODO: No longer needed?  
 from gnue.common.apps import GDebug
 import string
 
@@ -34,7 +35,29 @@
 # Base for an object that sends and receives events
 #
 class EventAware:
+  """
+  The base class for an object that sends and receives events
 
+  Sample Usage::
+
+    from gnue.common import events
+    class myClass(events.EventAware):
+      def __init__(self)
+        self.eventController = events.EventController()
+        events.EventAware.__init__(self, self.eventController)
+        self.registerEventListeners( {
+                             'myEvent1'           : self.eventOneHandler,
+                             'myEvent2'           : self.eventTwoHandler,
+                             })
+    
+      def eventOneHandler(self, event)
+        print "I'm an event named ", event.getEvent()
+    
+      def eventTwoHandler(self, event)
+        print "My event is named ", event.getEvent()
+
+  """
+
   def __init__(self, controller):
     self.__controller = controller
     self.dispatchEvent = controller.dispatchEvent

Modified: trunk/gnue-common/src/events/EventController.py
===================================================================
--- trunk/gnue-common/src/events/EventController.py     2004-01-09 04:49:41 UTC 
(rev 5029)
+++ trunk/gnue-common/src/events/EventController.py     2004-01-10 04:04:52 UTC 
(rev 5030)
@@ -33,7 +33,10 @@
 from Event import Event
 
 class EventController(EventAware):
-
+  """
+  An EventController is responsible for dispatching events to 
+  registered listeners.
+  """
   def __init__(self):
     # Note: Don't call EventAware.__init__
     #   ... that would be fugly.
@@ -41,8 +44,14 @@
     # Store a dictionary of registered events
     self.__incomingEvents = {}
 
-
+  
   def registerEventListeners(self, events):
+    """
+    Registers an event listener for a specific event
+    
+    @param events: A dictionary of {'eventName': listenerFuction} pairs
+    @type events: dict
+    """
     for event in events.keys():
       try:
         self.__incomingEvents[event].append(events[event])
@@ -50,9 +59,19 @@
         self.__incomingEvents[event] = [events[event]]
 
   def startCachingEvents(self):
+    """
+    Causes the event controller to start storing events
+    rather than dispatching them.  It will continue to 
+    store events until L{stopCachingEvents} is called.
+    """
     self.__cache = []
 
   def stopCachingEvents(self):
+    """
+    Notifies the event controller that is should 
+    start processing events again.  Any previously 
+    cached events are dispatched.
+    """
     cache = self.__cache
     del self.__cache
     for event, arg, parms in cache:

Modified: trunk/gnue-common/src/utils/TextUtils.py
===================================================================
--- trunk/gnue-common/src/utils/TextUtils.py    2004-01-09 04:49:41 UTC (rev 
5029)
+++ trunk/gnue-common/src/utils/TextUtils.py    2004-01-10 04:04:52 UTC (rev 
5030)
@@ -35,7 +35,25 @@
 
 # very simple lineWrap
 def lineWrap(message,maxWidth, preserveNewlines=1, alignment=ALIGN_LEFT, 
eol=1):
+  """
+  A simple linewrap function.
 
+  @param message:   The string to wrap
+  @param maxWidth:  The maximum string width allowed.
+  @param preserveNewlines: If true then newlines are left in the string 
+                           otherwise they are removed.
+  @param alignment: The alignment of the returned string based upon 
+                    a width of maxWidth.  
+
+                    Possible values (ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER)
+
+  @param eol: If true then the last character of the return value 
+              will be a newline
+
+  @return: The properly wrapped text string.
+  @rtype: string
+  """
+
   text = ""
 
   temptext = string.strip(str(message))
@@ -77,7 +95,28 @@
 
 
 def textToMeasurement(text, multiplier=1):
-  # pt
+  """
+  Converts most standard measurements to inches.
+
+  Sample Usage:
+
+  >>> textToMeasurement('72pt')
+  1.0
+  >>> # convert to 72 point output 
+  ... textToMeasurement('1.27cm',72)
+  36.0
+  
+  @param text: A string containing the measurement to convert
+               The following measurements are accepted
+               (pt, cm, mm, in)
+  @type text: string
+  @param multiplier: A multiplier used to adjust the output
+                     to values other inches.
+  @type multipler: number
+
+  @return: The converted value
+  @rtype: number
+  """
   if text[-1] in ('0','1','2','3','4','5','6','7','8','9'):
     value = float(text) / 72 * multiplier
   else:
@@ -89,10 +128,21 @@
   return value
 
 
-#
-# Convert an integer to a roman numeral
-#
 def intToRoman(num):
+  """
+  Convert an integer to a roman numeral.
+
+  Sample Usage:
+
+  >>> intToRoman(1999)
+  'MCMXCIX'
+
+  @param num: The number to convert
+  @type num: integer
+
+  @return: The roman numeral equivalent.
+  @rtype: string
+  """
   n = int(num) # just in case
   rv = ""
   for dec, rom in (
@@ -107,11 +157,22 @@
   return rv
 
 
-#
-# Convert a number to "dollar" notation (suitable for use on checks)
-# e.g., 123.24 --> "One Hundred Twenty Three and 24/100"
-#
 def dollarToText(num):
+  """
+  Convert a number to "dollar" notation (suitable for use on checks)
+  e.g., 123.24 --> "One Hundred Twenty Three and 24/100"
+
+  Sample Usage:
+
+  >>> dollarToText(1120.15)
+  'One Thousand One Hundred Twenty and 15/100'
+
+  @param num: The numeric amount
+  @type num: number
+
+  @return: The full text equivalent of the number.
+  @rtype: string
+  """
   whole = int(num)
   cents = round((num-whole)*100)
   rv = 'and %02d/100' % cents
@@ -146,8 +207,27 @@
 
 
 # Comify a number
-# (e.g., print -9900 as -9,900.00)
 def comify(num, decimals=2, parenthesis=0):
+  """
+  Comify a number (e.g., print -9900 as -9,900.00)
+
+  Sample Usage:
+
+  >>> comify(-9999.934, 2)
+  '-9,999.93'
+  >>> comify(-9999.934, 2, 1)
+  '(9,999.93)'
+
+  @param num: The number to reformat
+  @type num: number
+  @param decimals: The number of decimal places to retain
+  @type decimals: number
+  @param parenthesis: If true then negative numbers will be returned inside 
parenthesis
+  @type  parenthesis: number
+
+  @return: A properly formatted number
+  @rtype: string
+  """
   neg = num < 0
   num = abs(num)
   whole, dec = (string.split(string.strip(("%%12.%sf" % decimals) % 
abs(num)),'.') + [""])[:2]