Refactor signal examples and enhanced documentation

Author: san-tekart

docs/example.md

@@ -1,4 +1,4 @@
-# examples/02_signal_async.py
+# examples/signal_async.py
 
 """
 Async Signal Example
@@ -7,6 +7,12 @@
 1. Creating a signal
 2. Connecting an async slot
 3. Emitting a signal to async handler
+
+Key Points:
+- Demonstrates asynchronous signal-slot communication
+- Shows how to use @t_slot decorator with async functions
+- Illustrates handling of async slot execution in event loop
+- Explains integration of signals with asyncio for non-blocking operations
 """
 
 import asyncio

examples/signal_async.py

@@ -1,15 +1,22 @@
-# examples/01_signal_basic.py
+# examples/signal_basic.py
 
 """
-Async Signal Example
+Basic Signal-Slot Example
 
-This example demonstrates the basic usage of TSignal with async slots:
+This example demonstrates the fundamental usage of TSignal with a synchronous slot:
 1. Creating a signal
-2. Connecting an async slot
-3. Emitting a signal to async handler
+2. Connecting a regular method as a slot (without @t_slot)
+3. Emitting a signal to trigger slot execution
+
+Key Points:
+- Showcases the most basic form of signal-slot connection.
+- The slot is a normal instance method of a class, not decorated with @t_slot.
+- Emphasizes that even without @t_slot, a callable method can act as a slot.
+- Introduces the concept of signal emission and immediate slot execution.
 """
 
 import asyncio
+import time
 from tsignal.core import t_with_signals, t_signal, t_slot
 
 
@@ -34,20 +41,19 @@ def increment(self):
 
 
 @t_with_signals
-class AsyncDisplay:
+class Display:
     """
-    A simple display class that receives count updates and processes them asynchronously.
+    A simple display class that receives count updates and processes them.
     """
 
     def __init__(self):
         self.last_value = None
 
-    @t_slot
-    async def on_count_changed(self, value):
-        """Async slot that receives count updates"""
+    def on_count_changed(self, value):
+        """slot that receives count updates"""
         print(f"Display processing count: {value}")
-        # Simulate some async processing
-        await asyncio.sleep(1)
+        # Simulate some heavy processing
+        time.sleep(1)
         self.last_value = value
         print(f"Display finished processing: {value}")
 
@@ -59,28 +65,24 @@ async def main():
 
     # Create instances
     counter = Counter()
-    display = AsyncDisplay()
+    display = Display()
 
-    # Connect signal to async slot
-    counter.count_changed.connect(display, display.on_count_changed)
+    # Connect signal to slot
+    counter.count_changed.connect(display.on_count_changed)
 
-    print("Starting async counter example...")
+    print("Starting counter example...")
     print("Press Enter to increment counter, or 'q' to quit")
     print("(Notice the 1 second delay in processing)")
 
     while True:
-        # Get input asynchronously
-        line = await asyncio.get_event_loop().run_in_executor(None, input, "> ")
+        line = input("> ")
 
         if line.lower() == "q":
             break
 
         # Increment counter which will emit signal
         counter.increment()
 
-        # Give some time for async processing to complete
-        await asyncio.sleep(0.1)
-
 
 if __name__ == "__main__":
     asyncio.run(main())

examples/signal_basic.py

@@ -0,0 +1,58 @@
+# examples/signal_function_slots.py
+
+"""
+Signal-Function Slots Example
+
+This example demonstrates how to connect a signal to a standalone function 
+(not a class method). This highlights that slots can be any callable, not just methods.
+
+Steps:
+1. Define a signal in a class (Counter) that emits when its count changes.
+2. Define a standalone function that processes the emitted value.
+3. Connect the signal to this standalone function as a slot.
+4. Emit the signal by incrementing the counter and observe the function being called.
+
+Key Points:
+- Illustrates flexibility in choosing slots.
+- Standalone functions can serve as slots without additional decorators.
+"""
+
+import asyncio
+from tsignal.core import t_with_signals, t_signal
+
+
+@t_with_signals
+class Counter:
+    def __init__(self):
+        self.count = 0
+
+    @t_signal
+    def count_changed(self):
+        """Emitted when the count changes."""
+
+    def increment(self):
+        self.count += 1
+        print(f"Counter incremented to: {self.count}")
+        self.count_changed.emit(self.count)
+
+
+def print_value(value):
+    """A standalone function acting as a slot."""
+    print(f"Function Slot received value: {value}")
+
+
+async def main():
+    counter = Counter()
+    # Connect the signal to the standalone function slot
+    counter.count_changed.connect(print_value)
+
+    print("Press Enter to increment counter, or 'q' to quit.")
+    while True:
+        line = input("> ")
+        if line.lower() == "q":
+            break
+        counter.increment()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/signal_function_slots.py

@@ -0,0 +1,52 @@
+# examples/signal_lambda_slots.py
+
+"""
+Signal-Lambda Slots Example
+
+This example demonstrates connecting a signal to a lambda function slot.
+It shows that you can quickly define inline, anonymous slots for simple tasks.
+
+Steps:
+1. Define a signal in a class (Counter) that emits when its count changes.
+2. Connect the signal to a lambda function that prints the received value.
+3. Increment the counter and observe the lambda being called.
+
+Key Points:
+- Demonstrates that slots can be lambdas (anonymous functions).
+- Useful for quick, inline actions without defining a separate function or method.
+"""
+
+import asyncio
+from tsignal.core import t_with_signals, t_signal
+
+
+@t_with_signals
+class Counter:
+    def __init__(self):
+        self.count = 0
+
+    @t_signal
+    def count_changed(self):
+        """Emitted when the count changes."""
+
+    def increment(self):
+        self.count += 1
+        print(f"Counter incremented to: {self.count}")
+        self.count_changed.emit(self.count)
+
+
+async def main():
+    counter = Counter()
+    # Connect the signal to a lambda slot
+    counter.count_changed.connect(lambda v: print(f"Lambda Slot received: {v}"))
+
+    print("Press Enter to increment counter, or 'q' to quit.")
+    while True:
+        line = input("> ")
+        if line.lower() == "q":
+            break
+        counter.increment()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/signal_lamba_slots.py

@@ -1,4 +1,4 @@
-# examples/06_stock_monitor_console.py
+# examples/stock_monitor_console.py
 
 """
 Stock monitor console example.

examples/stock_monitor_console.py

@@ -1,4 +1,4 @@
-# examples/05_stock_monitor_simple_updated.py
+# examples/stock_monitor_simple.py
 
 """
 Stock monitor simple example.

examples/stock_monitor_simple.py

@@ -1,4 +1,4 @@
-# examples/07_stock_monitor_ui.py
+# examples/stock_monitor_ui.py
 
 """
 Stock monitor UI example.

examples/stock_monitor_ui.py

@@ -1,4 +1,4 @@
-# examples/03_thread_basic.py
+# examples/thread_basic.py
 
 """
 Thread Communication Example

examples/thread_basic.py

@@ -1,4 +1,4 @@
-# examples/04_thread_worker.py
+# examples/thread_worker.py
 
 """
 Thread Worker Pattern Example