Add logging configuration module and related tests, and more docstrings

strohganoff · strohganoff · commit e43fef77275d · 2024-10-29T16:09:41.000-05:00
diff --git a/streamdeck/utils/dirs.py b/streamdeck/utils/dirs.py
@@ -1,3 +1,11 @@
+"""This module provides utility functions to get various directory paths related to Elgato Stream Deck plugins and components.
+
+The functions defined here help locate user-specific log directories, local data directories for plugins, and application data directories for Elgato Stream Deck components and plugins.
+These paths are useful for accessing log files, unpacked plugin code, and other application data for Stream Deck and its plugins.
+
+Note:
+    These functions have been tested on macOS only so far, with plans to test on Windows in the future.
+"""
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
@@ -11,28 +19,76 @@
 
 
 def streamdeck_log_dir() -> Path:
+    """Get the path to the user-specific log directory for Elgato Stream Deck.
+
+    The result of this function is the user log directory path that all plugins as well as internal StreamDeck components write to.
+
+    Returns:
+        Path: Path to the Stream Deck log directory.
+    """
     return platformdirs.user_log_path(appname="ElgatoStreamDeck")
 
 
 def streamdeck_local_data_dir() -> Path:
+    """Get the path to the local user-specific data directory for Elgato Stream Deck.
+
+    The result of this function is the directory that contains the unpacked (i.e. unzipped) directories of all of the code of installed plugins.
+
+    Returns:
+        Path: Path to the local data directory for Stream Deck.
+    """
     return platformdirs.user_data_path("com.elgato.StreamDeck")
 
 
-def plugin_local_data_dir(plugin_name: str) -> Path:
-    return streamdeck_local_data_dir() / "Plugins" / plugin_name
+def plugin_local_data_dir(plugin_uuid: str) -> Path:
+    """Get the path to the local user-specific data directory for a specific Stream Deck plugin.
+
+    The result of this function is the directory path for the given plugin's unpacked (i.e. unzipped) code.
+
+    Args:
+        plugin_uuid (str): The UUID of the plugin.
+
+    Returns:
+        Path: Path to the local data directory for the specified plugin.
+    """
+    return streamdeck_local_data_dir() / "Plugins" / f"{plugin_uuid}.sdPlugin"
 
 
 def streamdeck_application_data_dir() -> Path:
-    # NOTE: The only directory under this seems to be "QtWebEngine",
-    # which is a component for embeding web browser functionality into their desktop applications.
-    return platformdirs.user_data_path('elgato') / "Streamdeck"
+    """Get the path to the application-specific data directory for Elgato Stream Deck.
+
+    Note:
+        The only directory under this path seems to be "QtWebEngine", which is a component for embedding web browser
+        functionality into their desktop applications.
+
+    Returns:
+        Path: Path to the application data directory for Stream Deck.
+    """
+    return platformdirs.user_data_path("elgato") / "Streamdeck"
+
 
+def plugin_application_data_dir(plugin_uuid: str) -> Path:
+    """Get the path to the application-specific data directory for a specific Stream Deck plugin.
 
-def plugin_application_data_dir(plugin_name: str) -> Path:
-    # NOTE: Not all plugins have a directory here.. A few individual plugins have probably pushed data to this location.
-    return streamdeck_application_data_dir() / "QtWebEngine" / plugin_name
+    Note:
+        Not all plugins have a directory here. Only a few individual plugins have likely pushed data to this location.
+
+    Args:
+        plugin_uuid (str): The UUID of the plugin.
+
+    Returns:
+        Path: Path to the application data directory for the specified plugin.
+    """
+    return streamdeck_application_data_dir() / "QtWebEngine" / plugin_uuid
 
 
 def elgato_site_data_dir() -> Path:
-    # NOTE: There doesn't seem to be a "Stream Deck" directory in here, just "Wave Link".
-    return platformdirs.site_data_path("Elgato")
+    """Get the path to the system-wide shared data directory for Elgato products.
+
+    Note:
+        There doesn't seem to be a "Stream Deck" directory in here, only "Wave Link".
+
+    Returns:
+        Path: Path to the shared data directory for Elgato products.
+    """
+    return platformdirs.site_data_path("Elgato")
diff --git a/streamdeck/utils/logging.py b/streamdeck/utils/logging.py
@@ -0,0 +1,107 @@
+"""This module provides utility functions for configuring loggers for Elgato Stream Deck plugins.
+
+The module includes functions to set up loggers that write logs to either the centralized Stream Deck user log directory
+or to the installed plugin's local code directory. Each logger is configured with both a stream handler for console output and a
+rotating file handler to manage log file sizes.
+"""
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from streamdeck.utils.dirs import plugin_local_data_dir, streamdeck_log_dir
+
+
+def configure_streamdeck_logger(
+    name: str,
+    plugin_uuid: str,
+    log_level: int = logging.DEBUG,
+) -> None:
+    """Configure a logger for the Elgato Stream Deck plugin with a rotating file handler.
+
+    This logger writes to a log file located in the Stream Deck user log directory, where both internal Stream Deck components
+    and plugins have their logs centralized.
+
+    Args:
+        name (str): The name of the logger.
+        plugin_uuid (str): The UUID of the plugin.
+        log_level (int, optional): The logging level. Defaults to logging.DEBUG.
+    """
+    plugin_log_filepath = streamdeck_log_dir() / f"{plugin_uuid}.log"
+
+    _configure_logger(
+        name=name,
+        filename=plugin_log_filepath,
+        level=log_level,
+    )
+
+
+def configure_local_logger(
+    name: str,
+    plugin_uuid: str,
+    log_level: int = logging.DEBUG,
+) -> None:
+    """Configure a logger for a Stream Deck plugin that writes to a local data directory.
+
+    This logger writes to a log file located in the local plugin directory, allowing plugin-specific logs to be kept
+    separately from the main Stream Deck logs.
+
+    Args:
+        name (str): The name of the logger.
+        plugin_uuid (str): The UUID of the plugin.
+        log_level (int, optional): The logging level. Defaults to logging.DEBUG.
+    """
+    # The log file name is the last component of the plugin_uuid.
+    plugin_component_name = plugin_uuid.split(".")[-1]
+
+    local_log_filepath = (
+        plugin_local_data_dir(plugin_uuid=plugin_uuid) / f"logs/{plugin_component_name}.log"
+    )
+
+    _configure_logger(
+        name=name,
+        filename=local_log_filepath,
+        level=log_level,
+    )
+
+
+def _configure_logger(
+    name: str,
+    filename: Path,
+    level: int = logging.DEBUG,
+) -> logging.Logger:
+    """Helper function to configure a logger with a stream handler and a rotating file handler.
+
+    This function ensures that the logger is only configured once by checking its handlers. It sets up both a stream
+    handler for console output and a rotating file handler to save logs to a file.
+
+    Args:
+        name (str): The name of the logger.
+        filename (Path): The path to the log file.
+        level (int, optional): The logging level. Defaults to logging.DEBUG.
+
+    Returns:
+        logging.Logger: The configured logger instance.
+    """
+    logger = logging.getLogger(name)
+
+    # For some reason, logger.getHandlers() evaluates as True here, even if the handlers list property is empty...
+    if not logger.handlers:
+        logger.setLevel(level)
+
+        formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+        stream_handler = logging.StreamHandler()
+        stream_handler.setFormatter(formatter)
+        logger.addHandler(stream_handler)
+
+        # Ensure the directory path this logger will write files to exists.
+        filename.parent.mkdir(parents=True, exist_ok=True)
+
+        file_handler = RotatingFileHandler(
+            filename.expanduser(),
+            maxBytes=5 * 1024 * 1024,
+            backupCount=20,
+        )
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+    return logger
diff --git a/tests/test_logging.py b/tests/test_logging.py
@@ -0,0 +1,113 @@
+"""This module contains tests for configuring loggers for the Elgato Stream Deck plugins.
+
+The tests validate that the logger configurations correctly create log files for both local plugin-specific logging and
+centralized Stream Deck logging.
+"""
+import logging
+from pathlib import Path
+
+import platformdirs
+import pytest
+from streamdeck.utils.logging import configure_local_logger, configure_streamdeck_logger
+
+
+@pytest.fixture
+def fake_plugin_local_log_dir(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    """Fixture to set up a fake local log directory for plugin-specific logging.
+
+    This fixture uses `monkeypatch` to replace the `platformdirs.user_data_path` function, redirecting it to use a
+    temporary path for testing purposes.
+
+    Args:
+        monkeypatch (pytest.MonkeyPatch): The pytest monkeypatch object for modifying module attributes.
+        tmp_path (Path): A temporary path provided by pytest for file operations.
+
+    Returns:
+        Path: The temporary path used for local plugin logging.
+    """
+    monkeypatch.setattr(
+        platformdirs, "user_data_path", value=(lambda plugin_uuid: tmp_path / plugin_uuid)
+    )
+    return tmp_path
+
+
+@pytest.fixture
+def fake_streamdeck_log_dir(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    """Fixture to set up a fake Stream Deck log directory for centralized logging.
+
+    This fixture uses `monkeypatch` to replace the `platformdirs.user_log_path` function, redirecting it to use a
+    temporary path for testing purposes.
+
+    Args:
+        monkeypatch (pytest.MonkeyPatch): The pytest monkeypatch object for modifying module attributes.
+        tmp_path (Path): A temporary path provided by pytest for file operations.
+
+    Returns:
+        Path: The temporary path used for Stream Deck logging.
+    """
+    monkeypatch.setattr(platformdirs, "user_log_path", value=(lambda appname: tmp_path / appname))
+    return tmp_path
+
+
+def test_local_logger(fake_plugin_local_log_dir: Path):
+    """Test the configuration of a local plugin-specific logger.
+
+    This test verifies that a logger configured for a specific plugin writes logs to the correct local directory.
+
+    Args:
+        fake_plugin_local_log_dir (Path): The fake local log directory path provided by the fixture.
+    """
+    FAKE_LOGGER_NAME = "TEST-PLUGIN-FILE"
+    FAKE_PLUGIN_UUID = "com.test.spotifier"
+    LOG_STATEMENT = "Test log."
+
+    configure_local_logger(name=FAKE_LOGGER_NAME, plugin_uuid=FAKE_PLUGIN_UUID)
+    logger = logging.getLogger(FAKE_LOGGER_NAME)
+
+    logger.info(LOG_STATEMENT)
+
+    log_file = (
+        fake_plugin_local_log_dir
+        / "com.elgato.StreamDeck/Plugins"
+        / FAKE_PLUGIN_UUID
+        / f"logs/{FAKE_LOGGER_NAME}.log"
+    )
+
+    assert log_file.exists()
+
+    with log_file.open("r") as f:
+        actual_log_file_output = f.read()
+        # We don't want to make too many assumptions here about the format of the log output.
+        assert "INFO" in actual_log_file_output
+        assert LOG_STATEMENT in actual_log_file_output
+        # Probably don't need to assert that the logger's name is in the log.
+        # assert fake_name in actual_log_file_output
+
+
+def test_streamdeck_logger(fake_streamdeck_log_dir: Path):
+    """Test the configuration of a centralized Stream Deck logger.
+
+    This test verifies that a logger configured for the Stream Deck writes logs to the correct centralized directory.
+
+    Args:
+        fake_streamdeck_log_dir (Path): The fake Stream Deck log directory path provided by the fixture.
+    """
+    FAKE_LOGGER_NAME = "my_test_name"
+    FAKE_PLUGIN_UUID = "com.test.plugin"
+    LOG_STATEMENT = "Testing 123..."
+
+    configure_streamdeck_logger(name=FAKE_LOGGER_NAME, plugin_uuid=FAKE_PLUGIN_UUID)
+    logger = logging.getLogger(FAKE_LOGGER_NAME)
+
+    logger.info(LOG_STATEMENT)
+
+    log_file = fake_streamdeck_log_dir / "ElgatoStreamDeck" / f"{FAKE_PLUGIN_UUID}.log"
+
+    assert log_file.exists()
+    with log_file.open("r") as f:
+        actual_log_file_output = f.read()
+        # We don't want to make too many assumptions here about the format of the log output.
+        assert "INFO" in actual_log_file_output
+        assert LOG_STATEMENT in actual_log_file_output
+        # Probably don't need to assert that the logger's name is in the log.
+        assert FAKE_LOGGER_NAME in actual_log_file_output
