0
# Hooks Module
1

2
Extension system for customizing Quilt3 behavior through configurable hook functions. Allows users to modify or extend core functionality by providing custom implementations for specific operations.
3

4
## Type Imports
5

6
```python { .api }
7
from typing import Optional, Callable
8
```
9

10
## Capabilities
11

12
### S3 Client Hook Management
13

14
Configure custom S3 client builders for specialized AWS operations.
15

16
```python { .api }
17
def get_build_s3_client_hook() -> Optional[BuildClientHook]:
18
    """
19
    Return the current build S3 client hook.
20

21
    Returns:
22
    The currently configured hook function, or None if no hook is set
23
    """
24

25
def set_build_s3_client_hook(hook: Optional[BuildClientHook]) -> Optional[BuildClientHook]:
26
    """
27
    Set the build S3 client hook.
28

29
    Parameters:
30
    - hook: Hook function to set, or None to clear the current hook
31

32
    Returns:
33
    The previously configured hook function, or None if no hook was set
34
    """
35
```
36

37
## Hook Types
38

39
### BuildClientHook
40

41
```python { .api }
42
BuildClientHook = Callable[..., Any]
43
"""
44
Type alias for S3 client builder hook functions.
45

46
Hook functions should accept boto3 session parameters and return
47
a configured S3 client or modify client behavior.
48
"""
49
```
50

51
## Usage Examples
52

53
### Basic Hook Configuration
54

55
```python
56
import quilt3.hooks
57

58
# Check current hook configuration
59
current_hook = quilt3.hooks.get_build_s3_client_hook()
60
if current_hook:
61
    print("S3 client hook is currently configured")
62
else:
63
    print("No S3 client hook configured")
64

65
# Clear any existing hook
66
previous_hook = quilt3.hooks.set_build_s3_client_hook(None)
67
print("Cleared S3 client hook")
68
```
69

70
### Custom S3 Client Hook
71

72
```python
73
import quilt3.hooks
74
import boto3
75

76
def custom_s3_client_builder(*args, **kwargs):
77
    """
78
    Custom S3 client builder with additional configuration.
79
    
80
    This example adds custom retry configuration and timeout settings.
81
    """
82
    # Create base session
83
    session = boto3.Session(*args, **kwargs)
84
    
85
    # Configure custom S3 client with retries and timeouts
86
    s3_client = session.client(
87
        's3',
88
        config=boto3.session.Config(
89
            retries={'max_attempts': 10, 'mode': 'adaptive'},
90
            connect_timeout=60,
91
            read_timeout=60
92
        )
93
    )
94
    
95
    return s3_client
96

97
# Install the custom hook
98
previous_hook = quilt3.hooks.set_build_s3_client_hook(custom_s3_client_builder)
99

100
# Now all Quilt operations will use the custom S3 client
101
import quilt3
102
bucket = quilt3.Bucket("s3://my-bucket")  # Will use custom client configuration
103
```
104

105
### Regional S3 Client Hook
106

107
```python
108
import quilt3.hooks
109
import boto3
110

111
def regional_s3_client_builder(*args, **kwargs):
112
    """
113
    Custom S3 client builder that forces a specific region.
114
    """
115
    # Extract region from kwargs or use default
116
    region = kwargs.pop('region_name', 'us-west-2')
117
    
118
    session = boto3.Session(*args, **kwargs)
119
    
120
    # Force specific region for all S3 operations
121
    s3_client = session.client('s3', region_name=region)
122
    
123
    print(f"Created S3 client for region: {region}")
124
    return s3_client
125

126
# Install regional hook
127
quilt3.hooks.set_build_s3_client_hook(regional_s3_client_builder)
128

129
# Test the hook
130
import quilt3
131
bucket = quilt3.Bucket("s3://my-bucket")
132
bucket.ls()  # Will use forced region configuration
133
```
134

135
### Development vs Production Hooks
136

137
```python
138
import quilt3.hooks
139
import boto3
140
import os
141

142
def environment_aware_s3_client(*args, **kwargs):
143
    """
144
    S3 client builder that adapts to development vs production environments.
145
    """
146
    env = os.getenv('ENVIRONMENT', 'development')
147
    
148
    session = boto3.Session(*args, **kwargs)
149
    
150
    if env == 'development':
151
        # Development: use localstack or minio
152
        s3_client = session.client(
153
            's3',
154
            endpoint_url='http://localhost:4566',  # LocalStack
155
            aws_access_key_id='test',
156
            aws_secret_access_key='test',
157
            region_name='us-east-1'
158
        )
159
        print("Using development S3 endpoint")
160
    else:
161
        # Production: use standard AWS S3
162
        s3_client = session.client('s3')
163
        print("Using production AWS S3")
164
    
165
    return s3_client
166

167
# Configure environment-aware hook
168
quilt3.hooks.set_build_s3_client_hook(environment_aware_s3_client)
169
```
170

171
### Hook with Logging and Monitoring
172

173
```python
174
import quilt3.hooks
175
import boto3
176
import logging
177
import time
178

179
# Configure logging
180
logging.basicConfig(level=logging.INFO)
181
logger = logging.getLogger(__name__)
182

183
def monitored_s3_client_builder(*args, **kwargs):
184
    """
185
    S3 client builder with logging and performance monitoring.
186
    """
187
    start_time = time.time()
188
    
189
    try:
190
        session = boto3.Session(*args, **kwargs)
191
        s3_client = session.client('s3')
192
        
193
        build_time = time.time() - start_time
194
        logger.info(f"S3 client built successfully in {build_time:.3f}s")
195
        
196
        return s3_client
197
        
198
    except Exception as e:
199
        build_time = time.time() - start_time
200
        logger.error(f"S3 client build failed after {build_time:.3f}s: {e}")
201
        raise
202

203
# Install monitoring hook
204
quilt3.hooks.set_build_s3_client_hook(monitored_s3_client_builder)
205

206
# All S3 operations will now be logged
207
import quilt3
208
bucket = quilt3.Bucket("s3://my-bucket")
209
files = bucket.ls()  # This will log client creation
210
```
211

212
### Temporary Hook Usage
213

214
```python
215
import quilt3.hooks
216
import contextlib
217

218
@contextlib.contextmanager
219
def temporary_s3_hook(hook_function):
220
    """
221
    Context manager for temporarily using a different S3 client hook.
222
    """
223
    # Save current hook
224
    previous_hook = quilt3.hooks.get_build_s3_client_hook()
225
    
226
    try:
227
        # Install temporary hook
228
        quilt3.hooks.set_build_s3_client_hook(hook_function)
229
        yield
230
    finally:
231
        # Restore previous hook
232
        quilt3.hooks.set_build_s3_client_hook(previous_hook)
233

234
# Define a temporary hook
235
def debug_s3_client(*args, **kwargs):
236
    print("Creating S3 client with debug configuration")
237
    session = boto3.Session(*args, **kwargs)
238
    return session.client('s3', config=boto3.session.Config(log_level=logging.DEBUG))
239

240
# Use temporary hook
241
with temporary_s3_hook(debug_s3_client):
242
    bucket = quilt3.Bucket("s3://my-bucket")
243
    bucket.ls()  # Uses debug S3 client
244

245
# After context, original hook is restored
246
bucket2 = quilt3.Bucket("s3://another-bucket")  
247
bucket2.ls()  # Uses original S3 client configuration
248
```
249

250
## Best Practices
251

252
### Hook Implementation Guidelines
253

254
- **Maintain compatibility**: Ensure custom hooks accept the same parameters as the default implementation
255
- **Handle errors gracefully**: Include proper error handling in hook functions
256
- **Log appropriately**: Add logging for debugging but avoid excessive output
257
- **Test thoroughly**: Verify hook behavior in different scenarios
258
- **Document configuration**: Document any environment variables or configuration requirements
259

260
### Performance Considerations
261

262
- **Avoid heavy operations**: Keep hook functions lightweight to prevent performance impact
263
- **Cache when appropriate**: Consider caching expensive operations within hooks
264
- **Monitor resource usage**: Be aware of memory and connection pool implications
265

266
### Security Considerations
267

268
- **Validate inputs**: Ensure hook functions validate any external inputs
269
- **Protect credentials**: Avoid logging or exposing sensitive credential information
270
- **Use secure defaults**: Default to secure configurations when possible
271

272
## Error Handling
273

274
```python
275
import quilt3.hooks
276
import boto3
277
import logging
278

279
def robust_s3_client_builder(*args, **kwargs):
280
    """
281
    Robust S3 client builder with comprehensive error handling.
282
    """
283
    try:
284
        session = boto3.Session(*args, **kwargs)
285
        s3_client = session.client('s3')
286
        
287
        # Test the client with a simple operation
288
        s3_client.list_buckets()
289
        
290
        return s3_client
291
        
292
    except Exception as e:
293
        logging.error(f"S3 client creation failed: {e}")
294
        
295
        # Fall back to default behavior or raise
296
        # Depending on your requirements:
297
        
298
        # Option 1: Re-raise the exception
299
        raise
300
        
301
        # Option 2: Return None to fall back to default
302
        # return None
303
        
304
        # Option 3: Try alternative configuration
305
        # return fallback_s3_client(*args, **kwargs)
306

307
# Install robust hook
308
quilt3.hooks.set_build_s3_client_hook(robust_s3_client_builder)
309
```