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, 98 insertions, 20 deletions

diff --git a/pylog/onaplogging/marker/markerHandler.py b/pylog/onaplogging/marker/markerHandler.py
index e9ce810..36934a8 100644
--- a/pylog/onaplogging/marker/markerHandler.py
+++ b/pylog/onaplogging/marker/markerHandler.py
@@ -12,40 +12,118 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import sys
+from logging import LogRecord
 from logging.handlers import SMTPHandler
-from .marker import matchMarkerHelp
+from typing import Tuple, List, Optional, Union
+
+from onaplogging.utils.system import is_above_python_2_7, is_above_python_3_2
+
+from .marker import match_markers, Marker
 
 
 class MarkerNotifyHandler(SMTPHandler):
+    """Handler for email notification.
+
+    Wraps logging.handler.SMTPHandler and extends it by sending only such
+    notifications which contain certain markers.
+
+    Extends:
+        SMTPHandler
+    Property:
+        markers: A marker or a list of markers.
+    Args:
+        mailhost: A (host, port) tuple.
+        fromaddr: The sender of the email notification.
+        toaddrs: Email notification recepient(s).
+        subject: Email subject.
+        credentials: A (username, password) tuple.
+        secure: For example (TLS). It is used when the
+                                  credentials are supplied.
+        timout: Default is 5.0 seconds. Python version 3.2+
+        markers: A marker or a list of markers.
+    """
+
+    @property
+    def markers(self):
+        # type: () -> Union[Marker, List[Marker]]
+        return self._markers
+
+    @markers.setter
+    def markers(self, value):
+        # type: ( Union[Marker, List[Marker]] ) - None
+        self._markers = value
+
+    def __init__(self,
+                 mailhost,          # type: Tuple
+                 fromaddr,          # type: str
+                 toaddrs,           # type: Union[List[str], str]
+                 subject,           # type: Tuple
+                 credentials=None,  # type: Tuple
+                 secure=None,       # type: Optional[Tuple]
+                 timeout=5.0,       # type: Optional[float]
+                 markers=None     # type: Optional[Union[Marker, List[Marker]]]
+                 ):
+
+        if is_above_python_3_2():
+            super(MarkerNotifyHandler, self). \
+            __init__(  # noqa: E122
+                mailhost,
+                fromaddr,
+                toaddrs,
+                subject,
+                credentials,
+                secure,
+                timeout)
+
+        elif is_above_python_2_7():
+            super(MarkerNotifyHandler, self). \
+            __init__(  # noqa: E122
+                mailhost,
+                fromaddr,
+                toaddrs,
+                subject,
+                credentials,
+                secure)
 
-    def __init__(self, mailhost, fromaddr, toaddrs, subject,
-                 credentials=None, secure=None, timeout=5.0, markers=None):
-
-        if sys.version_info > (3, 2):
-            super(MarkerNotifyHandler, self).__init__(
-                mailhost, fromaddr, toaddrs, subject,
-                credentials, secure, timeout)
-        elif sys.version_info > (2, 7):
-            super(MarkerNotifyHandler, self).__init__(
-                mailhost, fromaddr, toaddrs, subject,
-                credentials, secure)
         else:
             SMTPHandler.__init__(self,
-                                 mailhost, fromaddr, toaddrs, subject,
-                                 credentials, secure)
+                                 mailhost,
+                                 fromaddr,
+                                 toaddrs,
+                                 subject,
+                                 credentials,
+                                 secure)
 
         self.markers = markers
 
     def handle(self, record):
+        # type: (LogRecord) -> bool
+        """
+        Handle a LogRecord record. Send an email notification.
+        """
+        return self.send_notification(record)
+
+    def send_notification(self, record):
+        # type: (LogRecord) -> bool
+        """Email notification handler.
 
-        if self.markers is None:
+        Matches the record with the specific markers set for email
+        notifications. Sends an email notification if that marker(s) matched.
+
+        Args:
+            record (LogRecord): A record that might contain a marker.
+        Returns:
+            bool: Whether a record was passed for emission (to be sent).
+        """
+
+        if  hasattr(self, "markers") and \
+            self.markers is None:
             return False
 
-        if matchMarkerHelp(record, self.markers):
-            if sys.version_info > (2, 7):
+        if match_markers(record, self.markers):
+
+            if is_above_python_2_7():
                 return super(MarkerNotifyHandler, self).handle(record)
-            else:
-                return SMTPHandler.handle(self, record)
+            return SMTPHandler.handle(self, record)
 
         return False