0
# IPykernel
1

2
IPython Kernel for Jupyter - provides the core communication layer between Jupyter frontends and the Python interpreter, enabling interactive computing with Python in Jupyter notebooks and other frontends. The kernel handles code execution, output capture, completion, introspection, debugging capabilities, and implements the Jupyter messaging protocol for real-time bidirectional communication.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import ipykernel
14
```
15

16
Common for accessing kernel functionality:
17

18
```python
19
from ipykernel import connect
20
from ipykernel.kernelapp import IPKernelApp
21
from ipykernel.ipkernel import IPythonKernel
22
```
23

24
## Basic Usage
25

26
```python
27
from ipykernel.kernelapp import launch_new_instance
28
from ipykernel.embed import embed_kernel
29
from ipykernel import get_connection_info, connect_qtconsole
30

31
# Launch a new kernel instance
32
launch_new_instance()
33

34
# Embed a kernel in current scope for interactive use
35
embed_kernel()
36

37
# Get connection information for current kernel
38
connection_info = get_connection_info()
39
print(f"Kernel connection file: {connection_info}")
40

41
# Connect a qtconsole to current kernel
42
connect_qtconsole()
43
```
44

45
## Architecture
46

47
IPykernel follows a layered architecture designed around the Jupyter messaging protocol:
48

49
- **Application Layer**: Kernel lifecycle management and application framework
50
- **Core Kernel**: IPython kernel implementation with message handling and execution
51
- **Communication Layer**: ZMQ-based messaging, connection management, and I/O streams
52
- **Integration Layer**: GUI event loops, matplotlib backends, and external tool integration
53
- **Utility Layer**: Data serialization, JSON handling, and kernel utilities
54
- **Specialized Features**: Embedding, in-process kernels, and async execution support
55

56
This architecture enables the kernel to serve as the foundation for interactive Python computing in the Jupyter ecosystem, supporting code execution, rich display output, interactive widgets, debugging, and integration with scientific computing libraries.
57

58
## Capabilities
59

60
### Kernel Application and Lifecycle
61

62
Core kernel application framework for launching, configuring, and managing IPython kernel instances. Provides entry points for starting kernels and installing kernel specifications.
63

64
```python { .api }
65
class IPKernelApp:
66
    def initialize(self, argv=None): ...
67
    def start(self): ...
68

69
def launch_new_instance(argv=None, **kwargs): ...
70
```
71

72
[Kernel Application](./kernel-application.md)
73

74
### Core Kernel Implementation
75

76
The main IPython kernel that handles code execution, message processing, and maintains kernel state. Provides the core functionality for interactive Python computing.
77

78
```python { .api }
79
class IPythonKernel:
80
    def do_execute(self, code, silent, store_history=True, user_expressions=None, allow_stdin=None): ...
81
    def do_complete(self, code, cursor_pos): ...
82
    def do_inspect(self, code, cursor_pos, detail_level=0): ...
83
```
84

85
[Core Kernel](./core-kernel.md)
86

87
### Connection and Communication
88

89
Utilities for establishing and managing connections between Jupyter frontends and kernels. Handles connection files, ZMQ socket management, and communication setup.
90

91
```python { .api }
92
def get_connection_file(): ...
93
def get_connection_info(): ...
94
def connect_qtconsole(argv=None, **kwargs): ...
95
def write_connection_file(fname=None, **kwargs): ...
96
```
97

98
[Connection Management](./connection-management.md)
99

100
### Communication Framework (Comm)
101

102
Bidirectional communication system between frontends and kernels for custom messages and interactive widgets. Enables real-time data exchange beyond standard execution.
103

104
```python { .api }
105
class Comm:
106
    def __init__(self, target_name=None, data=None, **kwargs): ...
107
    def send(self, data=None, buffers=None): ...
108
    def close(self, data=None, buffers=None): ...
109

110
class CommManager:
111
    def register_target(self, target_name, f): ...
112
    def register_comm(self, comm): ...
113
```
114

115
[Communication Framework](./communication-framework.md)
116

117
### Kernel Embedding
118

119
Tools for embedding IPython kernels directly into Python applications and interactive sessions, enabling kernel functionality within existing codebases.
120

121
```python { .api }
122
def embed_kernel(module=None, local_ns=None, **kwargs): ...
123
```
124

125
[Kernel Embedding](./kernel-embedding.md)
126

127
### In-Process Kernels
128

129
Complete in-process kernel implementation for scenarios requiring tight integration without separate processes. Includes clients, managers, and communication channels.
130

131
```python { .api }
132
class InProcessKernelManager:
133
    def start_kernel(self, **kwargs): ...
134
    def restart_kernel(self, **kwargs): ...
135

136
class InProcessKernelClient:
137
    def execute(self, code, **kwargs): ...
138
    def complete(self, code, **kwargs): ...
139
```
140

141
[In-Process Kernels](./in-process-kernels.md)
142

143
### GUI Integration and Event Loops
144

145
Integration with GUI toolkits (Qt, Tkinter, GTK, etc.) enabling matplotlib and other GUI libraries to work seamlessly within Jupyter environments.
146

147
```python { .api }
148
def enable_gui(gui=None): ...
149
def register_integration(gui): ...
150
```
151

152
[GUI Integration](./gui-integration.md)
153

154
### Matplotlib and Display Integration
155

156
Specialized support for matplotlib inline plotting, display hooks for rich output, and integration with Jupyter's display system.
157

158
```python { .api }
159
def show(close=None): ...
160
def flush_figures(): ...
161
def configure_inline_support(shell, backend): ...
162
```
163

164
[Matplotlib Integration](./matplotlib-integration.md)
165

166
### I/O and Streaming
167

168
Stream handling for capturing and redirecting stdout/stderr, managing kernel output publishing, and handling interactive input/output.
169

170
```python { .api }
171
class OutStream:
172
    def write(self, string): ...
173
    def flush(self): ...
174

175
class IOPubThread:
176
    def start(self): ...
177
    def stop(self): ...
178
```
179

180
[I/O and Streaming](./io-streaming.md)
181

182
### Data Serialization and Utilities
183

184
Utilities for JSON serialization, data cleaning, image encoding, and kernel-specific data handling requirements.
185

186
```python { .api }
187
def json_clean(obj): ...
188
def encode_images(format_dict): ...
189
def publish_data(data, metadata=None): ...
190
```
191

192
[Data Utilities](./data-utilities.md)
193

194
## Version Information
195

196
```python { .api }
197
# Available at package level
198
version_info: tuple
199
__version__: str
200
kernel_protocol_version_info: tuple  
201
kernel_protocol_version: str
202
```
203

204
## Types
205

206
```python { .api }
207
# Connection information structure
208
ConnectionInfo = dict[str, Any]  # Contains ports, transport, ip, etc.
209

210
# Execution result structure  
211
ExecutionResult = dict[str, Any]  # Contains status, execution_count, etc.
212

213
# Completion result structure
214
CompletionResult = dict[str, Any]  # Contains matches, cursor_start, cursor_end
215

216
# Inspection result structure  
217
InspectionResult = dict[str, Any]  # Contains found, data, metadata
218
```