Merge pull request #1 from strohganoff/feature/better-logging

Feature/better logging

Author: strohganoff

.gitignore

@@ -12,6 +12,7 @@ reports/
 *.pyc
 .pytest_cache
 __pycache__
+.DS_Store
 
 *.txt
 *.env

README.md

@@ -47,7 +47,7 @@ An **Action** represents a specific functionality in your plugin. You can create
 from streamdeck import Action
 
 # Create an action with a unique UUID (from your manifest.json)
-my_action = Action(uuid="com.example.myaction")
+my_action = Action(uuid="com.example.myplugin.myaction")
 ```
 
 ### Registering Event Handlers
@@ -64,6 +64,47 @@ def handle_will_appear(event):
     print("Will Appear event received:", event)
 ```
 
+
+### Writing Logs
+
+For convenience, a logger is configured with the same name as the last part of the Action's UUID, so you can simply call logging.getLogger(<name>) with the appropriate name to get the already-configured logger that writes to a rotating file. The log file is located in the Stream Deck user log directory.
+
+When creating actions in your plugin, you can configure logging using the logger name that matches the last part of your Action's UUID. For example, consider the following code:
+
+```python
+import logging
+from streamdeck import Action
+
+logger = logging.getLogger("myaction")
+
+my_action = Action(uuid="com.example.mytestplugin.myaction")
+```
+
+Here, the logger name "myaction" matches the last part of the UUID passed in to instantiate the Action ("com.strohganoff.mytestplugin.myaction"). 
+
+#### Configuring your own Loggers
+
+Loggers can also be easily configured using provided utility functions, allowing for flexibility. If custom logging configurations are prefered over the automatic method shown above, you can use the following functions:
+
+`configure_streamdeck_logger`: Configures a logger for the Stream Deck plugin with a rotating file handler that writes logs to a centralized location.
+
+`configure_local_logger`: Configures a logger for a Stream Deck plugin that writes logs to a local data directory, allowing for plugin-specific logging.
+
+These functions can be used to set up the logging behavior you desire, depending on whether you want the logs to be centralized or specific to each plugin.
+
+For example:
+```python
+import logging
+from streamdeck.utils.logging import configure_streamdeck_logger
+
+configure_streamdeck_logger(name="myaction", plugin_uuid="com.example.mytestplugin")
+
+logger = logging.getLogger("myaction")
+```
+
+Using the above code, you can ensure that logs from your action are properly collected and managed, helping you debug and monitor the behavior of your Stream Deck plugins.
+
+
 ### Running the Plugin
 
 Once the plugin's actions and their handlers have been defined, very little else is needed to get this code running. With this library installed, the streamdeck CLI command   will handle the setup, loading of action scripts, and running of the plugin automatically, making it much easier to manage.
@@ -117,21 +158,22 @@ Below is a complete example that creates a plugin with a single action. The acti
 
 ```python
 # main.py
-
+import logging
 from streamdeck import Action, PluginManager, events
 
+logger = logging.getLogger("myaction")
+
 # Define your action
-my_action = Action(uuid="com.example.myaction")
+my_action = Action(uuid="com.example.myplugin.myaction")
 
 # Register event handlers
 @my_action.on("keyDown")
 def handle_key_down(event):
-    print("Key Down event received:", event)
+    logger.debug("Key Down event received:", event)
 ```
 
 ```toml
 # pyproject.toml
-
 [tools.streamdeck]
     action_scripts = [
         "main.py",

pyproject.toml

@@ -7,7 +7,7 @@
 
 [project]
     name = "streamdeck-plugin-sdk"
-    version = "0.2.2"
+    version = "0.3.0"
     description = "Write Streamdeck plugins using Python"
     readme = "README.md"
     authors = [

streamdeck/__main__.py

@@ -3,7 +3,6 @@
 import importlib.util
 import json
 import logging
-import os
 from argparse import ArgumentParser
 from pathlib import Path
 from typing import TYPE_CHECKING, cast
@@ -21,6 +20,7 @@
     StreamDeckConfigDict,
 )
 from streamdeck.manager import PluginManager
+from streamdeck.utils.logging import configure_streamdeck_logger
 
 
 if TYPE_CHECKING:
@@ -30,16 +30,7 @@
     from typing_extensions import Self  # noqa: UP035
 
 
-logger = logging.getLogger("streamdeck-plugin-sdk")
-
-logger.addHandler(logging.StreamHandler())
-
-# TODO: Add better functionality for setting up logging to save to files in the proper streamdeck log directory.
-file_handler = logging.FileHandler(os.path.expanduser("~/plugin.log"))
-file_handler.setLevel(logging.DEBUG)
-logger.addHandler(file_handler)
-
-logger.info("Starting run...")
+logger = logging.getLogger("streamdeck")
 
 
 def setup_cli() -> ArgumentParser:
@@ -65,14 +56,21 @@ def setup_cli() -> ArgumentParser:
 
     # Options that will always be passed in by the StreamDeck software when running this plugin.
     parser.add_argument("-port", dest="port", type=int, help="Port", required=True)
-    parser.add_argument("-pluginUUID", dest="pluginUUID", type=str, help="pluginUUID", required=True)
-    parser.add_argument("-registerEvent", dest="registerEvent", type=str, help="registerEvent", required=True)
+    parser.add_argument(
+        "-pluginUUID", dest="pluginUUID", type=str, help="pluginUUID", required=True
+    )
+    parser.add_argument(
+        "-registerEvent", dest="registerEvent", type=str, help="registerEvent", required=True
+    )
     parser.add_argument("-info", dest="info", type=str, help="info", required=True)
 
     return parser
 
 
-def determine_action_scripts(plugin_dir: Path | None, action_scripts: list[str] | None) -> list[str]:
+def determine_action_scripts(
+    plugin_dir: Path | None,
+    action_scripts: list[str] | None,
+) -> list[str]:
     """Determine the action scripts to be loaded based on provided arguments.
 
     plugin_dir and action_scripts cannot both have values -> either only one of them isn't None, or they are both None.
@@ -102,7 +100,6 @@ def determine_action_scripts(plugin_dir: Path | None, action_scripts: list[str]
         raise KeyError(msg) from e
 
 
-
 def read_streamdeck_config_from_pyproject(plugin_dir: Path) -> StreamDeckConfigDict:
     """Get the streamdeck section from a plugin directory by reading pyproject.toml.
 
@@ -178,12 +175,12 @@ def _load_module_from_file(filepath: Path) -> ModuleType:
         # Create a module specification for a module located at the given filepath.
         # A "specification" is an object that contains information about how to load the module, such as its location and loader.
         # "module.name" is an arbitrary name used to identify the module internally.
-        spec: ModuleSpec = importlib.util.spec_from_file_location("module.name", str(filepath)) # type: ignore
+        spec: ModuleSpec = importlib.util.spec_from_file_location("module.name", str(filepath))  # type: ignore
         # Create a new module object from the given specification.
         # At this point, the module is created but not yet loaded (i.e. its code hasn't been executed).
         module: ModuleType = importlib.util.module_from_spec(spec)
         # Load the module by executing its code, making available its functions, classes, and variables.
-        spec.loader.exec_module(module) # type: ignore
+        spec.loader.exec_module(module)  # type: ignore
 
         return module
 
@@ -205,6 +202,10 @@ def main():
     info = json.loads(args.info)
     plugin_uuid = info["plugin"]["uuid"]
 
+    # After configuring once here, we can grab the logger in any other module with `logging.getLogger("streamdeck")`, or
+    # a child logger with `logging.getLogger("streamdeck.mycomponent")`, all with the same handler/formatter configuration.
+    configure_streamdeck_logger(name="streamdeck", plugin_uuid=plugin_uuid)
+
     action_scripts = determine_action_scripts(
         plugin_dir=args.plugin_dir,
         action_scripts=args.action_scripts,
@@ -223,6 +224,10 @@ def main():
     )
 
     for action in actions:
+        # Configure a logger for each action, giving it the last part of its uuid as logger name.
+        action_component_name = action.uuid.split(".")[-1]
+        configure_streamdeck_logger(name=action_component_name, plugin_uuid=plugin_uuid)
+
         manager.register_action(action)
 
     manager.run()

streamdeck/command_sender.py

@@ -11,7 +11,7 @@
 
 
 
-logger = getLogger("streamdeck")
+logger = getLogger("streamdeck.command_sender")
 
 
 class StreamDeckCommandSender:

streamdeck/manager.py

@@ -19,7 +19,6 @@
 
 # TODO: Fix this up to push to a log in the apropos directory and filename.
 logger = getLogger("streamdeck.manager")
-logger.addHandler(logging.StreamHandler())
 
 
 

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")

streamdeck/utils/helper_actions.py

@@ -12,13 +12,12 @@
     from streamdeck.models.events import EventBase
 
 
-
-logger = getLogger("streamdeck")
-
-
-def create_logging_action(action_name: str):
+def create_logging_action(action_uuid: str) -> Action:
     """Action that logs the event name of every occurring event."""
-    logging_action = Action(action_name)
+    logging_action = Action(action_uuid)
+
+    action_component_name = action_uuid.split(".")[-1]
+    logger = getLogger(action_component_name)
 
     def log_event(event_data: EventBase) -> None:
         logger.info("Action %s — event %s", logging_action.__class__, event_data.event)
@@ -30,10 +29,12 @@ def log_event(event_data: EventBase) -> None:
     return logging_action
 
 
-
-def create_file_writing_action(action_name: str, file: TextIOWrapper) -> Action:
+def create_file_writing_action(action_uuid: str, file: TextIOWrapper) -> Action:
     """Action that saves the full json of every occurring event."""
-    file_writing_action = Action(action_name)
+    file_writing_action = Action(action_uuid)
+
+    action_component_name = action_uuid.split(".")[-1]
+    logger = getLogger(action_component_name)
 
     def write_event(event_data: EventBase) -> None:
         logger.info("Action %s — event %s", file_writing_action.__class__, event_data.event)
@@ -46,4 +47,4 @@ def write_event(event_data: EventBase) -> None:
     for event_name in available_event_names:
         file_writing_action.on(event_name)(write_event)
 
-    return file_writing_action
+    return file_writing_action