onaplogging: Docstrings, refactor, type hinting

[logging-analytics.git] / pylog / onaplogging / marker / markerFilter.py

diff --git a/pylog/onaplogging/marker/markerFilter.py b/pylog/onaplogging/marker/markerFilter.py
index 4ae5478..a381d8e 100644 (file)
--- a/pylog/onaplogging/marker/markerFilter.py
+++ b/pylog/onaplogging/marker/markerFilter.py
@@ -12,21 +12,57 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import sys
-from logging import Filter
-from marker import matchMarkerHelp
+from logging import Filter, LogRecord
+from warnings import warn
+from typing import List, Optional, Union
+
+from onaplogging.utils.system import is_above_python_2_7
+
+from .marker import match_markers, Marker
 
 
 class MarkerFilter(Filter):
+    """Marker filtering.
+
+    Extends:
+        logging.Filter
+    Properties:
+        marker_to_match (Marker/list): a marker of list of markers.
+    Methods
+        filter: Filter records by the current filter marker(s).
+    """
+
+    @property
+    def markers_to_match(self):
+        # type: () -> Union[Marker, List[Marker]]
+        return self.markersToMatch  # TODO renamed - deprecated
 
-    def __init__(self, name="", markers=None):
-        if sys.version_info > (2, 7):
+    @markers_to_match.setter
+    def markers_to_match(self, value):
+        # type: ( Union[Marker, List[Marker]] ) -> None
+        self.markersToMatch = value
+
+    def __init__(self,
+                 name="",        # type: str
+                 markers=None):  # type: Optional[Union[Marker, List[Marker]]]
+
+        if is_above_python_2_7():
             super(MarkerFilter, self).__init__(name)
+
         else:
             Filter.__init__(self, name)
 
-        self.markerToMatch = markers
+        warn("markersToMatch attribute will be replaced by a property. "
+              "Use markers_to_match property instead.", DeprecationWarning)
+        self.markers_to_match = markers
 
     def filter(self, record):
-        # compare filter's markers with record's marker
-        return matchMarkerHelp(record, self.markerToMatch)
+        # type: (LogRecord) -> bool
+        """Filter by looking for a marker match.
+
+        Args:
+            record: A record to match with the filter(s).
+        Returns:
+            bool: Whether the record matched with the filter(s)
+        """
+        return match_markers(record, self.markers_to_match)