Add functionality and documentation for debug mode

Author: strohganoff

README.md

@@ -157,7 +157,7 @@ The following commands are required, which are the same as the Stream Deck softw
 
 - `-info`: Additional information (formatted as json) about the plugin environment, as provided by the Stream Deck software.
 
-There are also  two additional options for specifying action scripts to load. Note that you can't use both of these options together, and the Stream Deck software doesn't pass in these options.
+There are also two additional options for specifying action scripts to load. Note that you can't use both of these options together, and the Stream Deck software doesn't pass in these options.
 
 - Plugin Directory: Pass the directory containing the plugin files as a positional argument:
 
@@ -172,6 +172,58 @@ There are also  two additional options for specifying action scripts to load. No
     streamdeck --action-scripts actions1.py actions2.py
     ```
 
+In addition to these, there is an additional option to use **debug mode**, which is discussed below.
+
+#### Debugging
+
+The SDK supports remote debugging capabilities, allowing you to attach a debugger after the plugin has started. This is particularly useful since Stream Deck plugins run as separate processes.
+
+To enable debug mode, pass in the option `--debug {debug port number}`, which tells the plugin to wait for a debugger to attach on that port number.
+
+```bash
+streamdeck --debug 5675
+```
+
+When running in debug mode, the plugin will pause for 10 seconds after initialization, giving you time to attach your debugger. You'll see a message in the logs indicating that the plugin is waiting for a debugger to attach.
+
+NOTE: If things get messy, and you have a prior instance already listening to that port, you should kill the process with something like the following command:
+
+```bash
+kill $(lsof -t -i:$DEBUG_PORT)
+```
+
+#### Debugging with VS Code
+
+1. Create a launch configuration in `.vscode/launch.json`:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Attach to Stream Deck Plugin",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            }
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "."
+                }
+            ],
+            "justMyCode": false,
+        }
+    ]
+}
+```
+
+2. Start your plugin with debugging enabled
+3. When you see the "waiting for debugger" message, use VS Code's Run and Debug view to attach using the configuration above
+4. Set breakpoints and debug as normal
+
 
 #### Configuration
 

pyproject.toml

@@ -74,6 +74,7 @@
             "pytest-mock >= 3.14.0",
             "pytest-sugar >= 1.0.0",
             "tox >= 4.23.2",
+            "debugpy",
         ]
 
     [project.urls]

streamdeck/__main__.py

@@ -2,7 +2,7 @@
 import logging
 import sys
 from pathlib import Path
-from typing import Annotated, Union
+from typing import Annotated, Optional
 
 import typer
 
@@ -18,14 +18,25 @@
 plugin = typer.Typer()
 
 
+def setup_debug_mode(debug_port: int) -> None:
+    """Setup the debug mode for the plugin and wait for the debugger to attach."""
+    import debugpy
+
+    debugpy.listen(debug_port)
+    logger.info("Starting in debug mode. Waiting for debugger to attach on port %d...", debug_port)
+    debugpy.wait_for_client()
+    logger.info("Debugger attached.")
+
+
 @plugin.command()
 def main(
     port: Annotated[int, typer.Option("-p", "-port")],
     plugin_registration_uuid: Annotated[str, typer.Option("-pluginUUID")],
     register_event: Annotated[str, typer.Option("-registerEvent")],
     info: Annotated[str, typer.Option("-info")],
     plugin_dir: Annotated[Path, typer.Option(file_okay=False, exists=True, readable=True)] = Path.cwd(),  # noqa: B008
-    action_scripts: Union[list[str], None] = None,  # noqa: UP007
+    action_scripts: Optional[list[str]] = None,  # noqa: UP007
+    debug_port: Annotated[Optional[int], typer.Option("--debug", "-d")] = None,  # noqa: UP007
 ) -> None:
     """Start the Stream Deck plugin with the given configuration.
 
@@ -43,6 +54,9 @@ def main(
     # a child logger with `logging.getLogger("streamdeck.mycomponent")`, all with the same handler/formatter configuration.
     configure_streamdeck_logger(name="streamdeck", plugin_uuid=plugin_uuid)
 
+    if debug_port:
+        setup_debug_mode(debug_port)
+
     pyproject = PyProjectConfigs.validate_from_toml_file(plugin_dir / "pyproject.toml", action_scripts=action_scripts)
     actions = pyproject.streamdeck_plugin_actions