0
# Google Colab Integration (ecolab)
1

2
Utilities specifically designed for Google Colab environments including enhanced display functions, code inspection, HTML rendering, Python-JavaScript communication, and development workflow improvements.
3

4
## Capabilities
5

6
### Display and Visualization
7

8
Enhanced display functions for better Colab experience.
9

10
```python { .api }
11
def auto_display(obj: Any) -> None:
12
    """
13
    Automatically display objects with enhanced formatting in Colab.
14
    
15
    Args:
16
        obj: Object to display (lists, dicts, images, etc.)
17
    """
18

19
def disp(obj: Any) -> None:
20
    """
21
    Shorthand for auto_display function.
22
    
23
    Args:
24
        obj: Object to display
25
    """
26

27
def auto_plot_array(
28
    array: np.ndarray,
29
    **kwargs
30
) -> None:
31
    """
32
    Automatically plot arrays as images when appropriate.
33
    
34
    Args:
35
        array: NumPy array to potentially plot as image
36
        **kwargs: Additional plotting arguments
37
    """
38
```
39

40
### Colab Interface Utilities
41

42
Functions for enhancing the Colab interface.
43

44
```python { .api }
45
def collapse(content: str, title: str = 'Details') -> None:
46
    """
47
    Create a collapsible section in Colab output.
48
    
49
    Args:
50
        content: Content to display in collapsible section
51
        title: Title for the collapsible section
52
    """
53

54
def get_permalink() -> str:
55
    """
56
    Get a permalink to the current Colab notebook.
57
    
58
    Returns:
59
        Permalink URL string
60
    """
61

62
def interruptible(fn: Callable) -> Callable:
63
    """
64
    Decorator to make long-running functions interruptible in Colab.
65
    
66
    Args:
67
        fn: Function to make interruptible
68
        
69
    Returns:
70
        Wrapped function that can be interrupted
71
    """
72

73
def json(obj: Any) -> None:
74
    """
75
    Display objects as formatted JSON in Colab.
76
    
77
    Args:
78
        obj: Object to display as JSON
79
    """
80
```
81

82
### Code Inspection and Analysis
83

84
Tools for inspecting and analyzing code in Colab.
85

86
```python { .api }
87
def auto_inspect(obj: Any) -> None:
88
    """
89
    Automatically inspect objects with enhanced Colab display.
90
    
91
    Args:
92
        obj: Object to inspect (functions, classes, modules)
93
    """
94

95
def inspect(
96
    obj: Any,
97
    show_source: bool = True,
98
    show_docs: bool = True
99
) -> None:
100
    """
101
    Inspect objects with detailed information display.
102
    
103
    Args:
104
        obj: Object to inspect
105
        show_source: Whether to show source code
106
        show_docs: Whether to show documentation
107
    """
108
```
109

110
### HTML and Syntax Highlighting
111

112
Enhanced HTML rendering and code highlighting.
113

114
```python { .api }
115
def highlight_html(
116
    code: str,
117
    language: str = 'python'
118
) -> str:
119
    """
120
    Generate syntax-highlighted HTML for code.
121
    
122
    Args:
123
        code: Source code to highlight
124
        language: Programming language for syntax highlighting
125
        
126
    Returns:
127
        HTML string with syntax highlighting
128
    """
129
```
130

131
### Environment Configuration
132

133
Tools for configuring the Colab environment.
134

135
```python { .api }
136
def patch_graphviz() -> None:
137
    """
138
    Patch graphviz for better Colab compatibility.
139
    """
140

141
def set_verbose(level: bool | int = True) -> None:
142
    """
143
    Set verbosity level for various operations.
144
    
145
    Args:
146
        level: Verbosity level (True/False or integer)
147
    """
148
```
149

150
### Python-JavaScript Communication
151

152
Bridge between Python and JavaScript in Colab.
153

154
```python { .api }
155
def pyjs_import(
156
    python_fn: Callable,
157
    name: str | None = None
158
) -> str:
159
    """
160
    Make Python function available to JavaScript.
161
    
162
    Args:
163
        python_fn: Python function to expose
164
        name: Name to use in JavaScript (defaults to function name)
165
        
166
    Returns:
167
        JavaScript code to call the function
168
    """
169

170
def register_js_fn(
171
    js_fn_name: str,
172
    python_handler: Callable
173
) -> None:
174
    """
175
    Register JavaScript function to call Python handler.
176
    
177
    Args:
178
        js_fn_name: Name of JavaScript function
179
        python_handler: Python function to handle calls
180
    """
181
```
182

183
### Module Management
184

185
Utilities for managing modules and reloading in Colab.
186

187
```python { .api }
188
class ReloadMode(Enum):
189
    """
190
    Enumeration for module reload modes.
191
    """
192
    NONE = "none"
193
    SOFT = "soft"
194
    HARD = "hard"
195

196
def clear_cached_modules() -> None:
197
    """
198
    Clear cached modules for fresh imports.
199
    """
200
```
201

202
## Usage Examples
203

204
### Enhanced Display
205

206
```python
207
from etils import ecolab
208
import numpy as np
209

210
# Auto display with enhanced formatting
211
data = {
212
    'experiment': 'vision_model_v2',
213
    'metrics': {'accuracy': 0.94, 'loss': 0.15},
214
    'config': {'batch_size': 32, 'learning_rate': 0.001}
215
}
216
ecolab.auto_display(data)  # Pretty formatted display
217

218
# Quick display shorthand
219
results = [1, 2, 3, 4, 5]
220
ecolab.disp(results)
221

222
# Automatic array plotting
223
image_array = np.random.rand(64, 64, 3)  # RGB image
224
ecolab.auto_plot_array(image_array)  # Automatically plots as image
225
```
226

227
### Interface Enhancements
228

229
```python
230
from etils import ecolab
231

232
# Create collapsible sections
233
long_output = "\\n".join([f"Line {i}" for i in range(100)])
234
ecolab.collapse(long_output, "Debug Output")
235

236
# Display as formatted JSON
237
config = {
238
    'model': {'layers': 4, 'units': 128},
239
    'training': {'epochs': 50, 'batch_size': 32}
240
}
241
ecolab.json(config)
242

243
# Get notebook permalink
244
permalink = ecolab.get_permalink()
245
print(f"Share this notebook: {permalink}")
246
```
247

248
### Code Inspection
249

250
```python
251
from etils import ecolab
252
import numpy as np
253

254
# Inspect functions with enhanced display
255
ecolab.inspect(np.array, show_source=True, show_docs=True)
256

257
# Auto-inspect with smart defaults
258
def my_function(x, y=10):
259
    """Example function for demonstration."""
260
    return x + y
261

262
ecolab.auto_inspect(my_function)
263
```
264

265
### Long-Running Operations
266

267
```python
268
from etils import ecolab
269
import time
270

271
@ecolab.interruptible
272
def long_training_loop():
273
    """Training loop that can be interrupted."""
274
    for epoch in range(1000):
275
        # Simulate training
276
        time.sleep(0.1)
277
        if epoch % 100 == 0:
278
            print(f"Epoch {epoch}")
279
    return "Training complete"
280

281
# Run the function - can be interrupted with stop button
282
result = long_training_loop()
283
```
284

285
### HTML and Highlighting
286

287
```python
288
from etils import ecolab
289

290
# Syntax highlighting
291
python_code = '''
292
def fibonacci(n):
293
    if n <= 1:
294
        return n
295
    return fibonacci(n-1) + fibonacci(n-2)
296
'''
297

298
highlighted = ecolab.highlight_html(python_code, 'python')
299
# Display highlighted code in Colab
300

301
# Different languages
302
js_code = '''
303
function factorial(n) {
304
    return n <= 1 ? 1 : n * factorial(n - 1);
305
}
306
'''
307
highlighted_js = ecolab.highlight_html(js_code, 'javascript')
308
```
309

310
### Python-JavaScript Bridge
311

312
```python
313
from etils import ecolab
314

315
# Expose Python function to JavaScript
316
def process_data(data):
317
    """Process data and return result."""
318
    return [x * 2 for x in data]
319

320
js_code = ecolab.pyjs_import(process_data, 'processData')
321
print(js_code)  # JavaScript code to call the function
322

323
# Register JavaScript callback
324
def handle_button_click(event_data):
325
    print(f"Button clicked with data: {event_data}")
326

327
ecolab.register_js_fn('onButtonClick', handle_button_click)
328
```
329

330
### Environment Configuration
331

332
```python
333
from etils import ecolab
334

335
# Configure graphviz for Colab
336
ecolab.patch_graphviz()
337

338
# Set verbosity for debugging
339
ecolab.set_verbose(True)  # Enable verbose output
340
ecolab.set_verbose(2)     # Higher verbosity level
341
ecolab.set_verbose(False) # Disable verbose output
342

343
# Clear module cache for development
344
ecolab.clear_cached_modules()
345
# Now reimport your modules to get latest changes
346
```
347

348
### Module Reloading
349

350
```python
351
from etils import ecolab
352

353
# Configure reload mode for development
354
reload_mode = ecolab.ReloadMode.SOFT
355

356
# Clear cached modules during development
357
ecolab.clear_cached_modules()
358

359
# Reimport your modules
360
import my_module  # Gets fresh version
361
```
362

363
### Development Workflow
364

365
```python
366
from etils import ecolab
367

368
# Complete development setup
369
ecolab.patch_graphviz()        # Fix graphviz
370
ecolab.set_verbose(True)       # Enable verbose logging
371
ecolab.clear_cached_modules()  # Clear module cache
372

373
# Enhanced display for debugging
374
debug_info = {
375
    'model_state': 'training',
376
    'current_epoch': 42,
377
    'gpu_memory': '8.2GB used / 16GB total'
378
}
379
ecolab.auto_display(debug_info)
380

381
# Collapsible debug output
382
debug_logs = "\\n".join([f"DEBUG: Step {i}" for i in range(50)])
383
ecolab.collapse(debug_logs, "Debug Logs")
384
```