0
# Styles and Themes
1

2
Comprehensive styling system with predefined spinners, bars, and themes, plus demonstration tools for previewing all available styles. Provides both ready-to-use visual elements and the foundation for custom animation creation.
3

4
## Capabilities
5

6
### Style Demonstration
7

8
Interactive demonstration functions that display animated previews of all available styles, helping users choose and test visual elements.
9

10
```python { .api }
11
def showtime(show=Show.SPINNERS, *, fps=None, length=None, pattern=None):
12
    """
13
    Display animated demos of all available styles.
14
    
15
    Parameters:
16
    - show (Show): Type of styles to display (Show.SPINNERS, Show.BARS, Show.THEMES)
17
    - fps (Optional[float]): Frames per second for animation
18
    - length (Optional[int]): Bar length for display
19
    - pattern (Optional[Pattern]): Regex pattern to filter displayed items
20
    """
21

22
def show_spinners(*, fps=None, length=None, pattern=None):
23
    """
24
    Show all available spinner animations.
25
    
26
    Parameters:
27
    - fps (Optional[float]): Animation speed in frames per second
28
    - length (Optional[int]): Bar length for spinner display
29
    - pattern (Optional[Pattern]): Filter spinners by name pattern
30
    """
31

32
def show_bars(*, fps=None, length=None, pattern=None):
33
    """
34
    Show all available bar styles.
35
    
36
    Parameters:
37
    - fps (Optional[float]): Animation speed for bars
38
    - length (Optional[int]): Bar length for display
39
    - pattern (Optional[Pattern]): Filter bars by name pattern
40
    """
41

42
def show_themes(*, fps=None, length=None, pattern=None):
43
    """
44
    Show all available themes.
45
    
46
    Parameters:
47
    - fps (Optional[float]): Animation speed for theme preview
48
    - length (Optional[int]): Bar length for display
49
    - pattern (Optional[Pattern]): Filter themes by name pattern
50
    """
51
```
52

53
#### Usage Examples
54

55
```python
56
from alive_progress.styles import showtime, show_spinners, show_bars, show_themes, Show
57
import re
58

59
# Show all spinners
60
show_spinners()
61

62
# Show all bars
63
show_bars()
64

65
# Show all themes
66
show_themes()
67

68
# Show all styles at once
69
showtime(Show.SPINNERS)
70
showtime(Show.BARS) 
71
showtime(Show.THEMES)
72

73
# Custom animation speed and bar length
74
show_spinners(fps=10, length=30)
75

76
# Filter by pattern
77
show_spinners(pattern=re.compile(r'.*dot.*'))
78
show_bars(pattern=re.compile(r'solid.*'))
79
```
80

81
### Style Collections
82

83
Built-in collections of predefined visual elements that can be used directly in alive_bar configuration.
84

85
```python { .api }
86
SPINNERS: Dict[str, SpinnerFactory]
87
"""Dictionary of all available spinner styles."""
88

89
BARS: Dict[str, BarFactory]  
90
"""Dictionary of all available bar styles."""
91

92
THEMES: Dict[str, Dict[str, Any]]
93
"""Dictionary of all available themes (combinations of spinner, bar, and unknown styles)."""
94
```
95

96
#### Available Spinners
97

98
Common spinner styles include:
99
- `'classic'`: Traditional rotating characters
100
- `'dots'`: Pulsing dots animation
101
- `'filling'`: Filling container effect
102
- `'scrolling'`: Scrolling characters
103
- `'bouncing'`: Bouncing ball effect
104
- `'sequential'`: Sequential character changes
105
- `'alongside'`: Multiple elements together
106
- `'delayed'`: Timing-delayed animations
107

108
#### Available Bars
109

110
Common bar styles include:
111
- `'classic'`: Traditional solid progress bar
112
- `'smooth'`: Smooth gradient transitions
113
- `'filling'`: Container filling effect
114
- `'blocks'`: Block-based progress
115
- `'underflows'`: Shows negative progress
116
- `'overflows'`: Shows excess progress
117

118
#### Available Themes
119

120
Predefined themes combining spinner, bar, and unknown styles:
121
- `'smooth'`: Modern smooth animations
122
- `'classic'`: Traditional terminal appearance
123
- `'ascii'`: ASCII-only characters for compatibility
124

125
#### Usage Examples
126

127
```python
128
from alive_progress import alive_bar
129
from alive_progress.styles import SPINNERS, BARS, THEMES
130

131
# Use specific spinner and bar
132
with alive_bar(1000, spinner='dots', bar='smooth') as bar:
133
    pass
134

135
# Use predefined theme
136
with alive_bar(1000, theme='classic') as bar:
137
    pass
138

139
# Inspect available options
140
print("Available spinners:", list(SPINNERS.keys()))
141
print("Available bars:", list(BARS.keys()))
142
print("Available themes:", list(THEMES.keys()))
143

144
# Mix and match
145
with alive_bar(1000, 
146
               spinner='bouncing',
147
               bar='blocks',
148
               unknown='scrolling') as bar:
149
    pass
150
```
151

152
### Show Enumeration
153

154
Enumeration for specifying which type of styles to display in showtime demonstrations.
155

156
```python { .api }
157
class Show(Enum):
158
    """Enumeration for showtime display types."""
159
    SPINNERS = "SPINNERS"
160
    BARS = "BARS"
161
    THEMES = "THEMES" 
162
```
163

164
#### Usage Examples
165

166
```python
167
from alive_progress.styles import showtime, Show
168

169
# Show specific style types
170
showtime(Show.SPINNERS)
171
showtime(Show.BARS)
172
showtime(Show.THEMES)
173

174
# With additional parameters
175
showtime(Show.SPINNERS, fps=15, length=25)
176
```
177

178
### Style Customization
179

180
Using custom styles with the predefined collections and style system.
181

182
#### Using Built-in Styles
183

184
```python
185
# Direct style names
186
with alive_bar(1000, spinner='dots', bar='smooth') as bar:
187
    pass
188

189
# Using SPINNERS/BARS dictionaries
190
from alive_progress.styles import SPINNERS, BARS
191

192
dot_spinner = SPINNERS['dots']
193
smooth_bar = BARS['smooth']
194

195
with alive_bar(1000, spinner=dot_spinner, bar=smooth_bar) as bar:
196
    pass
197
```
198

199
#### Theme Application
200

201
```python
202
from alive_progress.styles import THEMES
203

204
# Apply theme manually
205
theme_config = THEMES['classic']
206
with alive_bar(1000, **theme_config) as bar:
207
    pass
208

209
# Override theme elements
210
with alive_bar(1000, theme='smooth', spinner='dots') as bar:
211
    pass  # Uses smooth theme but with dots spinner
212
```
213

214
### Advanced Styling Patterns
215

216
#### Dynamic Style Selection
217

218
```python
219
import random
220
from alive_progress.styles import SPINNERS, BARS
221

222
# Random style selection
223
spinner_name = random.choice(list(SPINNERS.keys()))
224
bar_name = random.choice(list(BARS.keys()))
225

226
with alive_bar(1000, spinner=spinner_name, bar=bar_name) as bar:
227
    pass
228
```
229

230
#### Environment-based Styling  
231

232
```python
233
import os
234
from alive_progress.styles import THEMES
235

236
# ASCII mode for restricted environments
237
if os.getenv('TERM') == 'dumb':
238
    theme = 'ascii'
239
else:
240
    theme = 'smooth'
241

242
with alive_bar(1000, theme=theme) as bar:
243
    pass
244
```
245

246
#### Custom Theme Creation
247

248
```python
249
# Define custom theme
250
my_theme = {
251
    'spinner': 'bouncing',
252
    'bar': 'blocks', 
253
    'unknown': 'scrolling',
254
    'length': 50,
255
    'dual_line': True
256
}
257

258
# Use custom theme
259
with alive_bar(1000, **my_theme) as bar:
260
    pass
261

262
# Or extend existing theme
263
from alive_progress.styles import THEMES
264
extended_theme = {**THEMES['classic'], 'length': 60, 'dual_line': True}
265
with alive_bar(1000, **extended_theme) as bar:
266
    pass
267
```
268

269
### Style Discovery and Testing
270

271
#### Interactive Style Testing
272

273
```python
274
from alive_progress.styles import show_spinners, SPINNERS
275
import time
276

277
# Preview all spinners
278
show_spinners()
279

280
# Test specific spinner in actual progress bar
281
for spinner_name in ['dots', 'bouncing', 'scrolling']:
282
    print(f"Testing {spinner_name} spinner:")
283
    with alive_bar(50, spinner=spinner_name, title=f'{spinner_name} test') as bar:
284
        for i in range(50):
285
            time.sleep(0.1)
286
            bar()
287
    print()
288
```
289

290
#### Performance Considerations
291

292
```python
293
# For high throughput, use simpler styles
294
with alive_bar(1000000, 
295
               spinner=None,  # Disable spinner for maximum performance
296
               refresh_secs=0.1) as bar:
297
    for i in range(1000000):
298
        fast_operation()
299
        bar()
300

301
# For visual appeal with moderate performance
302
with alive_bar(10000, 
303
               theme='smooth',
304
               refresh_secs=0.05) as bar:
305
    for i in range(10000):
306
        moderate_operation()
307
        bar()
308
```