0
# Signals and Event Handling
1

2
Model lifecycle event system that allows registering custom handlers for model save and delete operations. Signals provide hooks to execute custom logic before or after these operations.
3

4
## Capabilities
5

6
### Signal Decorators
7

8
Decorators for registering signal handlers on model lifecycle events.
9

10
```python { .api }
11
from tortoise.signals import pre_save, post_save, pre_delete, post_delete
12

13
@pre_save(*senders):
14
    """
15
    Register models pre_save signal handler.
16
    
17
    Args:
18
        *senders: Model classes to listen for
19
        
20
    Returns:
21
        Function decorator for signal handler
22
    """
23

24
@post_save(*senders):
25
    """
26
    Register models post_save signal handler.
27
    
28
    Args:
29
        *senders: Model classes to listen for
30
        
31
    Returns:
32
        Function decorator for signal handler
33
    """
34

35
@pre_delete(*senders):
36
    """
37
    Register models pre_delete signal handler.
38
    
39
    Args:
40
        *senders: Model classes to listen for
41
        
42
    Returns:
43
        Function decorator for signal handler
44
    """
45

46
@post_delete(*senders):
47
    """
48
    Register models post_delete signal handler.
49
    
50
    Args:
51
        *senders: Model classes to listen for
52
        
53
    Returns:
54
        Function decorator for signal handler
55
    """
56
```
57

58
### Signal Types
59

60
```python { .api }
61
from tortoise.signals import Signals
62

63
class Signals(Enum):
64
    """Enumeration of available signal types."""
65
    pre_save = "pre_save"
66
    post_save = "post_save"
67
    pre_delete = "pre_delete" 
68
    post_delete = "post_delete"
69
```
70

71
## Usage Examples
72

73
### Basic Signal Handler
74

75
```python
76
from tortoise.signals import pre_save, post_save
77
from myapp.models import User
78

79
@pre_save(User)
80
async def user_pre_save(sender, instance, **kwargs):
81
    """Called before user is saved."""
82
    print(f"About to save user: {instance.name}")
83

84
@post_save(User)
85
async def user_post_save(sender, instance, created, **kwargs):
86
    """Called after user is saved."""
87
    if created:
88
        print(f"Created new user: {instance.name}")
89
    else:
90
        print(f"Updated user: {instance.name}")
91
```
92

93
### Multiple Model Handler
94

95
```python
96
from tortoise.signals import post_delete
97
from myapp.models import User, Profile
98

99
@post_delete(User, Profile)
100
async def cleanup_after_delete(sender, instance, **kwargs):
101
    """Called after user or profile deletion."""
102
    print(f"Deleted {sender.__name__}: {instance}")
103
```
104

105
### Signal Handler Parameters
106

107
Signal handlers receive the following parameters:
108

109
- **sender**: The model class that triggered the signal
110
- **instance**: The model instance being saved/deleted
111
- **created**: (post_save only) Boolean indicating if instance was created
112
- **kwargs**: Additional keyword arguments
113

114
## Signal Execution
115

116
- **pre_save**: Called before `save()` method execution
117
- **post_save**: Called after successful `save()` method execution  
118
- **pre_delete**: Called before `delete()` method execution
119
- **post_delete**: Called after successful `delete()` method execution
120

121
Signals are executed synchronously during the model operation and can affect the operation's outcome if they raise exceptions.