0
# Additional Utilities
1

2
Specialized utilities for JSON processing, mailbox handling, named tuples/lists, type checking, environment profiling, exception handling, and deprecation management. These utilities provide essential functionality for specific use cases and system integration.
3

4
## Capabilities
5

6
### JSON Processing
7

8
JSON Lines format processing and utilities.
9

10
```python { .api }
11
class JSONLIterator:
12
    """Iterator for reading JSON Lines format files."""
13
    def __init__(self, file_obj): ...
14
    def __iter__(self): ...
15
    def __next__(self): ...
16

17
def reverse_iter_lines(file_obj, blocksize=DEFAULT_BLOCKSIZE, **kwargs):
18
    """
19
    Iterate file lines in reverse order.
20
    
21
    Parameters:
22
    - file_obj: File object to read
23
    - blocksize (int): Block size for reading
24
    
25
    Yields:
26
    str: Each line in reverse order
27
    """
28
```
29

30
### Named Collections
31

32
Enhanced namedtuple and mutable namedlist implementations.
33

34
```python { .api }
35
def namedtuple(typename, field_names, verbose=False, rename=False):
36
    """
37
    Enhanced namedtuple factory.
38
    
39
    Parameters:
40
    - typename (str): Name of the new tuple subclass
41
    - field_names (str or list): Field names for the tuple
42
    - verbose (bool): Print class definition if True
43
    - rename (bool): Replace invalid field names with valid ones
44
    
45
    Returns:
46
    type: New namedtuple class
47
    """
48

49
def namedlist(typename, field_names, verbose=False, rename=False):
50
    """
51
    Mutable namedtuple equivalent.
52
    
53
    Parameters:
54
    - typename (str): Name of the new list subclass
55
    - field_names (str or list): Field names for the list
56
    - verbose (bool): Print class definition if True
57
    - rename (bool): Replace invalid field names with valid ones
58
    
59
    Returns:
60
    type: New namedlist class with mutable fields
61
    """
62
```
63

64
### Type Checking and Introspection
65

66
Enhanced type checking and sentinel object creation.
67

68
```python { .api }
69
def make_sentinel(name='_MISSING', var_name=None):
70
    """
71
    Create unique sentinel objects.
72
    
73
    Parameters:
74
    - name (str): Name for the sentinel
75
    - var_name (str, optional): Variable name for representation
76
    
77
    Returns:
78
    Sentinel: Unique sentinel object
79
    """
80

81
def issubclass(subclass, baseclass):
82
    """
83
    Enhanced issubclass with better error handling.
84
    
85
    Parameters:
86
    - subclass: Potential subclass to check
87
    - baseclass: Base class or tuple of base classes
88
    
89
    Returns:
90
    bool: True if subclass is a subclass of baseclass
91
    """
92

93
def get_all_subclasses(cls):
94
    """
95
    Get all subclasses recursively.
96
    
97
    Parameters:
98
    - cls (type): Base class
99
    
100
    Returns:
101
    set: Set of all subclasses
102
    """
103

104
class Sentinel:
105
    """Unique sentinel object for special values."""
106
    def __init__(self, name, var_name=None): ...
107
    def __repr__(self): ...
108
    def __bool__(self): ...
109
    __nonzero__ = __bool__  # Python 2 compatibility
110

111
class classproperty:
112
    """Property descriptor for class-level properties."""
113
    def __init__(self, func): ...
114
    def __get__(self, obj, objtype=None): ...
115
```
116

117
### Environment Profiling
118

119
System environment analysis and profiling utilities.
120

121
```python { .api }
122
def get_profile(**kwargs):
123
    """
124
    Main entrypoint returning JSON-serializable system info dict.
125
    
126
    Parameters:
127
    - **kwargs: Additional profile options
128
    
129
    Returns:
130
    dict: Comprehensive system profile information
131
    """
132

133
def get_python_info():
134
    """
135
    Collect Python interpreter information.
136
    
137
    Returns:
138
    dict: Python interpreter details
139
    """
140

141
def get_profile_json(indent=False):
142
    """
143
    Get profile as JSON string.
144
    
145
    Parameters:
146
    - indent (bool): Pretty-print JSON with indentation
147
    
148
    Returns:
149
    str: JSON-formatted profile data
150
    """
151

152
def dumps(val, indent):
153
    """
154
    JSON serialization with optional indentation.
155
    
156
    Parameters:
157
    - val: Value to serialize
158
    - indent (bool or int): Indentation for pretty-printing
159
    
160
    Returns:
161
    str: JSON-serialized string
162
    """
163
```
164

165
### Mailbox Utilities
166

167
Utilities for working with mbox mailbox files.
168

169
```python { .api }
170
class mbox_readonlydir:
171
    """Read-only directory-like access to mbox files."""
172
    def __init__(self, path, maxmem=DEFAULT_MAXMEM): ...
173
    def __getitem__(self, key): ...
174
    def __iter__(self): ...
175
    def keys(self): ...
176
    def values(self): ...
177
    def items(self): ...
178
    def get(self, key, default=None): ...
179
```
180

181
### Deprecation Management
182

183
Tools for managing deprecated module members and functionality.
184

185
```python { .api }
186
class DeprecatableModule(ModuleType):
187
    """Module wrapper that warns on deprecated member access."""
188
    def __init__(self, name, deprecated_members=None): ...
189
    def __getattr__(self, name): ...
190

191
def deprecate_module_member(mod_name, name, message):
192
    """
193
    Mark a module member as deprecated.
194
    
195
    Parameters:
196
    - mod_name (str): Module name
197
    - name (str): Member name to deprecate
198
    - message (str): Deprecation warning message
199
    
200
    Returns:
201
    None
202
    """
203
```
204

205
### Exception Handling Examples
206

207
Example exception handling utilities.
208

209
```python { .api }
210
class ExceptionCauseMixin(Exception):
211
    """Mixin for exceptions that can have causes."""
212
    def __init__(self, *args, **kwargs): ...
213
    @property
214
    def cause(self): ...
215

216
class MathError(ExceptionCauseMixin, ValueError):
217
    """Example math-related exception."""
218
    pass
219

220
def whoops_math():
221
    """Example function demonstrating exception handling."""
222
    try:
223
        return math_lol()
224
    except Exception as e:
225
        raise MathError("Math operation failed") from e
226

227
def math_lol(n=0):
228
    """Example recursive math function."""
229
    if n > 10:
230
        raise ValueError("Number too large")
231
    return n * math_lol(n + 1) if n < 5 else 1
232
```
233

234
### Easter Eggs
235

236
Novelty functions and easter eggs.
237

238
```python { .api }
239
def gobs_program():
240
    """
241
    Pure-Python implementation of Gob's Algorithm.
242
    
243
    Returns:
244
    str: Result of Gob's Algorithm (novelty function)
245
    """
246
```
247

248
## Usage Examples
249

250
```python
251
from boltons.jsonutils import JSONLIterator
252
from boltons.namedutils import namedtuple, namedlist
253
from boltons.typeutils import make_sentinel, issubclass
254
from boltons.ecoutils import get_profile
255

256
# JSON Lines processing
257
with open('data.jsonl', 'r') as f:
258
    jsonl_iter = JSONLIterator(f)
259
    for record in jsonl_iter:
260
        print(f"Processing: {record}")
261

262
# Enhanced namedtuple
263
Person = namedtuple('Person', 'name age city', verbose=True)
264
alice = Person('Alice', 30, 'New York')
265
print(f"Name: {alice.name}, Age: {alice.age}")
266

267
# Mutable namedlist
268
MutablePerson = namedlist('MutablePerson', 'name age city')
269
bob = MutablePerson('Bob', 25, 'Los Angeles')
270
bob.age = 26  # Can modify fields
271
print(f"Updated age: {bob.age}")
272

273
# Sentinel objects for special values
274
MISSING = make_sentinel('MISSING')
275
DEFAULT = make_sentinel('DEFAULT', 'DEFAULT_VALUE')
276

277
def process_data(data, strategy=MISSING):
278
    if strategy is MISSING:
279
        print("No strategy specified")
280
    elif strategy is DEFAULT:
281
        print("Using default strategy")
282
    else:
283
        print(f"Using strategy: {strategy}")
284

285
process_data([1, 2, 3])  # No strategy specified
286
process_data([1, 2, 3], DEFAULT)  # Using default strategy
287

288
# Enhanced type checking
289
class Animal: pass
290
class Dog(Animal): pass
291
class Puppy(Dog): pass
292

293
print(issubclass(Dog, Animal))    # True
294
print(issubclass("not a class", Animal))  # False (no TypeError)
295

296
from boltons.typeutils import get_all_subclasses
297
all_subs = get_all_subclasses(Animal)
298
print(f"Animal subclasses: {all_subs}")  # {Dog, Puppy}
299

300
# System profiling
301
profile = get_profile()
302
print(f"Python version: {profile['python']['version']}")
303
print(f"Platform: {profile['system']['platform']}")
304
print(f"Architecture: {profile['system']['architecture']}")
305
```
306

307
### Advanced Usage Examples
308

309
```python
310
from boltons.ecoutils import get_python_info, get_profile_json
311
from boltons.deprutils import DeprecatableModule, deprecate_module_member
312
from boltons.mboxutils import mbox_readonlydir
313
import tempfile
314
import warnings
315

316
# Detailed Python environment analysis
317
python_info = get_python_info()
318
print("Python Environment Details:")
319
for key, value in python_info.items():
320
    print(f"  {key}: {value}")
321

322
# Export environment profile as JSON
323
profile_json = get_profile_json(indent=True)
324
with open('system_profile.json', 'w') as f:
325
    f.write(profile_json)
326

327
# Deprecation management
328
# Create a module with deprecated members
329
class MyModule(DeprecatableModule):
330
    def __init__(self):
331
        super().__init__('mymodule')
332
        self.new_function = lambda: "This is the new function"
333
        self._deprecated_members = {
334
            'old_function': 'old_function is deprecated, use new_function instead'
335
        }
336

337
my_module = MyModule()
338

339
# Access deprecated member (will issue warning)
340
with warnings.catch_warnings(record=True) as w:
341
    warnings.simplefilter("always")
342
    try:
343
        result = my_module.old_function  # Triggers deprecation warning
344
    except AttributeError:
345
        print("Deprecated member access blocked")
346
    
347
    if w:
348
        print(f"Warning: {w[0].message}")
349

350
# Mailbox processing (if mbox file exists)
351
# mbox_dir = mbox_readonlydir('/path/to/mailbox.mbox')
352
# for message_id in mbox_dir.keys():
353
#     message = mbox_dir[message_id]
354
#     print(f"Message {message_id}: {message['Subject']}")
355

356
# Class-level properties
357
class ConfigManager:
358
    _instance = None
359
    _config = {'debug': False, 'version': '1.0'}
360
    
361
    @classproperty
362
    def config(cls):
363
        return cls._config
364
    
365
    @classproperty  
366
    def debug_mode(cls):
367
        return cls._config.get('debug', False)
368

369
print(f"Debug mode: {ConfigManager.debug_mode}")
370
print(f"Config: {ConfigManager.config}")
371

372
# Exception handling with causes
373
from boltons.excutils import ExceptionCauseMixin
374

375
class DataProcessingError(ExceptionCauseMixin):
376
    pass
377

378
def process_file(filename):
379
    try:
380
        with open(filename, 'r') as f:
381
            data = f.read()
382
            return json.loads(data)  # Might raise JSONDecodeError
383
    except FileNotFoundError as e:
384
        raise DataProcessingError(f"Could not find file: {filename}") from e
385
    except json.JSONDecodeError as e:
386
        raise DataProcessingError(f"Invalid JSON in file: {filename}") from e
387

388
# The resulting exception will have both the original cause and new context
389
```
390

391
## Types
392

393
```python { .api }
394
# Constants
395
ECO_VERSION = '1.1.0'                    # Protocol version for environment profiles
396
DEFAULT_BLOCKSIZE = 4096                 # Default block size for file operations
397
DEFAULT_MAXMEM = 4 * 1024 * 1024        # Default memory limit (4MB)
398

399
# Environment profile components
400
INSTANCE_ID: str                         # Unique 128-bit identifier for current process
401
START_TIME_INFO: dict                    # Dictionary with startup time information
402

403
# Sentinel type
404
SentinelType = type(make_sentinel())     # Type of sentinel objects
405
```