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

4 files changed, 147 insertions, 0 deletions

diff --git a/pylog/onaplogging/utils/__init__.py b/pylog/onaplogging/utils/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/pylog/onaplogging/utils/__init__.py
diff --git a/pylog/onaplogging/utils/styles.py b/pylog/onaplogging/utils/styles.py
new file mode 100644
index 0000000..e445aee
--- /dev/null
+++ b/pylog/onaplogging/utils/styles.py
@@ -0,0 +1,84 @@
+# Copyright (c) 2020 Deutsche Telekom.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+"""These are ANSI shell coloring codes used to format strings.
+
+[ begins the color definition. \033 starts the escape sequence.
+[\0330m is the default color of the shell that closes the escape sequence.
+
+`FMT_STR` takes the color as its first parameter (int). As the second
+parameter its takes the text (str).
+
+TL;DR
+    Examples on ANSI colors, attributes, backgrounds and foregrounds:
+    https://stackoverflow.com/a/28938235/7619961
+"""
+
+COLOR_TAG = "color"
+HIGHLIGHT_TAG = "highlight"
+ATTRIBUTE_TAG = "attribute"
+
+RESET = "\033[0m"
+FMT_STR = "\033[%dm%s"
+
+ATTRIBUTES = {
+
+    'normal': 0,
+    'bold': 1,
+    'underline': 4,
+    'blink': 5,
+    'invert': 7,
+    'hide': 8,
+
+}
+
+HIGHLIGHTS = {
+
+    'black': 40,
+    'red': 41,
+    'green': 42,
+    'yellow': 43,
+    'blue': 44,
+    'purple': 45,
+    'cyan': 46,
+    'white': 47,
+
+}
+
+COLORS = {
+
+    'black': 30,
+    'red': 31,
+    'green': 32,
+    'yellow': 33,
+    'blue': 34,
+    'purple': 35,
+    'cyan': 36,
+    'white': 37,
+
+}
+
+"""
+MDC and MARKER options are used only with Python starting 3.2 due to an update
+in the logging module. This allows the use of %-formatting, :meth:`str.format`
+(``{}``) formatting or :class:`string.Template` in the format string.
+"""
+
+MARKER_OPTIONS = {
+    "%": "%(marker)s",
+    "{": "{marker}",
+    "$": "${marker}"
+}
+
+MDC_OPTIONS = {
+    "%": "%(mdc)s",
+    "{": "{mdc}",
+    "$": "${mdc}"
+}
diff --git a/pylog/onaplogging/utils/system.py b/pylog/onaplogging/utils/system.py
new file mode 100644
index 0000000..cfe49a1
--- /dev/null
+++ b/pylog/onaplogging/utils/system.py
@@ -0,0 +1,31 @@
+# Copyright (c) 2020 Deutsche Telekom.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+import sys
+
+
+def is_above_python_3_2():
+    # type: () -> bool
+    """Check if code is running at least on Python 3.2 version.
+
+    Returns:
+        bool: True if it's at least 3.2 version, False otherwise
+    """
+    return sys.version_info >= (3, 2, 0, "final", 0)
+
+
+def is_above_python_2_7():
+    # type: () -> bool
+    """Check if code is running at least on Python 2.7 version.
+
+    Returns:
+        bool: True if it's at least 2.7 version, False otherwise
+    """
+    return sys.version_info >= (2, 7, 0, "final", 0)
diff --git a/pylog/onaplogging/utils/tools.py b/pylog/onaplogging/utils/tools.py
new file mode 100644
index 0000000..0cb0129
--- /dev/null
+++ b/pylog/onaplogging/utils/tools.py
@@ -0,0 +1,32 @@
+# Copyright (c) 2020 Deutsche Telekom.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+import yaml
+
+from deprecated import deprecated
+
+
+def yaml_to_dict(filepath):
+    # type: (str) -> dict
+    """YAML to Python dict converter.
+
+    Args:
+        filepath    : The filepath to a YAML file.
+    Returns:
+        dict        : Python dictionary object.
+    """
+    with open(filepath, 'rt') as f:
+        return yaml.load(f.read())
+
+
+@deprecated(reason="Will be removed. Call yaml_to_dict(filepath) instead.")
+def _yaml2Dict(filename):
+    """YAML to dict. See yaml_to_dict(filepath)."""
+    return yaml_to_dict(filename)