0
# Alive Progress
1

2
A new kind of Progress Bar with real-time throughput, ETA, and very cool animations! Alive Progress provides an animated progress bar library for Python that displays real-time animated progress indicators with comprehensive visual feedback including live spinners, accurate ETA calculations, multithreaded bar updates, and extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: alive-progress
7
- **Language**: Python  
8
- **Installation**: `pip install alive-progress`
9
- **Python Version**: >= 3.9
10

11
## Core Imports
12

13
```python
14
from alive_progress import alive_bar, alive_it, config_handler
15
```
16

17
Additional imports for styles and customization:
18

19
```python
20
from alive_progress.styles import show_spinners, show_bars, show_themes, showtime, Show, BARS, SPINNERS, THEMES
21
from alive_progress.animations import bar_factory, frame_spinner_factory, scrolling_spinner_factory
22
from alive_progress.tools import print_chars
23
```
24

25
## Basic Usage
26

27
### Simple Progress Bar
28

29
```python
30
from alive_progress import alive_bar
31
import time
32

33
# Basic progress bar with known total
34
with alive_bar(100, title='Processing') as bar:
35
    for i in range(100):
36
        time.sleep(0.1)  # simulate work
37
        bar()  # advance the bar
38
```
39

40
### Iterator Adapter
41

42
```python
43
from alive_progress import alive_it
44
import time
45

46
items = range(100)
47
for item in alive_it(items, title='Processing Items'):
48
    time.sleep(0.05)  # simulate processing
49
    # No need to call bar() - automatically managed
50
```
51

52
### Unknown Total
53

54
```python
55
from alive_progress import alive_bar
56

57
# Progress bar without known total
58
with alive_bar(title='Processing') as bar:
59
    for item in some_iterable():
60
        process_item(item)  # simulate work
61
        bar()  # advance counter
62
```
63

64
## Architecture
65

66
Alive Progress uses a multithreaded architecture with the following key components:
67

68
- **Progress Bar Context**: Main `alive_bar` context manager that orchestrates all components
69
- **Bar Handle**: Returned object providing control interface (`bar()`, properties, methods)
70
- **Animation Engine**: Separate thread managing real-time visual updates and spinner animations
71
- **Hook Manager**: Intercepts and enriches print/logging output during progress tracking
72
- **Configuration System**: Global and local settings management for appearance and behavior
73
- **Terminal Abstraction**: Cross-platform terminal interaction supporting TTY, non-TTY, and Jupyter environments
74

75
The design enables smooth visual feedback while maintaining low CPU overhead through calibrated refresh rates and efficient animation compilation.
76

77
## Capabilities
78

79
### Progress Tracking
80

81
Core progress bar functionality with context managers, iterator adapters, manual and automatic modes, pause/resume capabilities, and comprehensive progress monitoring.
82

83
```python { .api }
84
def alive_bar(total: Optional[int] = None, *, calibrate: Optional[int] = None, **options: Any):
85
    """Create an alive progress bar context manager."""
86

87
def alive_it(it: Collection[T], total: Optional[int] = None, *, 
88
             finalize: Callable[[Any], None] = None, 
89
             calibrate: Optional[int] = None, **options: Any) -> Iterable[T]:
90
    """Iterator adapter that automatically tracks progress."""
91
```
92

93
[Progress Tracking](./progress-tracking.md)
94

95
### Configuration Management
96

97
Global and local configuration system for customizing bar appearance, behavior, widgets, and output formatting across all progress bars or individual instances.
98

99
```python { .api }
100
config_handler.set_global(**options)
101
config_handler.reset()
102
config_handler.create_context(**options)
103
```
104

105
[Configuration](./configuration.md)
106

107
### Styles and Themes
108

109
Comprehensive styling system with predefined spinners, bars, and themes, plus factories for creating custom animations and visual effects.
110

111
```python { .api }
112
def showtime(show=Show.SPINNERS, *, fps=None, length=None, pattern=None):
113
    """Display animated demos of all available styles."""
114

115
def show_spinners(*, fps=None, length=None, pattern=None):
116
    """Show all available spinner animations."""
117

118
def show_bars(*, fps=None, length=None, pattern=None):
119
    """Show all available bar styles."""
120

121
def show_themes(*, fps=None, length=None, pattern=None):
122
    """Show all available themes."""
123
```
124

125
[Styles and Themes](./styles-themes.md)
126

127
### Animation Factories
128

129
Advanced animation creation system with factories for custom spinners and bars, supporting frame-based, scrolling, bouncing, sequential, and delayed animations.
130

131
```python { .api }
132
def bar_factory(**options):
133
    """Create custom bar animations."""
134

135
def frame_spinner_factory(frames, **options):
136
    """Create frame-based spinners."""
137

138
def scrolling_spinner_factory(chars, **options):
139
    """Create horizontally scrolling spinner animations."""
140

141
def bouncing_spinner_factory(chars, **options):
142
    """Create spinners that bounce back and forth."""
143
```
144

145
[Animation Factories](./animation-factories.md)
146

147
### Development Tools
148

149
Development and debugging utilities for character discovery and terminal testing, primarily useful for creating custom animations and testing Unicode support.
150

151
```python { .api }
152
def print_chars(line_length: int = 32, max_char: int = 0x20000):
153
    """Print Unicode characters to help find characters for custom spinners/bars."""
154
```
155

156
[Development Tools](./development-tools.md)
157

158
## Types
159

160
```python { .api }
161
from typing import Optional, Any, Callable, Collection, Iterable, TypeVar
162
from collections.abc import Collection, Iterable
163
from types import FunctionType
164
from enum import Enum
165

166
T = TypeVar('T')
167

168
class Show(Enum):
169
    SPINNERS = "SPINNERS"
170
    BARS = "BARS" 
171
    THEMES = "THEMES"
172

173
# Bar Handle Interface (returned by alive_bar context manager)
174
class AliveBarHandle:
175
    # Callable interface
176
    def __call__(self, count: int = 1, *, skipped: bool = False) -> None: ...
177
    
178
    # Read-only properties
179
    @property
180
    def current(self) -> Union[int, float]: ...
181
    @property  
182
    def monitor(self) -> str: ...
183
    @property
184
    def rate(self) -> str: ...
185
    @property
186
    def eta(self) -> str: ...
187
    @property
188
    def elapsed(self) -> float: ...
189
    @property
190
    def receipt(self) -> str: ...
191
    
192
    # Assignable properties
193
    @property
194
    def text(self) -> Optional[str]: ...
195
    @text.setter
196
    def text(self, value: Optional[str]) -> None: ...
197
    
198
    @property
199
    def title(self) -> Optional[str]: ...
200
    @title.setter  
201
    def title(self, value: Optional[str]) -> None: ...
202
    
203
    # Methods
204
    def pause(self) -> Any: ...  # Context manager
205
```