0
# Abseil Python Common Libraries (absl-py)
1

2
Abseil Python Common Libraries is a collection of Python library code for building Python applications. The code is collected from Google's own Python code base and has been extensively tested and used in production. It provides four main components: simple application startup utilities, a distributed command-line flags system, enhanced logging functionality, and comprehensive testing utilities.
3

4
## Package Information
5

6
- **Package Name**: absl-py
7
- **Language**: Python
8
- **Installation**: `pip install absl-py`
9
- **Version**: 2.3.1
10
- **Python Requirements**: >=3.8
11
- **License**: Apache-2.0
12

13
## Core Imports
14

15
```python
16
from absl import app
17
from absl import flags
18
from absl import logging
19
from absl.testing import absltest
20
```
21

22
Individual module imports:
23

24
```python
25
# Application startup
26
from absl import app
27

28
# Command-line flags
29
from absl import flags
30
FLAGS = flags.FLAGS
31

32
# Enhanced logging
33
from absl import logging
34

35
# Testing utilities
36
from absl.testing import absltest
37
from absl.testing import parameterized
38
from absl.testing import flagsaver
39
```
40

41
## Basic Usage
42

43
```python
44
from absl import app
45
from absl import flags
46
from absl import logging
47

48
FLAGS = flags.FLAGS
49

50
# Define command-line flags
51
flags.DEFINE_string('name', 'World', 'Name to greet.')
52
flags.DEFINE_integer('count', 1, 'Number of greetings.')
53
flags.DEFINE_boolean('verbose', False, 'Enable verbose logging.')
54

55
def main(argv):
56
    """Main application entry point."""
57
    del argv  # Unused.
58
    
59
    # Configure logging based on flags
60
    if FLAGS.verbose:
61
        logging.set_verbosity(logging.DEBUG)
62
    
63
    # Use logging instead of print
64
    logging.info('Starting application...')
65
    
66
    # Access flag values
67
    for i in range(FLAGS.count):
68
        logging.info('Hello, %s! (greeting %d/%d)', FLAGS.name, i+1, FLAGS.count)
69
    
70
    logging.info('Application completed.')
71

72
if __name__ == '__main__':
73
    app.run(main)
74
```
75

76
## Architecture
77

78
The absl-py library is organized around four core modules that work together:
79

80
- **app**: Provides application startup utilities with automatic flag parsing and exception handling
81
- **flags**: Implements a distributed command-line flag system where any module can define flags
82
- **logging**: Offers enhanced logging functionality built on top of Python's standard logging
83
- **testing**: Supplies comprehensive testing utilities including parameterized tests and flag management
84

85
This design enables modular Python applications where configuration, logging, and testing are consistently handled across all components.
86

87
## Capabilities
88

89
### Application Startup
90

91
Application lifecycle management with automatic flag parsing, exception handling, and proper program termination. Provides the main entry point for absl-based applications.
92

93
```python { .api }
94
def run(main, argv=None, flags_parser=parse_flags_with_usage):
95
    """
96
    Run the main function with automatic flag parsing and exception handling.
97
    
98
    Args:
99
        main: Main function that takes argv as argument
100
        argv: Command line arguments (defaults to sys.argv) 
101
        flags_parser: Function to parse flags (defaults to parse_flags_with_usage)
102
    """
103

104
class UsageError(Exception):
105
    """Exception for usage/argument errors."""
106

107
def call_after_init(callback):
108
    """Register callback to run after initialization."""
109
```
110

111
[Application Startup](./app.md)
112

113
### Command-Line Flags
114

115
Distributed flag definition system allowing any module to define command-line flags. Supports various flag types, validation, and help generation with global flag registry.
116

117
```python { .api }
118
def DEFINE_string(name, default, help, flag_values=FLAGS, **args):
119
    """Define a string flag."""
120

121
def DEFINE_boolean(name, default, help, flag_values=flags.FLAGS, **args):
122
    """Define a boolean flag."""
123

124
def DEFINE_integer(name, default, help, flag_values=flags.FLAGS, **args):
125
    """Define an integer flag."""
126

127
def DEFINE_float(name, default, help, flag_values=flags.FLAGS, **args):
128
    """Define a float flag."""
129

130
def DEFINE_enum(name, default, enum_values, help, flag_values=flags.FLAGS, **args):
131
    """Define an enum flag."""
132

133
FLAGS: FlagValues  # Global flag registry
134
```
135

136
[Command-Line Flags](./flags.md)
137

138
### Enhanced Logging
139

140
Comprehensive logging functionality built on Python's standard logging with additional features like verbosity control, conditional logging, and structured output formatting.
141

142
```python { .api }
143
def info(msg, *args, **kwargs):
144
    """Log an info message."""
145

146
def warning(msg, *args, **kwargs):
147
    """Log a warning message."""
148

149
def error(msg, *args, **kwargs):
150
    """Log an error message."""
151

152
def fatal(msg, *args, **kwargs):
153
    """Log a fatal message and exit."""
154

155
def debug(msg, *args, **kwargs):
156
    """Log a debug message."""
157

158
def set_verbosity(v):
159
    """Set logging verbosity level."""
160

161
def get_verbosity():
162
    """Get current verbosity level."""
163

164
def vlog(level, msg, *args, **kwargs):
165
    """Log a verbose message at the specified level."""
166

167
def log_every_n(level, msg, n, *args, **kwargs):
168
    """Log a message every N times this function is called."""
169

170
def log_every_n_seconds(level, msg, n_seconds, *args, **kwargs):
171
    """Log a message at most once every N seconds."""
172
```
173

174
[Enhanced Logging](./logging.md)
175

176
### Testing Utilities
177

178
Comprehensive testing framework extending unittest with additional assertions, parameterized testing, temporary file management, and flag state management for tests.
179

180
```python { .api }
181
class TestCase(unittest.TestCase):
182
    """Enhanced test case with additional assertions and utilities."""
183

184
def main(*args, **kwargs):
185
    """Main test runner entry point."""
186

187
class TempFileCleanup(enum.Enum):
188
    """Enum for temporary file cleanup behavior."""
189
    ALWAYS = 'always'
190
    SUCCESS = 'success'
191
    FAILURE = 'failure'
192
```
193

194
[Testing Utilities](./testing.md)
195

196
## Error Handling
197

198
absl-py defines several exception types for different error conditions:
199

200
```python { .api }
201
# Application errors
202
class app.Error(Exception):
203
    """Base application exception."""
204

205
class app.UsageError(app.Error):
206
    """Usage/argument error exception."""
207

208
# Flag errors  
209
class flags.Error(Exception):
210
    """Base flag exception."""
211

212
class flags.ValidationError(flags.Error):
213
    """Flag validation error."""
214

215
class flags.UnrecognizedFlagError(flags.Error):
216
    """Unrecognized flag error."""
217
```
218

219
Common error handling patterns involve catching specific exceptions and providing user-friendly error messages while maintaining proper exit codes.