0
# Animation Factories
1

2
Advanced animation creation system with factories for custom spinners and bars. Supports frame-based, scrolling, bouncing, sequential, alongside, and delayed animations with extensive customization options for creating unique visual effects.
3

4
## Capabilities
5

6
### Bar Factory
7

8
Factory function for creating custom bar animations with configurable styles, effects, and behaviors.
9

10
```python { .api }
11
def bar_factory(chars=None, *, tip=None, background=None, borders=None, errors=None):
12
    """
13
    Create custom bar animations.
14
    
15
    Parameters:
16
    - chars (Optional[str]): The sequence of increasing glyphs to fill the bar. Can be None for transparent fill.
17
    - tip (Optional[str]): The tip in front of the bar. Can be None unless chars is also None.
18
    - background (Optional[str]): The pattern to be used underneath the bar.
19
    - borders (Optional[Union[str, Tuple[str, str]]]): The pattern or patterns to be used before and after the bar.
20
    - errors (Optional[Union[str, Tuple[str, str]]]): The pattern or patterns to be used for error indication.
21
    
22
    Returns:
23
    Bar factory function that creates bar instances
24
    """
25
```
26

27
#### Usage Examples
28

29
```python
30
from alive_progress.animations import bar_factory
31
from alive_progress import alive_bar
32

33
# Create custom bar with specific characters
34
custom_bar = bar_factory(
35
    chars='▁▂▃▄▅▆▇█',
36
    background='░',
37
    tip='▶'
38
)
39

40
with alive_bar(1000, bar=custom_bar) as bar:
41
    for i in range(1000):
42
        process_item(i)
43
        bar()
44
```
45

46
### Frame Spinner Factory
47

48
Creates spinners from sequences of frames, supporting static frame sequences and custom frame timing.
49

50
```python { .api }
51
def frame_spinner_factory(*frames):
52
    """
53
    Create frame-based spinners from character sequences.
54
    
55
    Parameters:
56
    - *frames (Union[str, Tuple[str, ...]]): The frames to be displayed, split by cycles.
57
        If sent only a string, it is interpreted as frames of a single char each.
58
    
59
    Returns:
60
    Spinner factory function that creates frame-based spinners
61
    """
62
```
63

64
#### Usage Examples
65

66
```python
67
from alive_progress.animations import frame_spinner_factory
68
from alive_progress import alive_bar
69

70
# Simple rotating spinner
71
rotating_spinner = frame_spinner_factory('|/-\\')
72

73
with alive_bar(1000, spinner=rotating_spinner) as bar:
74
    for i in range(1000):
75
        process_item(i)
76
        bar()
77

78
# Complex multi-character frames
79
complex_spinner = frame_spinner_factory('◐◓◑◒')
80

81
# Custom timing - multiple cycles
82
timed_spinner = frame_spinner_factory(
83
    ('⠋', '⠙', '⠹', '⠸', '⠼'),  # First cycle
84
    ('⠴', '⠦', '⠧', '⠇', '⠏')   # Second cycle
85
)
86
```
87

88
### Scrolling Spinner Factory
89

90
Creates horizontally scrolling spinner animations with configurable direction, speed, and wrapping behavior.
91

92
```python { .api }
93
def scrolling_spinner_factory(chars, length=None, block=None, background=None, *,
94
                              right=True, hide=True, wrap=True, overlay=False):
95
    """
96
    Create horizontally scrolling spinner animations.
97
    
98
    Parameters:
99
    - chars (str): The characters to be scrolled, either together or split in blocks.
100
    - length (Optional[int]): The natural length that should be used in the style.
101
    - block (Optional[int]): If defined, split chars in blocks with this size.
102
    - background (Optional[str]): The pattern to be used besides or underneath the animations.
103
    - right (bool): The scroll direction to animate (default: True).
104
    - hide (bool): Controls whether the animation goes through the borders or not (default: True).
105
    - wrap (bool): Makes the animation wrap borders or stop when not hiding (default: True).
106
    - overlay (bool): Fixes the background in place if overlay, scrolls it otherwise (default: False).
107
    
108
    Returns:
109
    Spinner factory function that creates scrolling spinners
110
    """
111
```
112

113
#### Usage Examples
114

115
```python
116
from alive_progress.animations import scrolling_spinner_factory
117
from alive_progress import alive_bar
118

119
# Simple left-scrolling text
120
scroll_left = scrolling_spinner_factory('Processing...', right=False)
121

122
with alive_bar(1000, spinner=scroll_left) as bar:
123
    for i in range(1000):
124
        process_item(i)
125
        bar()
126

127
# Right-scrolling with custom characters
128
scroll_right = scrolling_spinner_factory('◆◇◆◇', right=True, length=8)
129

130
# Marquee-style scrolling
131
marquee = scrolling_spinner_factory(
132
    'Loading Data',
133
    length=15,
134
    right=True,
135
    wrap=True,
136
    spacing=3
137
)
138
```
139

140
### Bouncing Spinner Factory
141

142
Creates spinners with bouncing animations that move back and forth across a defined space.
143

144
```python { .api }
145
def bouncing_spinner_factory(chars, length=None, block=None, background=None, *,
146
                             right=True, hide=True, overlay=False):
147
    """
148
    Create spinners that bounce back and forth.
149
    
150
    Parameters:
151
    - chars (str): The characters to animate in bouncing motion.
152
    - length (Optional[int]): The natural length that should be used in the style.
153
    - block (Optional[int]): If defined, split chars in blocks with this size.
154
    - background (Optional[str]): The pattern to be used besides or underneath the animations.
155
    - right (bool): The initial direction to animate (default: True).
156
    - hide (bool): Controls whether the animation goes through the borders or not (default: True).
157
    - overlay (bool): Fixes the background in place if overlay, scrolls it otherwise (default: False).
158
    
159
    Returns:
160
    Spinner factory function that creates bouncing spinners
161
    """
162
```
163

164
#### Usage Examples
165

166
```python
167
from alive_progress.animations import bouncing_spinner_factory
168
from alive_progress import alive_bar
169

170
# Simple bouncing ball
171
bouncing_ball = bouncing_spinner_factory('●', length=10)
172

173
with alive_bar(1000, spinner=bouncing_ball) as bar:
174
    for i in range(1000):
175
        process_item(i)
176
        bar()
177

178
# Multi-character bouncing
179
bouncing_arrow = bouncing_spinner_factory('→', length=15, speed=2)
180

181
# Bouncing with trail effect
182
bouncing_trail = bouncing_spinner_factory('★', length=12, trail=True)
183
```
184

185
### Sequential Spinner Factory
186

187
Creates spinners with character sequences that change over time, supporting various progression patterns.
188

189
```python { .api }
190
def sequential_spinner_factory(*spinner_factories, intermix=True):
191
    """
192
    Create spinners that combine other spinners sequentially.
193
    
194
    Parameters:
195
    - *spinner_factories (spinner): The spinners to be combined.
196
    - intermix (bool): Intermixes the cycles if True, generating all possible combinations;
197
        runs each one until depletion otherwise (default: True).
198
    
199
    Returns:
200
    Spinner factory function that creates sequential spinners
201
    """
202
```
203

204
#### Usage Examples
205

206
```python
207
from alive_progress.animations import sequential_spinner_factory
208
from alive_progress import alive_bar
209

210
# Sequential combination of different spinners
211
spinner1 = frame_spinner_factory('⠀⠄⠆⠇⡇⡗⡟⡿⣿')
212
spinner2 = frame_spinner_factory('░▒▓█')
213
loading_seq = sequential_spinner_factory(spinner1, spinner2)
214

215
with alive_bar(1000, spinner=loading_seq) as bar:
216
    for i in range(1000):
217
        process_item(i)
218
        bar()
219

220
# Multiple spinner sequence without intermixing
221
fast_spinner = frame_spinner_factory('|/-\\')
222
slow_spinner = frame_spinner_factory('◐◓◑◒')
223
brightness = sequential_spinner_factory(fast_spinner, slow_spinner, intermix=False)
224

225
# Three-phase sequential animation
226
phase1 = frame_spinner_factory('123')
227
phase2 = frame_spinner_factory('456')
228
phase3 = frame_spinner_factory('789🚀')
229
countdown = sequential_spinner_factory(phase1, phase2, phase3)
230
```
231

232
### Alongside Spinner Factory
233

234
Creates spinners that display multiple elements together, supporting parallel animations and composite effects.
235

236
```python { .api }
237
def alongside_spinner_factory(*spinner_factories, pivot=None):
238
    """
239
    Create spinners that display multiple elements together.
240
    
241
    Parameters:
242
    - *spinner_factories (spinner): The spinners to be combined.
243
    - pivot (Optional[int]): The index of the spinner to dictate the animation cycles.
244
        If None, the whole animation will be compiled into a unique cycle.
245
    
246
    Returns:
247
    Spinner factory function that creates alongside spinners
248
    """
249
```
250

251
#### Usage Examples
252

253
```python
254
from alive_progress.animations import alongside_spinner_factory, frame_spinner_factory
255
from alive_progress import alive_bar
256

257
# Combine multiple spinners
258
spinner1 = frame_spinner_factory('|/-\\')
259
spinner2 = frame_spinner_factory('◐◓◑◒')
260
combined = alongside_spinner_factory(spinner1, spinner2)
261

262
with alive_bar(1000, spinner=combined) as bar:
263
    for i in range(1000):
264
        process_item(i)
265
        bar()
266

267
# Text and animation together with pivot control
268
text_spinner = frame_spinner_factory(('Loading.', 'Loading..', 'Loading...'))
269
symbol_spinner = frame_spinner_factory('⠋⠙⠹⠸')
270
loading_combo = alongside_spinner_factory(text_spinner, symbol_spinner, pivot=0)
271
```
272

273
### Delayed Spinner Factory
274

275
Creates spinners with timing delays and custom pacing for sophisticated animation control.
276

277
```python { .api }
278
def delayed_spinner_factory(spinner_factory, copies, offset=1, *, dynamic=True):
279
    """
280
    Create spinners with timing delays and custom pacing.
281
    
282
    Parameters:
283
    - spinner_factory (spinner): The source spinner.
284
    - copies (int): The number of copies.
285
    - offset (int): The offset to be applied incrementally to each copy (default: 1).
286
    - dynamic (bool): Dynamically changes the number of copies based on available space (default: True).
287
    
288
    Returns:
289
    Spinner factory function that creates delayed spinners
290
    """
291
```
292

293
#### Usage Examples
294

295
```python
296
from alive_progress.animations import delayed_spinner_factory, frame_spinner_factory
297
from alive_progress import alive_bar
298

299
# Base spinner
300
base = frame_spinner_factory('⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏')
301

302
# Create delayed spinner with 3 copies
303
delayed = delayed_spinner_factory(base, copies=3, offset=1)
304

305
with alive_bar(1000, spinner=delayed) as bar:
306
    for i in range(1000):
307
        process_item(i)
308
        bar()
309

310
# More copies with larger offset
311
multi_copy = delayed_spinner_factory(base, copies=5, offset=2)
312

313
# Fixed number of copies (non-dynamic)
314
fixed_copies = delayed_spinner_factory(
315
    base, 
316
    copies=4,
317
    offset=1,
318
    dynamic=False  # Won't adjust based on available space
319
)
320
```
321

322
### Spinner Player Utility
323

324
Utility function for playing and controlling spinner animations programmatically.
325

326
```python { .api }
327
def spinner_player(spinner):
328
    """
329
    Create an infinite generator that plays all cycles of a spinner indefinitely.
330
    
331
    Parameters:
332
    - spinner: Spinner factory to play
333
    
334
    Returns:
335
    Generator that yields animation frames indefinitely
336
    """
337
```
338

339
#### Usage Examples
340

341
```python
342
from alive_progress.animations import spinner_player, frame_spinner_factory
343

344
# Create and play spinner
345
spinner = frame_spinner_factory('⠋⠙⠹⠸')
346
player = spinner_player(spinner)
347

348
# Manually control animation
349
import time
350
for i, frame in enumerate(player):
351
    print(f'\r{frame}', end='', flush=True)
352
    time.sleep(0.1)
353
    # Stop after some condition
354
    if i > 50:  # Stop after 50 frames
355
        break
356
```
357

358
### Advanced Factory Patterns
359

360
#### Chaining Factories
361

362
```python
363
from alive_progress.animations import (
364
    frame_spinner_factory, 
365
    delayed_spinner_factory,
366
    scrolling_spinner_factory
367
)
368

369
# Create base animation
370
base_frames = ['◐', '◓', '◑', '◒']
371
base_spinner = frame_spinner_factory(base_frames)
372

373
# Add delay
374
delayed_spinner = delayed_spinner_factory(base_spinner, delay=10)
375

376
# Use in progress bar
377
with alive_bar(1000, spinner=delayed_spinner) as bar:
378
    pass
379
```
380

381
#### Conditional Factory Selection
382

383
```python
384
import os
385
from alive_progress.animations import frame_spinner_factory, scrolling_spinner_factory
386

387
# Choose factory based on environment
388
if os.getenv('SIMPLE_ANIMATIONS'):
389
    spinner_factory = frame_spinner_factory(['|', '/', '-', '\\'])
390
else:
391
    spinner_factory = scrolling_spinner_factory('Processing...', length=15)
392

393
with alive_bar(1000, spinner=spinner_factory) as bar:
394
    pass
395
```
396

397
#### Performance Optimization
398

399
```python
400
# For high-performance scenarios, use simpler animations
401
fast_spinner = frame_spinner_factory(['.', 'o', 'O'])  # Minimal frames
402

403
# For visual appeal, use complex animations  
404
beautiful_spinner = alongside_spinner_factory(
405
    scrolling_spinner_factory('Loading', right=True),
406
    bouncing_spinner_factory('●', length=10),
407
    separator=' | '
408
)
409

410
# Choose based on performance requirements
411
spinner = fast_spinner if high_performance_mode else beautiful_spinner
412
```