add block_forever example

update example READMEs

add script entry point for block_forever example
add poe task block-forever

examples/block_forever/README.md

@@ -0,0 +1,18 @@
+## About
+
+This example demonstrates the following:
+
+-   How to register callback functions for different kinds of events.
+-   How to view the logs emitted by the streamlabsio library.
+-   How to use the raw data returned by the callback functions.
+-   How to use {Client}.wait() to block the main thread indefinitely.
+
+## Configure
+
+The script expects the Streamlabs token to be loaded into the environment with key `STREAMLABS_TOKEN`.
+
+If you're running the script with `poetry poe block-forever` then poe is configured to load a `.env` file in the root of the repository.
+
+## Use
+
+Run the script and trigger any of the events with `Test Widgets` in the Streamlabs GUI.

examples/block_forever/__main__.py

@@ -0,0 +1,55 @@
+import os
+
+from loguru import logger
+
+import streamlabsio
+
+logger.enable('streamlabsio')
+
+
+def on_streamlabs_event(event, data):
+    match event:
+        case 'donation':
+            print('{name} donated {amount}! With message: {message}'.format(**data))
+
+
+def on_twitch_event(event, data):
+    event_message = {
+        'follow': 'Received follow from {name}',
+        'bits': '{name} donated {amount} bits! With message: {message}',
+        'subscription': '{name} just subscribed for {months} months!',
+        'raid': '{name} just raided with {raiders} raiders!',
+        'host': '{name} just hosted with {viewers} viewers!',
+    }
+
+    if event in event_message:
+        print(event_message[event].format(**data))
+
+
+def on_youtube_event(event, data):
+    event_message = {
+        'follow': 'Received follow from {name}',
+        'superchat': '{name} donated {displayString} with a superchat! With comment: {comment}',
+        'subscription': '{name} just subscribed for {months} months!',
+    }
+
+    if event in event_message:
+        print(event_message[event].format(**data))
+
+
+def main():
+    try:
+        with streamlabsio.connect(
+            token=os.getenv('STREAMLABS_TOKEN'), raw=True
+        ) as client:
+            client.obs.on('streamlabs', on_streamlabs_event)
+            client.obs.on('twitch_account', on_twitch_event)
+            client.obs.on('youtube_account', on_youtube_event)
+
+            client.wait()
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == '__main__':
+    main()

examples/events/README.md

@@ -1,18 +1,18 @@
 ## About
 
-To view the logs emitted by the streamlabsio library simply add the following to your code:
+This example demonstrates the following:
 
-```python
-from loguru import logger
-
-logger.enable('streamlabsio')
-```
+-   How to register callback functions for different kinds of events.
+-   How to view the logs emitted by the streamlabsio library.
+-   How to print the attributes of an event data dataclass using the *attrs()* method.
+-   How to use dataclass methods on the dataclasses, this case *asdict*.
+-   How to use {Client}.wait() to block the main thread for a period of time.
 
 ## Configure
 
 The script expects the Streamlabs token to be loaded into the environment with key `STREAMLABS_TOKEN`.
 
-If you're running the script with `poetry poe` then poe is configured to load a `.env` file in the root of the repository.
+If you're running the script with `poetry poe events` then poe is configured to load a `.env` file in the root of the repository.
 
 ## Use
 

examples/events/__main__.py

@@ -9,6 +9,8 @@ logger.enable('streamlabsio')
 
 
 def on_streamlabs_event(event, data):
+    print(data.attrs())
+
     match event:
         case 'donation':
             print(f'{data.name} donated {data.amount}! With message: {data.message}')
@@ -44,7 +46,7 @@ def main():
         client.obs.on('twitch_account', on_twitch_event)
         client.obs.on('youtube_account', on_youtube_event)
 
-        client.sio.sleep(30)
+        client.wait(30)
 
 
 if __name__ == '__main__':

pyproject.toml

@@ -27,6 +27,7 @@ envfile = ".env"
 
 [tool.poe.tasks]
 events.script = "scripts:ex_events"
+block-forever.script = "scripts:ex_block_forever"
 
 [tool.ruff]
 exclude = [

scripts.py

@@ -6,3 +6,11 @@ from pathlib import Path
 def ex_events():
     scriptpath = Path.cwd() / 'examples' / 'events' / '.'
     subprocess.run([sys.executable, str(scriptpath)])
+
+
+def ex_block_forever():
+    scriptpath = Path.cwd() / 'examples' / 'block_forever' / '.'
+    try:
+        subprocess.run([sys.executable, str(scriptpath)])
+    except KeyboardInterrupt:
+        sys.exit(0)