0
# Proglog
1

2
A comprehensive progress logging system for Python that enables developers to add flexible progress bars and logging capabilities to their applications. Proglog offers unified APIs for displaying progress across different environments including console applications, Jupyter notebooks, and web interfaces, with support for nested progress bars, selective display control, custom callback functions, and integration with popular progress bar libraries like tqdm.
3

4
## Package Information
5

6
- **Package Name**: proglog
7
- **Language**: Python
8
- **Installation**: `pip install proglog`
9

10
## Core Imports
11

12
```python
13
import proglog
14
```
15

16
Common imports for basic usage:
17

18
```python
19
from proglog import ProgressLogger, TqdmProgressBarLogger, default_bar_logger
20
```
21

22
For notebook integration:
23

24
```python
25
from proglog import notebook
26
```
27

28
## Basic Usage
29

30
```python
31
from proglog import default_bar_logger
32
import time
33

34
def my_routine(iterations=10, logger='bar'):
35
    """Run several loops to showcase Proglog."""
36
    logger = default_bar_logger(logger)  # Create appropriate logger
37
    
38
    # Nested progress bars with automatic tracking
39
    for i in logger.iter_bar(iteration=range(iterations)):
40
        for j in logger.iter_bar(animal=["dog", "cat", "rat", "duck"]):
41
            time.sleep(0.02)  # simulate some work
42
            
43
    # Manual progress updates
44
    logger(message="Processing complete!")
45

46
# Run with default tqdm progress bars
47
my_routine()
48

49
# Run silently 
50
my_routine(logger=None)
51

52
# Run with custom configuration
53
from proglog import TqdmProgressBarLogger
54
custom_logger = TqdmProgressBarLogger(ignored_bars=["animal"])
55
my_routine(logger=custom_logger)
56
```
57

58
## Architecture
59

60
Proglog uses a hierarchical logger architecture that separates concerns:
61

62
- **ProgressLogger**: Base logging class with state management and message logging
63
- **ProgressBarLogger**: Extends logging with multiple named progress bar management
64
- **TqdmProgressBarLogger**: Concrete implementation using tqdm for display
65
- **Worker Loggers**: Specialized loggers for Redis Queue (RQ) worker integration
66
- **Factory Functions**: Convenience functions for logger instantiation and configuration
67

68
This design enables maximum reusability across different deployment contexts, allowing users to control which progress bars are displayed without modifying the underlying code, and enabling complex applications to manage multiple concurrent progress tracking operations with hierarchical organization and customizable output formats.
69

70
## Capabilities
71

72
### Basic Progress Logging
73

74
Core logging functionality with state management, message logging, and iteration tracking. Provides the foundation for all other proglog capabilities.
75

76
```python { .api }
77
class ProgressLogger:
78
    def __init__(self, init_state=None): ...
79
    def log(self, message): ...
80
    def dump_logs(self, filepath=None): ...
81
    def callback(self, **kw): ...
82
    def store(self, **kw): ...
83
    def iter(self, **kw): ...
84
    def __call__(self, **kw): ...
85
```
86

87
[Basic Logging](./basic-logging.md)
88

89
### Progress Bar Management
90

91
Advanced progress bar functionality with support for multiple named bars, selective display control, and automatic tracking during iteration. Includes both generic bar management and tqdm-powered display.
92

93
```python { .api }
94
class ProgressBarLogger(ProgressLogger):
95
    def __init__(self, init_state=None, bars=None, ignored_bars=None, 
96
                 logged_bars="all", min_time_interval=0, ignore_bars_under=0): ...
97
    def iter_bar(self, bar_prefix="", **kw): ...
98
    def bars_callback(self, bar, attr, value, old_value=None): ...
99

100
class TqdmProgressBarLogger(ProgressBarLogger):
101
    def __init__(self, init_state=None, bars=None, leave_bars=False,
102
                 ignored_bars=None, logged_bars="all", notebook="default",
103
                 print_messages=True, min_time_interval=0, ignore_bars_under=0): ...
104
```
105

106
[Progress Bars](./progress-bars.md)
107

108
### Worker Integration
109

110
Redis Queue (RQ) worker integration for progress tracking in distributed job processing environments. Enables progress state persistence and retrieval across worker processes.
111

112
```python { .api }
113
class RqWorkerProgressLogger:
114
    def __init__(self, job): ...
115
    def callback(self, **kw): ...
116

117
class RqWorkerBarLogger(RqWorkerProgressLogger, ProgressBarLogger):
118
    def __init__(self, job, init_state=None, bars=None, ignored_bars=(), 
119
                 logged_bars="all", min_time_interval=0): ...
120
```
121

122
[Worker Integration](./workers.md)
123

124
## Utility Functions
125

126
### Logger Factory
127

128
```python { .api }
129
def default_bar_logger(logger, bars=None, ignored_bars=None, logged_bars="all", 
130
                      min_time_interval=0, ignore_bars_under=0):
131
    """
132
    Factory function to create appropriate logger based on type.
133
    
134
    Parameters:
135
    - logger: "bar" for TqdmProgressBarLogger, None for MuteProgressBarLogger, 
136
             or existing logger instance
137
    - bars: Bar configuration (None, list, tuple, or dict)
138
    - ignored_bars: Bars to ignore (None, list, or "all_others")
139
    - logged_bars: Bars to log ("all" or list of bar names)
140
    - min_time_interval: Minimum time between updates (seconds)
141
    - ignore_bars_under: Ignore bars with fewer than N items
142
    
143
    Returns:
144
    Configured logger instance
145
    """
146
```
147

148
### Global Configuration
149

150
```python { .api }
151
def notebook(turn="on"):
152
    """
153
    Configure global notebook mode setting.
154
    
155
    Parameters:
156
    - turn: "on" to enable notebook mode, any other value to disable
157
    """
158
```
159

160
### Silent Logger
161

162
```python { .api }
163
class MuteProgressBarLogger(ProgressBarLogger):
164
    """Silent progress bar logger that ignores all bars."""
165
    def bar_is_ignored(self, bar): ...  # Always returns True
166
```
167

168
## Version Information
169

170
```python { .api }
171
__version__: str  # Package version string (currently "0.1.12")
172
```