Skip to content

Commit 8907e44

Browse files
committed
Update README.md with bit about logging
1 parent 84fa5c7 commit 8907e44

2 files changed

Lines changed: 48 additions & 5 deletions

File tree

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ reports/
1212
*.pyc
1313
.pytest_cache
1414
__pycache__
15+
.DS_Store
1516

1617
*.txt
1718
*.env

README.md

Lines changed: 47 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ An **Action** represents a specific functionality in your plugin. You can create
4747
from streamdeck import Action
4848

4949
# Create an action with a unique UUID (from your manifest.json)
50-
my_action = Action(uuid="com.example.myaction")
50+
my_action = Action(uuid="com.example.myplugin.myaction")
5151
```
5252

5353
### Registering Event Handlers
@@ -64,6 +64,47 @@ def handle_will_appear(event):
6464
print("Will Appear event received:", event)
6565
```
6666

67+
68+
### Writing Logs
69+
70+
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.
71+
72+
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:
73+
74+
```python
75+
import logging
76+
from streamdeck import Action
77+
78+
logger = logging.getLogger("myaction")
79+
80+
my_action = Action(uuid="com.example.mytestplugin.myaction")
81+
```
82+
83+
Here, the logger name "myaction" matches the last part of the UUID passed in to instantiate the Action ("com.strohganoff.mytestplugin.myaction").
84+
85+
#### Configuring your own Loggers
86+
87+
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:
88+
89+
`configure_streamdeck_logger`: Configures a logger for the Stream Deck plugin with a rotating file handler that writes logs to a centralized location.
90+
91+
`configure_local_logger`: Configures a logger for a Stream Deck plugin that writes logs to a local data directory, allowing for plugin-specific logging.
92+
93+
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.
94+
95+
For example:
96+
```python
97+
import logging
98+
from streamdeck.utils.logging import configure_streamdeck_logger
99+
100+
configure_streamdeck_logger(name="myaction", plugin_uuid="com.example.mytestplugin")
101+
102+
logger = logging.getLogger("myaction")
103+
```
104+
105+
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.
106+
107+
67108
### Running the Plugin
68109

69110
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
117158

118159
```python
119160
# main.py
120-
161+
import logging
121162
from streamdeck import Action, PluginManager, events
122163
164+
logger = logging.getLogger("myaction")
165+
123166
# Define your action
124-
my_action = Action(uuid="com.example.myaction")
167+
my_action = Action(uuid="com.example.myplugin.myaction")
125168
126169
# Register event handlers
127170
@my_action.on("keyDown")
128171
def handle_key_down(event):
129-
print("Key Down event received:", event)
172+
logger.debug("Key Down event received:", event)
130173
```
131174

132175
```toml
133176
# pyproject.toml
134-
135177
[tools.streamdeck]
136178
action_scripts = [
137179
"main.py",

0 commit comments

Comments
 (0)