Changeset 1858 for trunk/python/logging.py

Timestamp:

08/05/10 11:46:40 (14 years ago)

Author:

Malte Marquarding

Message:

Adde more API documentation

File:

• trunk/python/logging.py (modified) (6 diffs)

trunk/python/logging.py

@@ -1 @@
-__all__ = ["asaplog", "print_log", "print_log_dec"]
+"""This module presents a logging abstraction layer on top of casa.
+"""
+__all__ = ["asaplog", "print_log", "print_log_dec", "AsapLogger"]
 
 from asap.env import is_casapy
@@ -10 +12 @@
 
 
-class _asaplog(object):
-    """Wrapper object to allow for both casapy and asap logging"""
+class AsapLogger(object):
+    """Wrapper object to allow for both casapy and asap logging.
+
+    Inside casapy this will connect to `taskinit.casalog`. Otherwise it will
+    create its own casa log sink.
+
+    .. note:: Do instantiate a new one - use the :obj:`asaplog` instead.
+    
+    """
     def __init__(self):
         self._enabled = False
@@ -25 +34 @@
         """Post the messages to the logger. This will clear the buffered
         logs.
+
+        Parameters:
+
+            level:  The log level (severity). One of INFO, WARN, ERROR.
+
         """
         if not self._enabled:
@@ -41 +55 @@
 
     def push(self, msg, newline=True):
-        """Push logs into the buffer. post needs to be called to send them."""
+        """Push logs into the buffer. post needs to be called to send them.
+
+        Parameters:
+
+            msg:        the log message (string)
+
+            newline:    should we terminate with a newline (default yes)
+
+        """
         from asap import rcParams
         if self._enabled:
@@ -58 +80 @@
         self._enabled = flag
 
-asaplog = _asaplog()
+asaplog = AsapLogger()
+"""Default asap logger"""
 
 def print_log_dec(f, level='INFO'):
+    """Decorator which posts log at completion of the wrapped method.
+    Example::
+
+        @print_log_dec
+        def test(self):
+            do_stuff()
+            asaplog.push('testing...', False)
+            do_more_stuff()
+            asaplog.push('finished')
+    """
     @wraps_dec(f)
     def wrap_it(*args, **kw):
@@ -69 +102 @@
 
 def print_log(level='INFO'):
-    """Alias for asaplog.post."""
+    """Alias for asaplog.post(level)"""
     asaplog.post(level)