0
# Boltons
1

2
Boltons is a comprehensive Python utility library containing over 230 BSD-licensed, pure-Python utilities that extend the standard library with functionality that should be built-in. The library provides essential tools for common programming tasks including atomic file operations, optimized data structures, advanced iteration utilities, recursive data structure manipulation, caching, comprehensive traceback handling, and utilities across domains like debugging, dictionaries, file handling, formatting, functional programming, I/O operations, JSON processing, mathematical operations, networking, statistics, string manipulation, and time handling.
3

4
Designed for maximum reusability and reliability, boltons serves as a foundational toolkit for Python developers who need robust, well-tested utility functions that maintain the same quality standards as the standard library while filling gaps in common functionality across CLI tools, web applications, data processing pipelines, and general-purpose Python development.
5

6
## Package Information
7

8
- **Package Name**: boltons
9
- **Language**: Python
10
- **Installation**: `pip install boltons`
11

12
## Core Imports
13

14
Boltons modules are imported individually based on the functionality needed:
15

16
```python
17
from boltons.cacheutils import LRU, cached
18
from boltons.dictutils import OrderedMultiDict
19
from boltons.iterutils import chunked, flatten
20
from boltons.fileutils import atomic_save
21
from boltons.strutils import slugify, bytes2human
22
```
23

24
## Basic Usage
25

26
```python
27
from boltons.iterutils import chunked, flatten
28
from boltons.dictutils import OrderedMultiDict
29
from boltons.cacheutils import LRU
30
from boltons.strutils import slugify
31

32
# Process data in chunks
33
data = list(range(100))
34
for chunk in chunked(data, 10):
35
    print(f"Processing chunk of {len(chunk)} items")
36

37
# Maintain insertion order with multiple values per key
38
omd = OrderedMultiDict()
39
omd.add('key', 'value1')
40
omd.add('key', 'value2')
41
print(omd.getlist('key'))  # ['value1', 'value2']
42

43
# Create URL-friendly slugs
44
title = "Hello, World! This is a test."
45
slug = slugify(title)
46
print(slug)  # "hello-world-this-is-a-test"
47

48
# Use LRU cache for performance
49
cache = LRU(max_size=100)
50
cache['key'] = 'expensive_computation_result'
51
```
52

53
## Architecture
54

55
Boltons is organized into focused utility modules, each containing related functionality:
56

57
- **Data Structures**: Enhanced dictionaries, lists, sets, and queues with specialized behaviors
58
- **Iteration & Processing**: Advanced iteration utilities, chunking, windowing, and data transformation
59
- **Caching**: Multiple cache implementations with different eviction strategies
60
- **String & Text Processing**: Comprehensive text manipulation, formatting, and encoding utilities
61
- **File & I/O Operations**: Atomic file operations, spooled I/O, and path manipulation
62
- **Network & URL Handling**: Socket utilities and comprehensive URL parsing/manipulation
63
- **Time & Statistics**: Time zone handling, relative time formatting, and statistical analysis
64
- **Development Tools**: Debugging utilities, traceback enhancement, and introspection tools
65

66
Each module can be imported and used independently, providing composable utilities that integrate seamlessly with existing Python code.
67

68
## Capabilities
69

70
### Data Structures
71

72
Advanced dictionary, list, set, and queue implementations with specialized behaviors for common programming patterns. Includes ordered multi-dictionaries, bidirectional mappings, priority queues, and indexed sets.
73

74
```python { .api }
75
# dictutils
76
class OrderedMultiDict(dict): ...
77
class OneToOne(dict): ...
78
class FrozenDict(dict): ...
79

80
# listutils  
81
class BarrelList(list): ...
82
class SplayList(list): ...
83

84
# setutils
85
class IndexedSet(MutableSet): ...
86

87
# queueutils
88
class HeapPriorityQueue(BasePriorityQueue): ...
89
class SortedPriorityQueue(BasePriorityQueue): ...
90
```
91

92
[Data Structures](./data-structures.md)
93

94
### Iteration & Processing Utilities
95

96
Comprehensive tools for working with iterables including chunking, windowing, flattening, uniqueness operations, and advanced data structure manipulation. Provides both list and iterator versions of operations for memory efficiency.
97

98
```python { .api }
99
def chunked(src, size, count=None, **kw): ...
100
def windowed(src, size, fill=_UNSET): ...
101
def flatten(iterable): ...
102
def unique(src, key=None): ...
103
def remap(root_obj, **kwargs): ...
104
def get_path(root_obj, path, default=_UNSET): ...
105
```
106

107
[Iteration & Processing](./iteration-processing.md)
108

109
### Caching
110

111
Multiple cache implementations with different eviction strategies, function/method decorators, and cache key generation utilities. Supports LRU, LRI strategies with hit/miss statistics and property caching.
112

113
```python { .api }
114
class LRU(dict): ...
115
class LRI(dict): ...
116
def cached(cache, scoped=True, typed=False, key=None): ...
117
def cachedmethod(cache, scoped=True, typed=False, key=None): ...
118
class cachedproperty: ...
119
```
120

121
[Caching](./caching.md)
122

123
### String & Text Processing  
124

125
Comprehensive text manipulation including case conversion, slugification, text formatting, HTML processing, ANSI handling, compression, and advanced string operations with internationalization support.
126

127
```python { .api }
128
def slugify(text, delim='_', lower=True, ascii=False): ...
129
def camel2under(camel_string): ...
130
def under2camel(under_string): ...
131
def bytes2human(nbytes, ndigits=0): ...
132
def html2text(html_text): ...
133
def strip_ansi(text): ...
134
def multi_replace(input_string, sub_map, **kwargs): ...
135
```
136

137
[String & Text Processing](./string-text-processing.md)
138

139
### File & I/O Operations
140

141
Atomic file operations, advanced I/O utilities, path manipulation, and file system operations. Includes spooled I/O that automatically switches to disk for large data and atomic file saving with backup support.
142

143
```python { .api }
144
def atomic_save(dest_path, **kwargs): ...
145
def mkdir_p(path): ...
146
class AtomicSaver: ...
147
class SpooledBytesIO(SpooledIOBase): ...
148
class SpooledStringIO(SpooledIOBase): ...
149
def augpath(path, suffix='', prefix='', ext=None, base=None, dpath=None, multidot=False): ...
150
```
151

152
[File & I/O Operations](./file-io-operations.md)
153

154
### Network & URL Handling
155

156
Socket programming utilities with buffering and protocol support, plus comprehensive URL parsing, manipulation, and utilities. Includes netstring protocol implementation and complete URL component handling.
157

158
```python { .api }
159
class BufferedSocket: ...
160
class NetstringSocket: ...
161
class URL: ...
162
def parse_url(url_text): ...
163
def find_all_links(text, with_text=False, **kwargs): ...
164
```
165

166
[Network & URL Handling](./network-url-handling.md)
167

168
### Time & Date Utilities
169

170
Time zone handling, datetime parsing, relative time formatting, and date range generation. Supports ISO 8601 parsing, human-readable time deltas, and timezone-aware operations.
171

172
```python { .api }
173
def isoparse(iso_str): ...
174
def parse_timedelta(text): ...  
175
def relative_time(d, other=None, ndigits=0): ...
176
def daterange(start, stop, step=1, inclusive=False): ...
177
class LocalTZInfo(tzinfo): ...
178
class USTimeZone(tzinfo): ...
179
```
180

181
[Time & Date Utilities](./time-date-utilities.md)
182

183
### Mathematical & Statistical Operations
184

185
Mathematical utilities, statistical analysis, and data summarization tools. Includes bit manipulation, number clamping, descriptive statistics, and histogram formatting.
186

187
```python { .api }
188
def clamp(x, lower=float('-inf'), upper=float('inf')): ...
189
class Bits: ...
190
class Stats: ...
191
def describe(data, quantiles=None, format=None): ...
192
```
193

194
[Mathematical & Statistical Operations](./math-stats-operations.md)
195

196
### Development & Debugging Tools
197

198
Debugging utilities, function introspection, traceback enhancement, garbage collection tools, and development aids. Includes pdb integration, enhanced exception handling, and function manipulation utilities.
199

200
```python { .api }
201
def pdb_on_signal(signalnum=None): ...
202
def pdb_on_exception(limit=100): ...
203
class TracebackInfo: ...
204
class ExceptionInfo: ...
205
class FunctionBuilder: ...
206
def get_module_callables(mod, ignore=None): ...
207
```
208

209
[Development & Debugging Tools](./development-debugging-tools.md)
210

211
### Format & Table Utilities
212

213
String formatting utilities, tabular data handling, and HTML table generation. Includes format string parsing, table creation from various data sources, and flexible output formatting.
214

215
```python { .api }
216
def split_format_str(fstr): ...
217
def get_format_args(fstr): ...
218
class Table: ... 
219
def to_text(obj, maxlen=None): ...
220
```
221

222
[Format & Table Utilities](./format-table-utilities.md)
223

224
### Additional Utilities
225

226
Specialized utilities for JSON processing, mailbox handling, named tuples/lists, type checking, and deprecation management. Includes JSON Lines processing, mbox file access, and enhanced type introspection.
227

228
```python { .api }
229
class JSONLIterator: ...
230
def namedtuple(typename, field_names, verbose=False, rename=False): ...
231
def namedlist(typename, field_names, verbose=False, rename=False): ...
232
def make_sentinel(name='_MISSING', var_name=None): ...
233
class DeprecatableModule(ModuleType): ...
234
```
235

236
[Additional Utilities](./additional-utilities.md)