0
# Manager Operations
1

2
Core manager functionality for creating and controlling progress bar displays. Managers handle TTY detection, coordinate multiple concurrent progress bars, and provide environment-specific rendering (terminal vs Jupyter notebook).
3

4
## Capabilities
5

6
### Manager Factory
7

8
Get the appropriate manager instance based on the environment, automatically detecting TTY capabilities and notebook contexts.
9

10
```python { .api }
11
def get_manager(stream=None, counter_class=Counter, **kwargs):
12
    """
13
    Get a manager instance appropriate for the current environment.
14

15
    Parameters:
16
    - stream: Output stream (default: sys.__stdout__)
17
    - counter_class: Progress bar class (default: Counter)
18
    - **kwargs: Additional arguments passed to manager
19

20
    Returns:
21
    Manager or NotebookManager instance based on environment
22

23
    If running in a Jupyter notebook, returns NotebookManager.
24
    Otherwise returns Manager with TTY detection and auto-disable for non-TTY streams.
25
    """
26
```
27

28
### Terminal Manager
29

30
Manager for terminal-based progress bar display with TTY integration, companion stream handling, and resize support.
31

32
```python { .api }
33
class Manager:
34
    def __init__(self, stream=None, counter_class=Counter, status_bar_class=StatusBar, 
35
                 set_scroll=True, companion_stream=None, enabled=True, 
36
                 no_resize=False, threaded=None, width=None, **kwargs):
37
        """
38
        Terminal manager for progress bars.
39

40
        Parameters:
41
        - stream: Output stream (default: sys.__stdout__)
42
        - counter_class: Counter class for progress bars (default: Counter)
43
        - status_bar_class: Status bar class (default: StatusBar)
44
        - set_scroll: Enable scroll area redefinition (default: True)
45
        - companion_stream: Secondary stream for coordinate handling
46
        - enabled: Manager status (default: True)
47
        - no_resize: Disable window resize handling (default: False)
48
        - threaded: Defer resize handling until next write (default: auto-detect)
49
        - width: Static output width override
50
        - **kwargs: Default values for counter creation
51
        """
52

53
    def counter(self, **kwargs):
54
        """
55
        Create a new progress bar counter.
56

57
        Parameters:
58
        - total: Total expected count
59
        - desc: Description text
60
        - unit: Unit label for rate display
61
        - leave: Leave bar visible after completion (default: True)
62
        - **kwargs: Additional counter options
63

64
        Returns:
65
        Counter instance
66
        """
67

68
    def status_bar(self, *args, **kwargs):
69
        """
70
        Create a status bar for text updates.
71

72
        Parameters:
73
        - *args: Direct status text arguments
74
        - **kwargs: Status bar configuration options
75

76
        Returns:
77
        StatusBar instance
78
        """
79

80
    def stop(self):
81
        """
82
        Stop the manager and clean up all counters.
83
        Disables all associated counters and restores terminal state.
84
        """
85

86
    def write(self, output='', flush=True, counter=None, **kwargs):
87
        """
88
        Write output to the display.
89

90
        Parameters:
91
        - output: Text or callable to output
92
        - flush: Flush streams after writing (default: True)
93
        - counter: Associated counter for positioning
94
        - **kwargs: Arguments passed to callable output
95
        """
96

97
    def remove(self, counter):
98
        """
99
        Remove counter from manager.
100

101
        Parameters:
102
        - counter: Counter or StatusBar instance to remove
103

104
        Generally this method should not be called directly.
105
        Use counter.close() instead.
106
        """
107

108
    def __enter__(self):
109
        """
110
        Context manager entry.
111
        
112
        Returns:
113
        Manager instance
114
        """
115

116
    def __exit__(self, *args):
117
        """
118
        Context manager exit. Calls stop() to clean up.
119
        """
120
```
121

122
### Notebook Manager
123

124
Manager optimized for Jupyter notebook environments with HTML output and DisplayHandle integration.
125

126
```python { .api }
127
class NotebookManager:
128
    def __init__(self, counter_class=Counter, status_bar_class=StatusBar, 
129
                 enabled=True, width=100, **kwargs):
130
        """
131
        Notebook manager for Jupyter environments.
132

133
        Parameters:
134
        - counter_class: Counter class (default: Counter)
135
        - status_bar_class: Status bar class (default: StatusBar)
136
        - enabled: Manager status (default: True)
137
        - width: Static output width (default: 100)
138
        - **kwargs: Default values for counter creation
139

140
        Note: stream, set_scroll, companion_stream, no_resize, and threaded
141
        parameters are ignored in notebook environments.
142
        """
143

144
    def counter(self, **kwargs):
145
        """
146
        Create a progress bar counter for notebook display.
147

148
        Returns:
149
        Counter instance configured for HTML output
150
        """
151

152
    def status_bar(self, *args, **kwargs):
153
        """
154
        Create a status bar for notebook display.
155

156
        Returns:
157
        StatusBar instance configured for HTML output
158
        """
159

160
    def write(self, output='', flush=True, counter=None, **kwargs):
161
        """
162
        Write output to the display.
163

164
        Parameters:
165
        - output: Text or callable to output
166
        - flush: Flush streams after writing (default: True)
167
        - counter: Associated counter for positioning
168
        - **kwargs: Arguments passed to callable output
169
        """
170

171
    def remove(self, counter):
172
        """
173
        Remove counter from manager.
174

175
        Parameters:
176
        - counter: Counter or StatusBar instance to remove
177
        """
178

179
    def stop(self):
180
        """Stop the manager and finalize notebook display."""
181

182
    def __enter__(self):
183
        """
184
        Context manager entry.
185
        
186
        Returns:
187
        NotebookManager instance
188
        """
189

190
    def __exit__(self, *args):
191
        """
192
        Context manager exit. Calls stop() to clean up.
193
        """
194
```
195

196
## Usage Examples
197

198
### Basic Manager Usage
199

200
```python
201
import enlighten
202
import time
203

204
# Auto-detect environment and get appropriate manager
205
manager = enlighten.get_manager()
206

207
# Create multiple progress bars
208
pbar1 = manager.counter(total=100, desc='Task 1', unit='items')
209
pbar2 = manager.counter(total=50, desc='Task 2', unit='files')
210
status = manager.status_bar()
211

212
# Update progress
213
for i in range(100):
214
    pbar1.update()
215
    if i % 2 == 0:
216
        pbar2.update()
217
    status.update(f'Processing item {i+1}')
218
    time.sleep(0.1)
219

220
# Clean up
221
manager.stop()
222
```
223

224
### Custom Manager Configuration
225

226
```python
227
import enlighten
228
import sys
229

230
# Create manager with custom configuration
231
manager = enlighten.Manager(
232
    stream=sys.stderr,          # Use stderr instead of stdout
233
    enabled=True,               # Force enable even if not TTY
234
    no_resize=True,            # Disable resize handling
235
    width=80                   # Fixed width
236
)
237

238
# Create counter with custom defaults
239
pbar = manager.counter(
240
    total=100,
241
    desc='Custom Task',
242
    unit='ops',
243
    leave=False,               # Don't leave bar after completion
244
    bar_format='{desc}{desc_pad}{percentage:3.0f}%|{bar}|'
245
)
246
```
247

248
### Notebook Environment
249

250
```python
251
# In Jupyter notebook - NotebookManager automatically used
252
import enlighten
253

254
manager = enlighten.get_manager()  # Returns NotebookManager
255
pbar = manager.counter(total=100, desc='Notebook Progress')
256

257
for i in range(100):
258
    pbar.update()
259
    # Progress displays as HTML with live updates
260
```