0
# Status and Result Handling
1

2
Methods for completing spinners with status indicators and custom symbols. These methods stop the spinner and display a final status message that persists in the terminal.
3

4
## Capabilities
5

6
### Success Completion
7

8
Complete the spinner with a success indicator, typically used when operations complete successfully.
9

10
```python { .api }
11
def succeed(self, text=None):
12
    """
13
    Stop spinner and show success symbol with text.
14
    
15
    Parameters:
16
    - text (str, optional): Text to display with success symbol.
17
                           If None, uses current spinner text.
18
    
19
    Returns:
20
    - Halo: Self for method chaining
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
from halo import Halo
28
import time
29

30
spinner = Halo(text='Downloading file', spinner='dots')
31
spinner.start()
32
time.sleep(2)
33

34
# Complete with success
35
spinner.succeed('✓ File downloaded successfully')
36
# Output: ✓ File downloaded successfully
37
```
38

39
### Failure Completion
40

41
Complete the spinner with an error indicator for failed operations.
42

43
```python { .api }
44
def fail(self, text=None):
45
    """
46
    Stop spinner and show error symbol with text.
47
    
48
    Parameters:
49
    - text (str, optional): Text to display with error symbol.
50
                           If None, uses current spinner text.
51
    
52
    Returns:
53
    - Halo: Self for method chaining
54
    """
55
```
56

57
**Usage Example:**
58

59
```python
60
from halo import Halo
61
import time
62

63
spinner = Halo(text='Connecting to server', spinner='dots')
64
spinner.start()
65
time.sleep(2)
66

67
try:
68
    # Simulate operation that might fail
69
    raise ConnectionError("Unable to connect")
70
except ConnectionError as e:
71
    spinner.fail(f'✗ Connection failed: {e}')
72
    # Output: ✗ Connection failed: Unable to connect
73
```
74

75
### Warning Completion
76

77
Complete the spinner with a warning indicator for operations that completed with issues.
78

79
```python { .api }
80
def warn(self, text=None):
81
    """
82
    Stop spinner and show warning symbol with text.
83
    
84
    Parameters:
85
    - text (str, optional): Text to display with warning symbol.
86
                           If None, uses current spinner text.
87
    
88
    Returns:
89
    - Halo: Self for method chaining
90
    """
91
```
92

93
**Usage Example:**
94

95
```python
96
from halo import Halo
97
import time
98

99
spinner = Halo(text='Processing data', spinner='dots')
100
spinner.start()
101
time.sleep(2)
102

103
# Complete with warning
104
spinner.warn('⚠ Data processed with 3 warnings')
105
# Output: ⚠ Data processed with 3 warnings
106
```
107

108
### Info Completion
109

110
Complete the spinner with an info indicator for informational messages.
111

112
```python { .api }
113
def info(self, text=None):
114
    """
115
    Stop spinner and show info symbol with text.
116
    
117
    Parameters:
118
    - text (str, optional): Text to display with info symbol.
119
                           If None, uses current spinner text.
120
    
121
    Returns:
122
    - Halo: Self for method chaining
123
    """
124
```
125

126
**Usage Example:**
127

128
```python
129
from halo import Halo
130
import time
131

132
spinner = Halo(text='Scanning files', spinner='dots')
133
spinner.start()  
134
time.sleep(2)
135

136
# Complete with info
137
spinner.info('ℹ Scan completed - 42 files found')
138
# Output: ℹ Scan completed - 42 files found
139
```
140

141
### Custom Symbol Completion
142

143
Complete the spinner with a custom symbol and text for specialized status indicators.
144

145
```python { .api }
146
def stop_and_persist(self, symbol=" ", text=None):
147
    """
148
    Stop spinner and display custom symbol with text.
149
    
150
    Parameters:
151
    - symbol (str): Symbol to display (default: " ")
152
    - text (str, optional): Text to display with symbol.
153
                           If None, uses current spinner text.
154
    
155
    Returns:
156
    - Halo: Self for method chaining
157
    """
158
```
159

160
**Usage Example:**
161

162
```python
163
from halo import Halo
164
import time
165

166
spinner = Halo(text='Deploying application', spinner='dots')
167
spinner.start()
168
time.sleep(3)
169

170
# Custom completion symbols
171
spinner.stop_and_persist('🚀', 'Application deployed to production')
172
# Output: 🚀 Application deployed to production
173

174
# Another example
175
spinner2 = Halo(text='Running tests', spinner='star')  
176
spinner2.start()
177
time.sleep(2)
178
spinner2.stop_and_persist('📊', 'Tests completed: 45 passed, 0 failed')
179
# Output: 📊 Tests completed: 45 passed, 0 failed
180
```
181

182
## Status Symbols
183

184
The standard status symbols used by Halo (from the `log_symbols` package):
185

186
- **Success**: `✓` (green checkmark)
187
- **Error**: `✗` (red X)  
188
- **Warning**: `⚠` (yellow warning triangle)
189
- **Info**: `ℹ` (blue info symbol)
190

191
These symbols automatically adapt to the terminal's capabilities and may display as ASCII alternatives on unsupported terminals.
192

193
## Advanced Status Handling
194

195
### Conditional Status
196

197
```python
198
from halo import Halo
199
import time
200
import random
201

202
def process_data():
203
    spinner = Halo(text='Processing data', spinner='dots')
204
    spinner.start()
205
    
206
    # Simulate processing
207
    time.sleep(2)
208
    success_rate = random.random()
209
    
210
    if success_rate > 0.8:
211
        spinner.succeed('✓ Processing completed successfully')
212
    elif success_rate > 0.5:
213
        spinner.warn('⚠ Processing completed with warnings')
214
    else:
215
        spinner.fail('✗ Processing failed')
216

217
process_data()
218
```
219

220
### Status with Details
221

222
```python
223
from halo import Halo
224
import time
225

226
def backup_files():
227
    files = ['config.json', 'data.db', 'logs.txt']
228
    
229
    spinner = Halo(text='Starting backup', spinner='dots')
230
    spinner.start()
231
    
232
    backed_up = []
233
    failed = []
234
    
235
    for file in files:
236
        spinner.text = f'Backing up {file}'
237
        time.sleep(1)
238
        
239
        # Simulate success/failure
240
        if file != 'logs.txt':  # Simulate logs.txt failing
241
            backed_up.append(file)
242
        else:
243
            failed.append(file)
244
    
245
    if not failed:
246
        spinner.succeed(f'✓ Backup completed - {len(backed_up)} files backed up')
247
    elif backed_up:
248
        spinner.warn(f'⚠ Partial backup - {len(backed_up)} succeeded, {len(failed)} failed')
249
    else:
250
        spinner.fail('✗ Backup failed - no files backed up')
251

252
backup_files()
253
```
254

255
### Status with Timing
256

257
```python
258
from halo import Halo
259
import time
260

261
def timed_operation():
262
    start_time = time.time()
263
    
264
    spinner = Halo(text='Running operation', spinner='dots')
265
    spinner.start()
266
    
267
    # Simulate work
268
    time.sleep(3)
269
    
270
    end_time = time.time()
271
    duration = round(end_time - start_time, 2)
272
    
273
    spinner.succeed(f'✓ Operation completed in {duration}s')
274

275
timed_operation()
276
```
277

278
### Chained Operations
279

280
```python
281
from halo import Halo
282
import time
283

284
def multi_step_process():
285
    # Step 1
286
    spinner = Halo(text='Initializing', spinner='dots')
287
    spinner.start()
288
    time.sleep(1)
289
    spinner.succeed('✓ Initialization complete')
290
    
291
    # Step 2  
292
    spinner = Halo(text='Processing data', spinner='star')
293
    spinner.start()
294
    time.sleep(2)
295
    spinner.succeed('✓ Data processing complete')
296
    
297
    # Step 3
298
    spinner = Halo(text='Finalizing', spinner='dots')
299
    spinner.start() 
300
    time.sleep(1)
301
    spinner.succeed('✓ All operations completed successfully')
302

303
multi_step_process()
304
```