onaplogging: Docstrings, refactor, type hinting

[logging-analytics.git] / pylog / onaplogging / markerFormatter.py

diff --git a/pylog/onaplogging/markerFormatter.py b/pylog/onaplogging/markerFormatter.py
index a322e29..d0da695 100644 (file)
--- a/pylog/onaplogging/markerFormatter.py
+++ b/pylog/onaplogging/markerFormatter.py
@@ -12,57 +12,116 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import sys
 import logging
-from .marker import MARKER_TAG
-from .marker import Marker
+from logging import LogRecord
+from typing import Optional
+
+from onaplogging.utils.styles import MARKER_OPTIONS
+from onaplogging.utils.system import is_above_python_2_7, is_above_python_3_2
+
+from .marker import Marker, MARKER_TAG
 from .colorFormatter import BaseColorFormatter
 
 
 class MarkerFormatter(BaseColorFormatter):
+    """Formats coloring styles based on a marker.
 
-    def __init__(self, fmt=None, datefmt=None, colorfmt=None, style='%'):
+    If `fmt` is not supplied, the `style` is used.
 
-        if sys.version_info > (3, 2):
-            super(MarkerFormatter, self).__init__(
-                fmt=fmt, datefmt=datefmt, colorfmt=colorfmt, style=style)
-        elif sys.version_info > (2, 7):
-            super(MarkerFormatter, self).__init__(
-                fmt=fmt, datefmt=datefmt, colorfmt=colorfmt)
-        else:
-            BaseColorFormatter.__init__(self, fmt, datefmt, colorfmt)
+    Extends:
+        BaseColorFormatter
+    Properties:
+        marker_tag: a marker to be applied.
+        temp_fmt  : keeps initial format to be reset to after formatting.
+    Args:
+        fmt       : human-readable format.                    Defaults to None.
+        datefmt   : ISO8601-like (or RFC 3339-like) format.   Defaults to None.
+        colorfmt  : color schemas for logging levels.         Defaults to None.
+        style     : '%', '{' or '$' formatting.               Defaults to '%'.
+                      Added in Python 3.2.
+    """
+
+    @property
+    def marker_tag(self):
+        # type: () -> str
+        return self._marker_tag
+
+    @property
+    def temp_fmt(self):
+        # type: () -> str
+        return self._temp_fmt
+
+    @marker_tag.setter
+    def marker_tag(self, value):
+        # type: (str) -> None
+        self._marker_tag = value
 
-        self._marker_tag = "%(marker)s"
+    @temp_fmt.setter
+    def temp_fmt(self, value):
+        # type: (str) -> None
+        self._temp_fmt = value
 
-        if self.style == "{":
-            self._marker_tag = "{marker}"
-        elif self.style == "$":
-            self._marker_tag = "${marker}"
+    def __init__(self,
+                 fmt=None,          # type: Optional[str]
+                 datefmt=None,      # type: Optional[str]
+                 colorfmt=None,     # type: Optional[dict]
+                 style='%'):        # type: Optional[str]
 
-        self._tmpFmt = self._fmt
+        if is_above_python_3_2():
+            super(MarkerFormatter, self).\
+            __init__(fmt=fmt,  # noqa: E122
+                     datefmt=datefmt,
+                     colorfmt=colorfmt,
+                     style=style)  # added in Python 3.2+
+
+        elif is_above_python_2_7():
+            super(MarkerFormatter, self).\
+            __init__(fmt=fmt,  # noqa: E122
+                     datefmt=datefmt,
+                     colorfmt=colorfmt)
+
+        else:
+            BaseColorFormatter.\
+            __init__(self, fmt, datefmt, colorfmt)  # noqa: E122
+
+        self.marker_tag = MARKER_OPTIONS[self.style]
+        self.temp_fmt = self._fmt
 
     def format(self, record):
+        # type: (LogRecord) -> str
+        """Marker formatter.
+
+        Use it to apply the marker from the LogRecord record to the formatter
+        string `fmt`.
 
+        Args:
+            record  : an instance of a logged event.
+        Returns:
+            str     : "colored" text (formatted text).
+        """
         try:
-            if self._fmt.find(self._marker_tag) != -1 \
-                    and hasattr(record, MARKER_TAG):
+
+            if  self._fmt.find(self.marker_tag) != -1 and \
+                hasattr(record, MARKER_TAG):
                 marker = getattr(record, MARKER_TAG)
 
                 if isinstance(marker, Marker):
-                    self._fmt = self._fmt.replace(
-                        self._marker_tag, marker.getName())
-            elif self._fmt.find(self._marker_tag) != -1 \
-                    and not hasattr(record, MARKER_TAG):
+                    self._fmt = self._fmt.replace(self.marker_tag,
+                                                  marker.name)
 
-                self._fmt = self._fmt.replace(self._marker_tag, "")
+            elif self._fmt.find(self.marker_tag) != -1 and \
+                 not hasattr(record, MARKER_TAG):
+                self._fmt = self._fmt.replace(self.marker_tag, "")
 
-            if sys.version_info > (3, 2):
-                self._style = logging._STYLES[self.style][0](self._fmt)
+            if is_above_python_3_2():
+                StylingClass = logging._STYLES[self.style][0]
+                self.style = StylingClass(self._fmt)
 
-            if sys.version_info > (2, 7):
+            if is_above_python_2_7():
+                # includes Python 3.2+ style attribute
                 return super(MarkerFormatter, self).format(record)
             else:
                 return BaseColorFormatter.format(self, record)
 
         finally:
-            self._fmt = self._tmpFmt
+            self._fmt = self.temp_fmt