onaplogging: Docstrings, refactor, type hinting

Identify and document functionalities. Describe parameters
and their types, exception descriptions and types, extensions,
return types and descriptions. Preserve Python 2.7 and 3.x
compatibility. Add Python 2.7 to Tox testing. Extract code to utility files.
Add properties for readability and maintainability, fix naming conventions.
Deprecate old methods and attributes.

Issue-ID: REQ-420
Signed-off-by: Eli Halych <illia.halych@t-mobile.pl>
Change-Id: I19297e40fad743ec68aa04612ecbb11f61f2abec

1 files changed, 88 insertions, 29 deletions

diff --git a/pylog/onaplogging/markerFormatter.py b/pylog/onaplogging/markerFormatter.py
index a322e29..d0da695 100644
--- 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