0
# UBelt
1

2
A Python utility belt containing simple tools, a stdlib-like feel, and extra batteries. UBelt provides a comprehensive collection of 150+ focused utilities that make everyday Python tasks shorter, cleaner, and more consistent across different platforms.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import ubelt as ub
14
```
15

16
All utilities are available at the top level:
17

18
```python
19
import ubelt as ub
20
# Use any function directly
21
ub.cmd('ls')
22
ub.Timer()
23
ub.download('https://example.com/file.zip')
24
```
25

26
## Basic Usage
27

28
```python
29
import ubelt as ub
30

31
# Command execution with enhanced features
32
result = ub.cmd('ls -la', verbose=2)
33
print(result['out'])
34

35
# Progress iteration with timing and ETA
36
items = range(1000)
37
for item in ub.ProgIter(items, desc='Processing'):
38
    # Do work
39
    pass
40

41
# Dictionary operations and grouping
42
items = ['apple', 'banana', 'cherry', 'apricot']
43
grouped = ub.group_items(items, key=lambda x: x[0])
44
print(grouped)  # {'a': ['apple', 'apricot'], 'b': ['banana'], 'c': ['cherry']}
45

46
# Caching computations
47
cache = ub.Cacher('my_cache', depends=['input_data'])
48
result = cache.tryload()
49
if result is None:
50
    result = expensive_computation()
51
    cache.save(result)
52

53
# Path operations
54
with ub.TempDir() as tmp:
55
    fpath = tmp / 'example.txt'
56
    ub.touch(fpath)
57
    print(ub.augpath(fpath, suffix='_backup'))
58

59
# Timing operations
60
with ub.Timer('my_operation'):
61
    time.sleep(1)  # Replace with actual work
62
```
63

64
## Architecture
65

66
UBelt is organized into 27 focused submodules, each containing related functionality:
67

68
- **Data Structures**: Enhanced dictionaries (UDict, AutoDict), ordered sets, and data manipulation utilities
69
- **I/O Operations**: File operations, downloads, path utilities, and stream handling  
70
- **System Integration**: Command execution, platform detection, and cross-platform compatibility
71
- **Performance Tools**: Progress tracking, timing, caching, and memoization
72
- **Development Utilities**: Import helpers, debugging tools, and code formatting
73

74
All utilities follow consistent design patterns with optional parameters, sensible defaults, and cross-platform compatibility.
75

76
## Capabilities
77

78
### Dictionary and Data Operations
79

80
Comprehensive dictionary utilities including enhanced dict classes with set operations, grouping functions, and data structure manipulation tools.
81

82
```python { .api }
83
class UDict(dict): ...
84
class AutoDict(dict): ...
85
def group_items(items, key): ...
86
def dict_hist(items, weights=None): ...
87
def dict_union(*args, **kwargs): ...
88
def find_duplicates(items, k=2): ...
89
```
90

91
[Dictionary Operations](./dict-operations.md)
92

93
### Command Execution and System Integration
94

95
Execute shell commands with enhanced features, platform detection, and system integration utilities.
96

97
```python { .api }
98
def cmd(command, shell=False, detach=False, verbose=0, **kwargs): ...
99
WIN32: bool
100
LINUX: bool
101
DARWIN: bool
102
def find_exe(name, **kwargs): ...
103
```
104

105
[System Integration](./system-integration.md)
106

107
### File and Path Operations
108

109
Cross-platform path utilities, file operations, symbolic links, and temporary directory management.
110

111
```python { .api }
112
class Path(pathlib.Path): ...
113
class TempDir: ...
114
def ensuredir(dpath, **kwargs): ...
115
def symlink(real_path, link_path, **kwargs): ...
116
def touch(fpath, **kwargs): ...
117
def delete(fpath, **kwargs): ...
118
```
119

120
[Path Operations](./path-operations.md)
121

122
### Download and Caching
123

124
Download files with progress tracking, verification, and comprehensive caching systems for computations and data.
125

126
```python { .api }
127
def download(url, fpath=None, **kwargs): ...
128
def grabdata(url, fpath=None, **kwargs): ...
129
class Cacher: ...
130
class CacheStamp: ...
131
```
132

133
[Download and Caching](./download-caching.md)
134

135
### Progress and Timing
136

137
Progress iteration with ETA, timing utilities, and performance measurement tools.
138

139
```python { .api }
140
class ProgIter: ...
141
class Timer: ...
142
def timestamp(datetime=None, **kwargs): ...
143
def timeparse(stamp): ...
144
```
145

146
[Progress and Timing](./progress-timing.md)
147

148
### List and Sequence Operations
149

150
Comprehensive sequence manipulation including chunking, filtering, sorting, and uniqueness operations.
151

152
```python { .api }
153
def chunks(sequence, chunksize): ...
154
def group_items(items, key): ...
155
def argmax(sequence, key=None): ...
156
def argmin(sequence, key=None): ...
157
def argsort(sequence, key=None, reverse=False): ...
158
def unique(items, key=None): ...
159
def flatten(nested_list): ...
160
```
161

162
[List Operations](./list-operations.md)
163

164
### String and Text Processing
165

166
String manipulation utilities including indentation, formatting, and text processing functions.
167

168
```python { .api }
169
def indent(text, prefix='    '): ...
170
def codeblock(text): ...
171
def paragraph(text): ...
172
def hzcat(args, **kwargs): ...
173
```
174

175
[Text Processing](./text-processing.md)
176

177
### Hashing and Import Utilities
178

179
Hash arbitrary data and files, plus dynamic module importing and path resolution utilities.
180

181
```python { .api }
182
def hash_data(data, hasher='sha512', base='hex', **kwargs): ...
183
def hash_file(fpath, hasher='sha512', base='hex', **kwargs): ...
184
def import_module_from_name(name, **kwargs): ...
185
def import_module_from_path(fpath, **kwargs): ...
186
```
187

188
[Hashing and Imports](./hashing-imports.md)
189

190
### Function and Concurrency Utilities
191

192
Function manipulation, memoization, and enhanced concurrency tools.
193

194
```python { .api }
195
def memoize(func=None, **kwargs): ...
196
def identity(arg): ...
197
class Executor: ...
198
class JobPool: ...
199
```
200

201
[Function Utilities](./function-utilities.md)
202

203
## Types
204

205
```python { .api }
206
# Sentinel value for unspecified parameters  
207
NoParam: object  # Special sentinel used as default for hasher, base, and other parameters
208

209
# Enhanced dictionary types
210
class UDict(dict):
211
    """Dictionary with set operations and convenience methods"""
212
    
213
class AutoDict(dict):
214
    """Auto-vivifying dictionary"""
215

216
class SetDict(dict):
217
    """Dictionary with key-wise set operations"""
218

219
# Path utilities
220
class Path(pathlib.Path):
221
    """Enhanced pathlib.Path with additional methods"""
222

223
class TempDir:
224
    """Context manager for temporary directories"""
225
    
226
class ChDir:
227
    """Context manager for changing directories"""
228

229
# Progress and timing
230
class ProgIter:
231
    """Progress iterator with timing and ETA"""
232
    
233
class Timer:
234
    """Context manager and decorator for timing code"""
235

236
# Caching
237
class Cacher:
238
    """On-disk caching with dependency tracking"""
239
    
240
class CacheStamp:
241
    """Lightweight cache stamping for file-producing computations"""
242

243
# Command execution
244
class CmdOutput(dict):
245
    """Container for command output"""
246

247
# Concurrency
248
class Executor:
249
    """Enhanced executor interface"""
250
    
251
class JobPool:
252
    """Job pool for managing concurrent tasks"""
253

254
# Data structures
255
class OrderedSet:
256
    """Set that preserves insertion order"""
257

258
# Stream handling
259
class TeeStringIO:
260
    """StringIO that can write to multiple streams"""
261
    
262
class CaptureStdout:
263
    """Context manager to capture stdout"""
264
    
265
class CaptureStream:
266
    """Context manager to capture arbitrary stream"""
267

268
# Mixins
269
class NiceRepr:
270
    """Mixin for nice string representations"""
271

272
# Indexable utilities
273
class IndexableWalker:
274
    """Walk through indexable nested data structures"""
275
```