[svn r37930] Docstrings.

--HG--
branch : trunk

py/log/consumer.py

@@ -2,15 +2,20 @@ import py
 import sys
 
 class File(object): 
+    """ log consumer wrapping a file(-like) object
+    """
     def __init__(self, f): 
         assert hasattr(f, 'write')
         assert isinstance(f, file) or not hasattr(f, 'open') 
         self._file = f 
 
     def __call__(self, msg): 
+        """ write a message to the log """
         print >>self._file, str(msg)
 
 class Path(object): 
+    """ log consumer able to write log messages into
+    """
     def __init__(self, filename, append=False, delayed_create=False,
             buffering=1): 
         self._append = append
@@ -25,17 +30,22 @@ class Path(object):
         self._file = f
 
     def __call__(self, msg):
+        """ write a message to the log """
         if not hasattr(self, "_file"):
             self._openfile()
         print >> self._file, msg
 
 def STDOUT(msg): 
+    """ consumer that writes to sys.stdout """
     print >>sys.stdout, str(msg) 
 
 def STDERR(msg): 
+    """ consumer that writes to sys.stderr """
     print >>sys.stderr, str(msg)
 
 class Syslog:
+    """ consumer that writes to the syslog daemon """
+
     for priority in "LOG_EMERG LOG_ALERT LOG_CRIT LOG_ERR LOG_WARNING LOG_NOTICE LOG_INFO LOG_DEBUG".split():
         try:
             exec("%s = py.std.syslog.%s" % (priority, priority))
@@ -48,10 +58,12 @@ class Syslog:
             self.priority = priority
 
     def __call__(self, msg):
+        """ write a message to the log """
         py.std.syslog.syslog(self.priority, str(msg))
         
     
 def setconsumer(keywords, consumer): 
+    """ create a consumer for a set of keywords """
     # normalize to tuples 
     if isinstance(keywords, str): 
         keywords = tuple(map(None, keywords.split()))

py/log/logger.py

@@ -61,9 +61,11 @@ class Logger(object):
         setattr(self, name, Processor(self, name, dest))
 
 def get(ident="global", **kwargs): 
+    """ return the Logger with id 'ident', instantiating if appropriate """
     try:
         log = Logger._key2logger[ident]
     except KeyError:
         log = Logger(ident)
     log.ensure_sub(**kwargs)
     return log 
+

py/log/producer.py

@@ -49,11 +49,18 @@ class Producer(object):
         return producer 
     
     def __call__(self, *args):
+        """ write a message to the appropriate consumer(s) """
         func = self.get_consumer(self.keywords)
         if func is not None: 
             func(self.Message(self.keywords, args))
    
     def get_consumer(self, keywords): 
+        """ return a consumer matching keywords
+        
+            tries to find the most suitable consumer by walking, starting from
+            the back, the list of keywords, the first consumer matching a
+            keyword is returned (falling back to py.log.default)
+        """
         for i in range(len(self.keywords), 0, -1): 
             try: 
                 return self.keywords2consumer[self.keywords[:i]]
@@ -62,6 +69,7 @@ class Producer(object):
         return self.keywords2consumer.get('default', default_consumer)
 
     def set_consumer(self, consumer): 
+        """ register a consumer matching our own keywords """
         self.keywords2consumer[self.keywords] = consumer 
 
 default = Producer('default')
@@ -74,6 +82,7 @@ def _setstate(state):
     Producer.keywords2consumer.update(state) 
 
 def default_consumer(msg): 
+    """ the default consumer, prints the message to stdout (using 'print') """
     print str(msg) 
 
 Producer.keywords2consumer['default'] = default_consumer