refactor(LOGGING): extract base class

Author: niall-byrne

pi_portal/modules/configuration/__init__.py

@@ -1,4 +1,3 @@
 """Configuration Modules for the pi_portal cli."""
 
 from . import state, user_config
-from .logger import LoggingConfiguration

pi_portal/modules/configuration/logger.py

@@ -0,0 +1,57 @@
+"""LoggerConfigurationBase class."""
+
+import abc
+import logging
+from typing import Optional
+
+from pi_portal.modules.configuration import state
+
+
+class LoggerConfigurationBase(abc.ABC):
+  """Pi Portal base logging configuration."""
+
+  format_str: str
+  formatter: logging.Formatter
+  running_state: state.State
+
+  def __init__(self) -> None:
+    self.running_state = state.State()
+    self.level = self.running_state.log_level
+
+  def configure(
+      self,
+      log: logging.Logger,
+      file_name: Optional[str] = None,
+  ) -> None:
+    """Configure application logging.
+
+    :param log: The logger instance to configure.
+    :param file_name: The path to write logs to, none for stdout.
+    """
+
+    log.setLevel(self.level)
+    self.configure_formatter()
+    self.configure_handler(log, file_name)
+
+  def configure_handler(
+      self, log: logging.Logger, file_name: Optional[str]
+  ) -> None:
+    """Configure the logger's handler.
+
+    :param log: The logger instance to configure.
+    :param file_name: The path to write logs to, none for stdout.
+    """
+
+    log.handlers = []
+
+    if file_name is None:
+      handler = logging.StreamHandler()
+    else:
+      handler = logging.FileHandler(file_name, delay=True)
+
+    handler.setFormatter(self.formatter)
+    log.addHandler(handler)
+
+  @abc.abstractmethod
+  def configure_formatter(self) -> None:
+    """Configure the logger's formatter."""

pi_portal/modules/configuration/logging/__init__.py

@@ -0,0 +1,18 @@
+"""Shared fixtures for the logging modules tests."""
+# pylint: disable=redefined-outer-name
+
+from io import StringIO
+
+import pytest
+
+
+@pytest.fixture
+def mocked_logger_name() -> str:
+  """Return a mock logger name."""
+  return "mockLogger"
+
+
+@pytest.fixture
+def mocked_stream() -> StringIO:
+  """Return a mock logging stream."""
+  return StringIO()

pi_portal/modules/configuration/logging/bases/__init__.py

@@ -0,0 +1,33 @@
+"""JsonFormatter class."""
+
+import logging
+from typing import Any, Dict, Optional
+
+from pythonjsonlogger import jsonlogger
+
+
+class JsonFormatter(jsonlogger.JsonFormatter):
+  """JSON log formatter.
+
+  :param trace_id: The unique uuid for this process instance.
+  """
+
+  def __init__(self, trace_id: str, *args: Any, **kwargs: Any) -> None:
+    super().__init__(*args, **kwargs)
+    self.trace_id = trace_id
+
+  def add_fields(
+      self,
+      log_record: Dict[str, Any],
+      record: logging.LogRecord,
+      message_dict: Dict[str, Optional[str]],
+  ) -> None:
+    """Add custom fields to the base JsonFormatter.
+
+    :param log_record: The Python object that will be converted to JSON.
+    :param record: The Python LogRecord object generated.
+    :param message_dict: The existing message fields configuration.
+    """
+
+    super().add_fields(log_record, record, message_dict)
+    log_record['trace_id'] = self.trace_id

pi_portal/modules/configuration/logging/bases/base_logger.py

@@ -0,0 +1,28 @@
+"""Shared fixtures for the formatters modules."""
+# pylint: disable=redefined-outer-name
+
+import logging
+from io import StringIO
+
+import pytest
+from ..json import JsonFormatter
+
+
+@pytest.fixture
+def mocked_trace_id() -> str:
+  return "mockTraceId"
+
+
+@pytest.fixture
+def json_formatted_logger_instance(
+    mocked_logger_name: str,
+    mocked_stream: StringIO,
+    mocked_trace_id: str,
+) -> logging.Logger:
+  log = logging.getLogger(mocked_logger_name)
+  handler = logging.StreamHandler(stream=mocked_stream)
+  handler.setFormatter(
+      JsonFormatter(mocked_trace_id, '%(message)%(levelname)%(name)'),
+  )
+  log.addHandler(handler)
+  return log

pi_portal/modules/configuration/logging/conftest.py

@@ -0,0 +1,46 @@
+"""Test the JsonFormatter class."""
+
+import json
+import logging
+from io import StringIO
+
+
+class TestJsonFormatter:
+  """Test the JsonFormatter class."""
+
+  def test__no_fields__error_message(
+      self,
+      json_formatted_logger_instance: logging.Logger,
+      mocked_logger_name: str,
+      mocked_trace_id: str,
+      mocked_stream: StringIO,
+  ) -> None:
+    test_message = "test logging message"
+
+    json_formatted_logger_instance.error(test_message)
+
+    assert json.loads(mocked_stream.getvalue()) == {
+        "message": test_message,
+        "levelname": "ERROR",
+        "name": mocked_logger_name,
+        "trace_id": mocked_trace_id,
+    }
+
+  def test__extra_field__error_message(
+      self,
+      json_formatted_logger_instance: logging.Logger,
+      mocked_logger_name: str,
+      mocked_trace_id: str,
+      mocked_stream: StringIO,
+  ) -> None:
+    test_message = "test logging message"
+
+    json_formatted_logger_instance.error(test_message, extra={"foo": "bar"})
+
+    assert json.loads(mocked_stream.getvalue()) == {
+        "message": test_message,
+        "foo": "bar",
+        "levelname": "ERROR",
+        "name": mocked_logger_name,
+        "trace_id": mocked_trace_id,
+    }

pi_portal/modules/configuration/logging/formatters/__init__.py

@@ -0,0 +1,15 @@
+"""JsonLoggerConfiguration class."""
+
+from .bases.base_logger import LoggerConfigurationBase
+from .formatters.json import JsonFormatter
+
+
+class JsonLoggerConfiguration(LoggerConfigurationBase):
+  """JSON logging configuration."""
+
+  format_str = '%(message)%(levelname)%(name)%(asctime)'
+
+  def configure_formatter(self) -> None:
+    """Configure the logger's formatter."""
+
+    self.formatter = JsonFormatter(self.running_state.log_uuid, self.format_str)

pi_portal/modules/configuration/logging/formatters/json.py

@@ -0,0 +1,29 @@
+"""Shared fixtures for the formatters modules."""
+# pylint: disable=redefined-outer-name
+
+import logging
+from io import StringIO
+
+import pytest
+from pi_portal.modules.configuration.tests.fixtures import mock_state
+from ..json import JsonLoggerConfiguration
+
+
+@pytest.fixture
+def json_logger_configuration_instance() -> JsonLoggerConfiguration:
+  with mock_state.mock_state_creator():
+    return JsonLoggerConfiguration()
+
+
+@pytest.fixture
+def json_logger_stdout_instance(
+    monkeypatch: pytest.MonkeyPatch,
+    json_logger_configuration_instance: JsonLoggerConfiguration,
+    mocked_logger_name: str,
+    mocked_stream: StringIO,
+) -> logging.Logger:
+  log = logging.getLogger(mocked_logger_name)
+  json_logger = json_logger_configuration_instance
+  json_logger.configure(log)
+  monkeypatch.setattr(log.handlers[0], "stream", mocked_stream)
+  return log

pi_portal/modules/configuration/logging/formatters/tests/__init__.py

@@ -0,0 +1,84 @@
+"""Test the JsonLoggerConfiguration class."""
+
+import json
+import logging
+import os.path
+from io import StringIO
+from unittest import mock
+
+from freezegun import freeze_time
+from pi_portal.modules.configuration import state
+from ..formatters.json import JsonFormatter
+from ..json import JsonLoggerConfiguration
+
+
+class TestJsonLoggerConfiguration:
+  """Test JsonLoggerConfiguration class."""
+
+  def test_initialization__attrs(
+      self,
+      json_logger_configuration_instance: JsonLoggerConfiguration,
+  ) -> None:
+
+    assert json_logger_configuration_instance.format_str == \
+           '%(message)%(levelname)%(name)%(asctime)'
+
+  def test_configure__stdout(
+      self,
+      mocked_logger_name: str,
+      json_logger_configuration_instance: JsonLoggerConfiguration,
+  ) -> None:
+    mock_log = logging.getLogger(mocked_logger_name)
+
+    json_logger_configuration_instance.configure(mock_log)
+
+    assert len(mock_log.handlers) == 1
+    assert isinstance(mock_log.handlers[0], logging.StreamHandler)
+    assert isinstance(
+        json_logger_configuration_instance.formatter, JsonFormatter
+    )
+    assert mock_log.handlers[0].formatter == \
+           json_logger_configuration_instance.formatter
+
+  @mock.patch("os.open", mock.mock_open())
+  def test_configure__file(
+      self,
+      mocked_logger_name: str,
+      json_logger_configuration_instance: JsonLoggerConfiguration,
+  ) -> None:
+    mock_log = logging.getLogger(mocked_logger_name)
+    mock_file_name = "test.log"
+
+    json_logger_configuration_instance.configure(mock_log, mock_file_name)
+
+    assert len(mock_log.handlers) == 1
+    assert isinstance(mock_log.handlers[0], logging.FileHandler)
+    assert isinstance(
+        json_logger_configuration_instance.formatter, JsonFormatter
+    )
+    assert mock_file_name == \
+        os.path.basename(
+          mock_log.handlers[0].baseFilename
+        )
+    assert mock_log.handlers[0].formatter == \
+           json_logger_configuration_instance.formatter
+
+  @freeze_time("2012-01-14")
+  def test_logging__error_message__no_fields(
+      self,
+      json_logger_stdout_instance: logging.Logger,
+      mocked_logger_name: str,
+      mocked_state: state.State,
+      mocked_stream: StringIO,
+  ) -> None:
+    test_message = "test logging message"
+
+    json_logger_stdout_instance.error(test_message)
+
+    assert json.loads(mocked_stream.getvalue()) == {
+        "message": test_message,
+        "levelname": "ERROR",
+        "name": mocked_logger_name,
+        "trace_id": mocked_state.log_uuid,
+        "asctime": "2012-01-14 00:00:00,000",
+    }