0
# Kernel Embedding
1
2
Tools for embedding IPython kernels directly into Python applications and interactive sessions, enabling kernel functionality within existing codebases for debugging, interactive development, and creating custom interactive environments.
3
4
## Capabilities
5
6
### Kernel Embedding Function
7
8
Primary function for embedding a kernel into the current Python context.
9
10
```python { .api }
11
def embed_kernel(module=None, local_ns=None, **kwargs):
12
"""
13
Embed and start an IPython kernel in the current scope.
14
15
This creates an interactive kernel that can be connected to by
16
Jupyter frontends while maintaining access to the local variables
17
and execution context where it was called.
18
19
Parameters:
20
- module (module, optional): Module to use as __main__ context
21
- local_ns (dict, optional): Local namespace for kernel execution
22
- **kwargs: Additional kernel configuration options including:
23
- user_ns (dict): User namespace for kernel
24
- connection_file (str): Path to connection file
25
- ip (str): IP address for kernel connections
26
- shell_port (int): Port for shell messages
27
- iopub_port (int): Port for IOPub messages
28
- stdin_port (int): Port for stdin messages
29
- control_port (int): Port for control messages
30
- hb_port (int): Port for heartbeat
31
32
Returns:
33
None (starts kernel event loop, blocks until shutdown)
34
35
Example:
36
```python
37
import ipykernel
38
39
# Embed kernel with current local variables
40
x = 42
41
y = "hello"
42
ipykernel.embed_kernel() # x and y available in kernel
43
```
44
"""
45
```
46
47
## Usage Examples
48
49
### Basic Kernel Embedding
50
51
```python
52
from ipykernel import embed_kernel
53
54
def my_function():
55
x = 42
56
data = [1, 2, 3, 4, 5]
57
58
print("Starting embedded kernel...")
59
print("Variables 'x' and 'data' are available in the kernel")
60
61
# Embed kernel with access to local variables
62
embed_kernel() # Blocks here until kernel shutdown
63
64
# Call the function
65
my_function()
66
```
67
68
### Embedding with Custom Namespace
69
70
```python
71
from ipykernel import embed_kernel
72
73
# Create custom namespace for kernel
74
custom_ns = {
75
'config': {'debug': True, 'max_items': 100},
76
'utils': {'format_data': lambda x: f"Data: {x}"},
77
'data_store': []
78
}
79
80
print("Embedding kernel with custom utilities...")
81
embed_kernel(user_ns=custom_ns)
82
```
83
84
### Debugging with Embedded Kernel
85
86
```python
87
from ipykernel import embed_kernel
88
89
def complex_algorithm(data):
90
"""Complex function that might need debugging."""
91
processed = []
92
93
for i, item in enumerate(data):
94
# Complex processing logic
95
result = item * 2 + i
96
processed.append(result)
97
98
# Embed kernel for debugging at specific point
99
if len(processed) == 3:
100
print("Debugging checkpoint reached")
101
print(f"Current state: processed={processed}")
102
embed_kernel() # Debug here with full context
103
104
return processed
105
106
# Run with debugging
107
result = complex_algorithm([10, 20, 30, 40, 50])
108
```
109
110
### Interactive Development Environment
111
112
```python
113
from ipykernel import embed_kernel
114
import sys
115
import os
116
117
class InteractiveDevelopment:
118
"""Custom interactive development environment."""
119
120
def __init__(self, project_path):
121
self.project_path = project_path
122
self.modules_loaded = []
123
124
# Add project to Python path
125
if project_path not in sys.path:
126
sys.path.insert(0, project_path)
127
128
def load_module(self, module_name):
129
"""Load and track project modules."""
130
try:
131
module = __import__(module_name)
132
self.modules_loaded.append(module_name)
133
return module
134
except ImportError as e:
135
print(f"Failed to load {module_name}: {e}")
136
return None
137
138
def start_interactive_session(self):
139
"""Start embedded kernel with development context."""
140
# Create development namespace
141
dev_ns = {
142
'project_path': self.project_path,
143
'load_module': self.load_module,
144
'modules_loaded': self.modules_loaded,
145
'reload_module': lambda name: __import__(name, fromlist=[''],
146
level=0).__dict__.update(
147
__import__(name, fromlist=[''], level=0).__dict__
148
)
149
}
150
151
print(f"Starting interactive development session for: {self.project_path}")
152
print("Available tools: load_module(), reload_module(), modules_loaded")
153
154
embed_kernel(user_ns=dev_ns)
155
156
# Usage
157
dev_env = InteractiveDevelopment('/path/to/my/project')
158
dev_env.start_interactive_session()
159
```
160
161
### Embedding with Connection Configuration
162
163
```python
164
from ipykernel import embed_kernel
165
import tempfile
166
import os
167
168
# Create temporary connection file
169
with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
170
connection_file = f.name
171
172
try:
173
print(f"Starting kernel with connection file: {connection_file}")
174
175
# Embed with specific connection configuration
176
embed_kernel(
177
connection_file=connection_file,
178
ip='127.0.0.1',
179
shell_port=54321,
180
iopub_port=54322,
181
stdin_port=54323,
182
control_port=54324,
183
hb_port=54325
184
)
185
186
finally:
187
# Cleanup connection file
188
if os.path.exists(connection_file):
189
os.unlink(connection_file)
190
```
191
192
### Class-Based Embedding
193
194
```python
195
from ipykernel import embed_kernel
196
197
class DataProcessor:
198
"""Example class with embedded debugging capabilities."""
199
200
def __init__(self, config):
201
self.config = config
202
self.processed_items = []
203
self.debug_mode = config.get('debug', False)
204
205
def process_data(self, data):
206
"""Process data with optional embedded debugging."""
207
for item in data:
208
processed = self._process_item(item)
209
self.processed_items.append(processed)
210
211
# Embed kernel for debugging if enabled
212
if self.debug_mode and len(self.processed_items) % 10 == 0:
213
print(f"Processed {len(self.processed_items)} items")
214
self._debug_checkpoint()
215
216
def _process_item(self, item):
217
"""Process individual item."""
218
return {'original': item, 'processed': item * 2}
219
220
def _debug_checkpoint(self):
221
"""Embed kernel with class context."""
222
# Create namespace with class attributes
223
debug_ns = {
224
'processor': self,
225
'config': self.config,
226
'processed_items': self.processed_items,
227
'item_count': len(self.processed_items)
228
}
229
230
print("Debug checkpoint - 'processor' object available")
231
embed_kernel(user_ns=debug_ns)
232
233
# Usage with debugging enabled
234
processor = DataProcessor({'debug': True, 'batch_size': 100})
235
processor.process_data(range(25))
236
```
237
238
### Module Context Embedding
239
240
```python
241
from ipykernel import embed_kernel
242
import sys
243
244
# Save current module context
245
current_module = sys.modules[__name__]
246
247
def embed_with_module_context():
248
"""Embed kernel with current module as __main__."""
249
print("Embedding kernel with module context")
250
print(f"Current module: {current_module}")
251
252
# Embed with module context
253
embed_kernel(module=current_module)
254
255
# This makes the current module available as __main__ in kernel
256
embed_with_module_context()
257
```