0
# Progress and Timing
1

2
Progress iteration with ETA, timing utilities, and performance measurement tools for monitoring and profiling code execution.
3

4
## Capabilities
5

6
### Progress Iteration
7

8
Enhanced iteration with progress bars, timing information, and ETA calculation.
9

10
```python { .api }
11
class ProgIter:
12
    """
13
    Progress iterator with timing and ETA.
14
    A faster, more feature-rich alternative to tqdm.
15
    """
16
    def __init__(self, iterable, desc=None, total=None, freq=1, **kwargs):
17
        """
18
        Args:
19
            iterable: Items to iterate over
20
            desc (str): Description shown in progress bar
21
            total (int): Total number of items (auto-detected if possible)
22
            freq (int): Update frequency (every N iterations)
23
            verbose (int): Verbosity level
24
            show_percent (bool): Show percentage complete
25
            show_times (bool): Show timing information
26
            show_rate (bool): Show iteration rate
27
            clearline (bool): Clear line between updates
28
            adjust (bool): Adjust total if iterable length changes
29
            enabled (bool): Enable/disable progress display
30
            **kwargs: Additional formatting options
31
        """
32
    
33
    def __iter__(self): ...
34
    def __next__(self): ...
35
    def __enter__(self): ...
36
    def __exit__(self, exc_type, exc_val, exc_tb): ...
37
    
38
    def set_description(self, desc): ...
39
    def set_postfix(self, **kwargs): ...
40
    def format_infoline(self): ...
41
```
42

43
### Timing Utilities
44

45
Context managers and utilities for measuring execution time with high precision.
46

47
```python { .api }
48
class Timer:
49
    """
50
    Context manager and decorator for timing code execution.
51
    """
52
    def __init__(self, label='Timer', verbose=None, newline=True):
53
        """
54
        Args:
55
            label (str): Label for timer output
56
            verbose (int|bool): Verbosity level
57
            newline (bool): Print newline after timing
58
        """
59
    
60
    def __enter__(self): ...
61
    def __exit__(self, exc_type, exc_val, exc_tb): ...
62
    def __call__(self, func): ...  # Decorator usage
63
    
64
    def tic(self):
65
        """Start timing."""
66
    
67
    def toc(self):
68
        """
69
        Stop timing and return elapsed time.
70
        
71
        Returns:
72
            float: Elapsed time in seconds
73
        """
74
    
75
    @property
76
    def elapsed(self):
77
        """
78
        Current elapsed time.
79
        
80
        Returns:
81
            float: Elapsed time in seconds
82
        """
83
```
84

85
### Timestamp Utilities
86

87
Functions for generating and parsing timestamp strings.
88

89
```python { .api }
90
def timestamp(datetime=None, precision='milliseconds', timezone=True, **kwargs):
91
    """
92
    Generate timestamp string.
93
    
94
    Args:
95
        datetime: Datetime object (current time if None)
96
        precision (str): Time precision ('seconds', 'milliseconds', 'microseconds')
97
        timezone (bool): Include timezone information
98
        **kwargs: Additional formatting options
99
        
100
    Returns:
101
        str: Formatted timestamp string
102
    """
103

104
def timeparse(stamp):
105
    """
106
    Parse timestamp string to datetime object.
107
    
108
    Args:
109
        stamp (str): Timestamp string to parse
110
        
111
    Returns:
112
        datetime.datetime: Parsed datetime object
113
        
114
    Raises:
115
        ValueError: Invalid timestamp format
116
    """
117
```
118

119
## Usage Examples
120

121
### Progress Iteration
122

123
```python
124
import ubelt as ub
125
import time
126

127
# Basic progress iteration
128
items = range(100)
129
for item in ub.ProgIter(items, desc='Processing'):
130
    time.sleep(0.01)  # Simulate work
131

132
# Custom progress with total and description
133
data = [1, 2, 3, 4, 5] * 20
134
for item in ub.ProgIter(data, desc='Computing', total=len(data)):
135
    result = item ** 2  # Some computation
136
    time.sleep(0.005)
137

138
# Progress with custom frequency and formatting
139
large_dataset = range(10000)
140
for i, item in enumerate(ub.ProgIter(large_dataset, desc='Training', freq=100)):
141
    # Update every 100 iterations for performance
142
    if i % 1000 == 0:
143
        # Do expensive operation occasionally
144
        time.sleep(0.1)
145
```
146

147
### Advanced Progress Features
148

149
```python
150
import ubelt as ub
151

152
# Progress with postfix information
153
items = range(50)
154
prog = ub.ProgIter(items, desc='Training Model')
155
for epoch, item in enumerate(prog):
156
    # Simulate training metrics
157
    loss = 1.0 / (epoch + 1)
158
    accuracy = min(0.95, epoch * 0.02)
159
    
160
    # Update progress bar with current metrics
161
    prog.set_postfix(loss=f'{loss:.3f}', acc=f'{accuracy:.2%}')
162
    time.sleep(0.1)
163

164
# Nested progress loops
165
outer_items = range(5)
166
inner_items = range(20)
167

168
for i in ub.ProgIter(outer_items, desc='Outer loop'):
169
    for j in ub.ProgIter(inner_items, desc=f'Inner {i}', leave=False):
170
        time.sleep(0.01)
171

172
# Progress with context manager
173
with ub.ProgIter(total=100, desc='Processing files') as prog:
174
    for i in range(100):
175
        # Manual progress updates
176
        prog.update(1)
177
        time.sleep(0.01)
178
```
179

180
### Timing Code Execution
181

182
```python
183
import ubelt as ub
184
import time
185

186
# Context manager timing
187
with ub.Timer('Database query'):
188
    time.sleep(0.5)  # Simulate database operation
189
# Prints: Database query time: 0.500s
190

191
# Decorator timing
192
@ub.Timer('Function execution')
193
def slow_function():
194
    time.sleep(1.0)
195
    return "result"
196

197
result = slow_function()
198
# Prints: Function execution time: 1.000s
199

200
# Manual timer control
201
timer = ub.Timer('Manual timing', verbose=False)
202
timer.tic()
203
time.sleep(0.3)
204
elapsed = timer.toc()
205
print(f"Elapsed: {elapsed:.3f} seconds")
206

207
# Multiple timing measurements
208
timer = ub.Timer()
209
times = []
210
for i in range(5):
211
    timer.tic()
212
    time.sleep(0.1)
213
    times.append(timer.toc())
214

215
print(f"Average time: {sum(times)/len(times):.3f}s")
216
```
217

218
### Benchmarking and Performance
219

220
```python
221
import ubelt as ub
222
import time
223

224
# Compare function performance
225
def method_a():
226
    return sum(range(1000))
227

228
def method_b():
229
    return sum(x for x in range(1000))
230

231
# Time multiple runs
232
def benchmark_function(func, runs=100):
233
    times = []
234
    for _ in ub.ProgIter(range(runs), desc=f'Benchmarking {func.__name__}'):
235
        with ub.Timer(verbose=False) as timer:
236
            func()
237
        times.append(timer.elapsed)
238
    
239
    return {
240
        'mean': sum(times) / len(times),
241
        'min': min(times),
242
        'max': max(times)
243
    }
244

245
# Run benchmarks
246
results_a = benchmark_function(method_a)
247
results_b = benchmark_function(method_b)
248

249
print(f"Method A: {results_a['mean']:.6f}s avg")
250
print(f"Method B: {results_b['mean']:.6f}s avg")
251
```
252

253
### Timestamp Operations
254

255
```python
256
import ubelt as ub
257
from datetime import datetime
258

259
# Generate timestamps
260
now_stamp = ub.timestamp()
261
print(f"Current time: {now_stamp}")
262

263
# Custom precision
264
precise_stamp = ub.timestamp(precision='microseconds')
265
print(f"Precise time: {precise_stamp}")
266

267
# Custom datetime
268
custom_time = datetime(2023, 1, 1, 12, 0, 0)
269
custom_stamp = ub.timestamp(custom_time)
270
print(f"Custom time: {custom_stamp}")
271

272
# Parse timestamps back to datetime
273
parsed_time = ub.timeparse(now_stamp)
274
print(f"Parsed: {parsed_time}")
275

276
# Use timestamps for logging
277
with ub.Timer('Operation with timestamp', verbose=False) as timer:
278
    start_time = ub.timestamp()
279
    time.sleep(0.1)
280
    end_time = ub.timestamp()
281

282
print(f"Started: {start_time}")
283
print(f"Ended: {end_time}")
284
print(f"Duration: {timer.elapsed:.3f}s")
285
```
286

287
### Performance Monitoring
288

289
```python
290
import ubelt as ub
291
import time
292

293
# Monitor long-running process
294
def process_data(data_items):
295
    results = []
296
    
297
    # Track overall progress
298
    for item in ub.ProgIter(data_items, desc='Processing data'):
299
        # Time individual operations
300
        with ub.Timer(f'Item {item}', verbose=False) as timer:
301
            # Simulate variable processing time
302
            processing_time = 0.01 * (1 + item % 5)
303
            time.sleep(processing_time)
304
            result = item ** 2
305
        
306
        results.append({
307
            'item': item,
308
            'result': result,
309
            'time': timer.elapsed,
310
            'timestamp': ub.timestamp()
311
        })
312
    
313
    return results
314

315
# Process with monitoring
316
data = range(20)
317
results = process_data(data)
318

319
# Analyze timing results
320
total_time = sum(r['time'] for r in results)
321
avg_time = total_time / len(results)
322
print(f"Total processing time: {total_time:.3f}s")
323
print(f"Average per item: {avg_time:.3f}s")
324
```