0
# Jupyter Client
1

2
Jupyter Client provides the reference implementation of the Jupyter protocol and essential client and kernel management APIs for working with Jupyter kernels. It serves as the foundational communication layer between Jupyter frontends (like JupyterLab, Notebook) and computational kernels, handling message passing, kernel lifecycle management, and protocol compliance.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import jupyter_client
14
```
15

16
Common patterns for working with kernels:
17

18
```python
19
from jupyter_client import KernelManager, BlockingKernelClient
20
from jupyter_client import AsyncKernelManager, AsyncKernelClient
21
from jupyter_client import MultiKernelManager
22
```
23

24
For connection utilities:
25

26
```python
27
from jupyter_client import find_connection_file, write_connection_file
28
```
29

30
For kernel launching:
31

32
```python
33
from jupyter_client import launch_kernel
34
```
35

36
## Basic Usage
37

38
```python
39
from jupyter_client import KernelManager
40

41
# Create and start a kernel
42
km = KernelManager()
43
km.start_kernel()
44

45
# Create a client to communicate with the kernel
46
kc = km.client()
47
kc.start_channels()
48

49
# Execute code
50
msg_id = kc.execute("print('Hello, World!')")
51

52
# Get the result
53
reply = kc.get_shell_msg()
54
print(reply['content'])
55

56
# Clean up
57
kc.stop_channels()
58
km.shutdown_kernel()
59
```
60

61
## Architecture
62

63
Jupyter Client is built around several key components:
64

65
- **Kernel Management**: `KernelManager` and `MultiKernelManager` classes handle kernel lifecycle
66
- **Client Communication**: `KernelClient` classes provide APIs for sending messages to kernels
67
- **Connection Infrastructure**: Connection file management and network setup utilities
68
- **Provisioning System**: Pluggable kernel provisioning with local and remote implementations
69
- **Protocol Implementation**: Complete Jupyter protocol message handling and authentication
70

71
The library supports both synchronous (blocking) and asynchronous communication patterns, making it suitable for various integration scenarios from simple scripts to complex distributed systems.
72

73
## Capabilities
74

75
### Kernel Management
76

77
Single and multi-kernel lifecycle management including starting, stopping, restarting, and monitoring kernels. Supports both synchronous and asynchronous operations.
78

79
```python { .api }
80
class KernelManager:
81
    def start_kernel(self, **kwargs): ...
82
    def shutdown_kernel(self, now=False, restart=False): ...
83
    def restart_kernel(self, now=False, **kwargs): ...
84
    def interrupt_kernel(self): ...
85
    def is_alive(self): ...
86
    def client(self, **kwargs) -> BlockingKernelClient: ...
87

88
class AsyncKernelManager(KernelManager):
89
    def client(self, **kwargs) -> AsyncKernelClient: ...
90

91
class MultiKernelManager:
92
    def start_kernel(self, kernel_name=None, **kwargs) -> str: ...
93
    def shutdown_kernel(self, kernel_id, now=False, restart=False): ...
94
    def get_kernel(self, kernel_id) -> KernelManager: ...
95
    def list_kernel_ids(self) -> list: ...
96
```
97

98
[Kernel Management](./kernel-management.md)
99

100
### Client Communication
101

102
Kernel communication clients for executing code, sending messages, and receiving results. Provides both blocking and asynchronous interfaces for different usage patterns.
103

104
```python { .api }
105
class KernelClient:
106
    def execute(self, code, silent=False, store_history=True, **kwargs) -> str: ...
107
    def complete(self, code, cursor_pos=None) -> str: ...
108
    def inspect(self, code, cursor_pos=None, detail_level=0) -> str: ...
109
    def history(self, **kwargs) -> str: ...
110
    def kernel_info(self) -> str: ...
111
    def is_complete(self, code) -> str: ...
112
    def shutdown(self, restart=False) -> str: ...
113
    def start_channels(self, **kwargs): ...
114
    def stop_channels(self): ...
115

116
class BlockingKernelClient(KernelClient):
117
    def get_shell_msg(self, **kwargs) -> dict: ...
118
    def get_iopub_msg(self, **kwargs) -> dict: ...
119
    def wait_for_ready(self, timeout=None): ...
120
    def is_alive(self) -> bool: ...
121

122
class AsyncKernelClient(KernelClient):
123
    async def get_shell_msg(self, **kwargs) -> dict: ...
124
    async def get_iopub_msg(self, **kwargs) -> dict: ...
125
    async def wait_for_ready(self, timeout=None): ...
126
    async def is_alive(self) -> bool: ...
127
```
128

129
[Client Communication](./client-communication.md)
130

131
### Connection Management
132

133
Connection file handling, port management, and network configuration for kernel connections. Includes utilities for SSH tunneling and connection discovery.
134

135
```python { .api }
136
def write_connection_file(fname=None, shell_port=0, iopub_port=0, 
137
                         stdin_port=0, hb_port=0, control_port=0, 
138
                         ip='', key=b'', transport='tcp', **kwargs) -> tuple: ...
139

140
def find_connection_file(filename='kernel-*.json', path=None) -> str: ...
141

142
def tunnel_to_kernel(connection_info, sshserver, sshkey=None) -> tuple: ...
143

144
class ConnectionFileMixin:
145
    def load_connection_file(self, connection_file=None): ...
146
    def get_connection_info(self, session=False) -> dict: ...
147
    def cleanup_connection_file(self): ...
148
```
149

150
[Connection Management](./connection-management.md)
151

152
### Kernel Provisioning
153

154
Pluggable kernel provisioning system for starting kernels in different environments. Supports local subprocess provisioning and extensible remote provisioning.
155

156
```python { .api }
157
class KernelProvisionerBase:
158
    @property
159
    def has_process(self) -> bool: ...
160
    async def poll(self) -> int | None: ...
161
    async def wait(self) -> int | None: ...
162
    async def send_signal(self, signum): ...
163
    async def kill(self, restart=False): ...
164
    async def terminate(self, restart=False): ...
165
    async def launch_kernel(self, cmd, **kwargs) -> dict: ...
166

167
class LocalProvisioner(KernelProvisionerBase):
168
    # Local subprocess implementation
169
    ...
170

171
class KernelProvisionerFactory:
172
    def create_provisioner_instance(self, kernel_id, kernel_spec, parent): ...
173
    def get_provisioner_entries(self) -> dict: ...
174
```
175

176
[Kernel Provisioning](./kernel-provisioning.md)
177

178
### Session and Messaging
179

180
Jupyter protocol message handling, serialization, authentication, and session management. Provides complete protocol implementation with signing and security features.
181

182
```python { .api }
183
class Session:
184
    def msg(self, msg_type, content=None, parent=None, **kwargs) -> dict: ...
185
    def sign(self, msg_list) -> bytes: ...
186
    def serialize(self, msg, ident=None) -> list: ...
187
    def deserialize(self, msg_list, content=True, copy=True) -> dict: ...
188
    def send(self, socket, msg_or_type, content=None, **kwargs): ...
189
    def recv(self, socket, mode=0, content=True, copy=True) -> dict: ...
190
    def clone(self) -> Session: ...
191

192
def msg_header(msg_id, msg_type, username, session, **kwargs) -> dict: ...
193
def extract_header(msg_or_header) -> dict: ...
194
```
195

196
[Session and Messaging](./session-messaging.md)
197

198
### Kernel Specifications
199

200
Kernel specification discovery, installation, and management. Handles kernel.json files and kernel discovery across system and user directories.
201

202
```python { .api }
203
class KernelSpec:
204
    @classmethod
205
    def from_resource_dir(cls, resource_dir) -> KernelSpec: ...
206
    def to_dict(self) -> dict: ...
207
    def to_json(self) -> str: ...
208

209
class KernelSpecManager:
210
    def find_kernel_specs(self) -> dict: ...
211
    def get_kernel_spec(self, kernel_name) -> KernelSpec: ...
212
    def get_all_specs(self) -> dict: ...
213
    def install_kernel_spec(self, source_dir, kernel_name=None, **kwargs) -> str: ...
214
    def remove_kernel_spec(self, name) -> str: ...
215

216
def find_kernel_specs() -> dict: ...
217
def get_kernel_spec(kernel_name) -> KernelSpec: ...
218
def install_kernel_spec(source_dir, **kwargs) -> str: ...
219
```
220

221
[Kernel Specifications](./kernel-specifications.md)
222

223
## Types
224

225
```python { .api }
226
# Connection information dictionary
227
KernelConnectionInfo = Dict[str, Union[int, str, bytes]]
228

229
# Version information
230
from jupyter_client import __version__, version_info
231
from jupyter_client import protocol_version, protocol_version_info
232

233
# Exception types
234
class DuplicateKernelError(Exception): ...
235
class NoSuchKernel(KeyError): ...
236
class InvalidPortNumber(Exception): ...
237
```