0
# Connection Management
1

2
Connection file handling, port management, and network configuration for kernel connections. Includes utilities for creating connection files, discovering existing connections, SSH tunneling, and managing network ports.
3

4
## Capabilities
5

6
### Connection File Operations
7

8
Functions for creating, reading, and finding kernel connection files that contain network and authentication information for connecting to kernels.
9

10
```python { .api }
11
def write_connection_file(fname=None, shell_port=0, iopub_port=0, 
12
                         stdin_port=0, hb_port=0, control_port=0, 
13
                         ip='', key=b'', transport='tcp', 
14
                         signature_scheme='hmac-sha256', kernel_name='', 
15
                         **kwargs):
16
    """
17
    Write kernel connection information to a JSON file.
18
    
19
    Parameters:
20
    - fname (str): Connection file path (auto-generated if None)
21
    - shell_port (int): Port for shell channel (0 for auto-assign)
22
    - iopub_port (int): Port for iopub channel (0 for auto-assign)
23
    - stdin_port (int): Port for stdin channel (0 for auto-assign)
24
    - hb_port (int): Port for heartbeat channel (0 for auto-assign)
25
    - control_port (int): Port for control channel (0 for auto-assign)
26
    - ip (str): IP address for connections (empty for localhost)
27
    - key (bytes): Authentication key for message signing
28
    - transport (str): Transport protocol ('tcp' or 'ipc')
29
    - signature_scheme (str): Message signing scheme
30
    - kernel_name (str): Name of the kernel
31
    - **kwargs: Additional connection parameters
32
    
33
    Returns:
34
    tuple: (connection_file_path, connection_info_dict)
35
    """
36

37
def find_connection_file(filename='kernel-*.json', path=None, profile=None):
38
    """
39
    Find a kernel connection file.
40
    
41
    Parameters:
42
    - filename (str): Connection file pattern to search for
43
    - path (str): Directory to search in (runtime dir if None)
44
    - profile (str): Jupyter profile name
45
    
46
    Returns:
47
    str: Path to connection file
48
    
49
    Raises:
50
    IOError: If connection file not found
51
    """
52

53
def tunnel_to_kernel(connection_info, sshserver, sshkey=None):
54
    """
55
    Create SSH tunnels for connecting to a remote kernel.
56
    
57
    Parameters:
58
    - connection_info (dict): Kernel connection information
59
    - sshserver (str): SSH server address
60
    - sshkey (str): Path to SSH private key file
61
    
62
    Returns:
63
    tuple: (shell_port, iopub_port, stdin_port, hb_port, control_port)
64
    """
65
```
66

67
### Connection File Mixin
68

69
The `ConnectionFileMixin` class provides methods for handling connection files and network setup in kernel managers and clients.
70

71
```python { .api }
72
class ConnectionFileMixin:
73
    """Mixin for handling kernel connection files and network setup."""
74
    
75
    def write_connection_file(self, **kwargs):
76
        """
77
        Write connection info to file.
78
        
79
        Parameters:
80
        - **kwargs: Connection parameters (see write_connection_file)
81
        
82
        Returns:
83
        None
84
        """
85
    
86
    def load_connection_file(self, connection_file=None):
87
        """
88
        Load connection information from file.
89
        
90
        Parameters:
91
        - connection_file (str): Path to connection file
92
        
93
        Returns:
94
        None
95
        """
96
    
97
    def load_connection_info(self, info):
98
        """
99
        Load connection information from dictionary.
100
        
101
        Parameters:
102
        - info (dict): Connection information dictionary
103
        
104
        Returns:
105
        None
106
        """
107
    
108
    def get_connection_info(self, session=False):
109
        """
110
        Get current connection information.
111
        
112
        Parameters:
113
        - session (bool): Include session information if True
114
        
115
        Returns:
116
        dict: Connection information dictionary
117
        """
118
    
119
    def cleanup_connection_file(self):
120
        """
121
        Remove the connection file.
122
        
123
        Returns:
124
        None
125
        """
126
    
127
    def blocking_client(self):
128
        """
129
        Create a blocking client for this connection.
130
        
131
        Returns:
132
        BlockingKernelClient: Client instance
133
        """
134
    
135
    def connect_iopub(self, identity=None):
136
        """
137
        Connect to the iopub channel.
138
        
139
        Parameters:
140
        - identity (bytes): ZMQ identity for the socket
141
        
142
        Returns:
143
        zmq.Socket: Connected ZMQ socket
144
        """
145
    
146
    def connect_shell(self, identity=None):
147
        """
148
        Connect to the shell channel.
149
        
150
        Parameters:
151
        - identity (bytes): ZMQ identity for the socket
152
        
153
        Returns:
154
        zmq.Socket: Connected ZMQ socket
155
        """
156
    
157
    def connect_stdin(self, identity=None):
158
        """
159
        Connect to the stdin channel.
160
        
161
        Parameters:
162
        - identity (bytes): ZMQ identity for the socket
163
        
164
        Returns:
165
        zmq.Socket: Connected ZMQ socket
166
        """
167
    
168
    def connect_hb(self, identity=None):
169
        """
170
        Connect to the heartbeat channel.
171
        
172
        Parameters:
173
        - identity (bytes): ZMQ identity for the socket
174
        
175
        Returns:
176
        zmq.Socket: Connected ZMQ socket
177
        """
178
    
179
    def connect_control(self, identity=None):
180
        """
181
        Connect to the control channel.
182
        
183
        Parameters:
184
        - identity (bytes): ZMQ identity for the socket
185
        
186
        Returns:
187
        zmq.Socket: Connected ZMQ socket
188
        """
189

190
    # Configuration traits
191
    connection_file = None  # Path to connection file
192
    transport = 'tcp'       # Transport protocol
193
    ip = ''                 # IP address
194
    shell_port = 0          # Shell channel port
195
    iopub_port = 0          # IOPub channel port
196
    stdin_port = 0          # Stdin channel port
197
    hb_port = 0             # Heartbeat channel port
198
    control_port = 0        # Control channel port
199
```
200

201
### Port Management
202

203
The `LocalPortCache` singleton manages port allocation to prevent race conditions when starting multiple kernels.
204

205
```python { .api }
206
class LocalPortCache:
207
    """Singleton class for managing port allocation."""
208
    
209
    def find_available_port(self, ip):
210
        """
211
        Find an available port on the specified IP.
212
        
213
        Parameters:
214
        - ip (str): IP address to check ports on
215
        
216
        Returns:
217
        int: Available port number
218
        """
219
    
220
    def return_port(self, port):
221
        """
222
        Return a port to the available pool.
223
        
224
        Parameters:
225
        - port (int): Port number to return
226
        
227
        Returns:
228
        None
229
        """
230
```
231

232
### Kernel Launching
233

234
Low-level utilities for launching kernel processes with proper configuration and cross-platform support.
235

236
```python { .api }
237
def launch_kernel(cmd, stdin=None, stdout=None, stderr=None, 
238
                  env=None, independent=False, cwd=None, **kwargs):
239
    """
240
    Launch a kernel process with appropriate configuration.
241
    
242
    Parameters:
243
    - cmd (List[str]): Command list for launching the kernel
244
    - stdin (int, optional): Standard input file descriptor
245
    - stdout (int, optional): Standard output file descriptor  
246
    - stderr (int, optional): Standard error file descriptor
247
    - env (Dict[str, str], optional): Environment variables for kernel
248
    - independent (bool): Whether kernel survives parent process death
249
    - cwd (str, optional): Working directory for kernel process
250
    - **kwargs: Additional arguments passed to subprocess.Popen
251
    
252
    Returns:
253
    subprocess.Popen: Kernel process instance
254
    """
255
```
256

257
### SSH Tunneling
258

259
Functions for creating SSH tunnels to connect to remote kernels securely.
260

261
```python { .api }
262
def ssh_tunnel(lport, rport, server, remoteip='127.0.0.1', 
263
               keyfile=None, password=None, timeout=0.4):
264
    """
265
    Create an SSH tunnel.
266
    
267
    Parameters:
268
    - lport (int): Local port number
269
    - rport (int): Remote port number
270
    - server (str): SSH server address
271
    - remoteip (str): Remote IP address to tunnel to
272
    - keyfile (str): Path to SSH private key
273
    - password (str): SSH password (if not using key)
274
    - timeout (float): Connection timeout
275
    
276
    Returns:
277
    subprocess.Popen: SSH process
278
    """
279

280
def forward_tunnel(local_port, remote_port, remote_host, ssh_server,
281
                  ssh_keyfile=None, password=None):
282
    """
283
    Create a port forwarding tunnel.
284
    
285
    Parameters:
286
    - local_port (int): Local port to bind to
287
    - remote_port (int): Remote port to forward to
288
    - remote_host (str): Remote host address
289
    - ssh_server (str): SSH server for tunneling
290
    - ssh_keyfile (str): Path to SSH private key
291
    - password (str): SSH password
292
    
293
    Returns:
294
    ForwardServer: Server instance managing the tunnel
295
    """
296
```
297

298
### Types
299

300
```python { .api }
301
# Type alias for connection information
302
KernelConnectionInfo = Dict[str, Union[int, str, bytes]]
303
```
304

305
## Usage Examples
306

307
### Creating Connection Files
308

309
```python
310
from jupyter_client import write_connection_file
311

312
# Create connection file with auto-assigned ports
313
fname, connection_info = write_connection_file()
314
print(f"Connection file: {fname}")
315
print(f"Connection info: {connection_info}")
316

317
# Create with specific configuration
318
fname, connection_info = write_connection_file(
319
    ip='192.168.1.100',
320
    shell_port=50001,
321
    iopub_port=50002,
322
    stdin_port=50003,
323
    hb_port=50004,
324
    control_port=50005,
325
    kernel_name='python3'
326
)
327
```
328

329
### Finding and Loading Connection Files
330

331
```python
332
from jupyter_client import find_connection_file, KernelManager
333

334
# Find existing connection file
335
try:
336
    conn_file = find_connection_file('kernel-12345.json')
337
    print(f"Found connection file: {conn_file}")
338
except IOError:
339
    print("Connection file not found")
340

341
# Load connection in kernel manager
342
km = KernelManager()
343
km.load_connection_file(conn_file)
344

345
# Create client from loaded connection
346
kc = km.client()
347
```
348

349
### Working with Connection Information
350

351
```python
352
from jupyter_client import KernelManager
353

354
km = KernelManager()
355
km.start_kernel()
356

357
# Get connection information
358
conn_info = km.get_connection_info()
359
print(f"Shell port: {conn_info['shell_port']}")
360
print(f"IOPub port: {conn_info['iopub_port']}")
361
print(f"Transport: {conn_info['transport']}")
362
print(f"IP: {conn_info['ip']}")
363

364
# Load connection info into another manager
365
km2 = KernelManager()
366
km2.load_connection_info(conn_info)
367

368
# Clean up
369
km.cleanup_connection_file()
370
```
371

372
### SSH Tunneling to Remote Kernel
373

374
```python
375
from jupyter_client import tunnel_to_kernel, find_connection_file
376

377
# Find remote kernel connection file
378
remote_conn_file = find_connection_file('kernel-remote.json')
379

380
# Load connection info
381
with open(remote_conn_file, 'r') as f:
382
    import json
383
    remote_conn_info = json.load(f)
384

385
# Create SSH tunnels
386
local_ports = tunnel_to_kernel(
387
    remote_conn_info, 
388
    sshserver='user@remote-server.com',
389
    sshkey='/path/to/private_key'
390
)
391

392
print(f"Local tunnel ports: {local_ports}")
393

394
# Now connect using local ports
395
from jupyter_client import KernelManager
396
km = KernelManager()
397

398
# Update connection info with local tunnel ports
399
tunnel_conn_info = remote_conn_info.copy()
400
tunnel_conn_info.update({
401
    'shell_port': local_ports[0],
402
    'iopub_port': local_ports[1],
403
    'stdin_port': local_ports[2],
404
    'hb_port': local_ports[3],
405
    'control_port': local_ports[4],
406
    'ip': '127.0.0.1'  # Connect to local tunnel
407
})
408

409
km.load_connection_info(tunnel_conn_info)
410
kc = km.client()
411
```
412

413
### Port Management
414

415
```python
416
from jupyter_client.connect import LocalPortCache
417

418
# Get port cache instance
419
port_cache = LocalPortCache.instance()
420

421
# Find available port
422
available_port = port_cache.find_available_port('127.0.0.1')
423
print(f"Available port: {available_port}")
424

425
# Use the port...
426

427
# Return port when done
428
port_cache.return_port(available_port)
429
```
430

431
### Direct Socket Connections
432

433
```python
434
from jupyter_client import KernelManager
435
import zmq
436

437
km = KernelManager()
438
km.start_kernel()
439

440
# Connect to individual channels
441
context = zmq.Context()
442

443
# Connect to shell channel
444
shell_socket = km.connect_shell()
445
shell_socket.send_multipart([b'execute_request', b'print("hello")'])
446

447
# Connect to iopub channel  
448
iopub_socket = km.connect_iopub()
449
message = iopub_socket.recv_multipart()
450

451
# Clean up
452
shell_socket.close()
453
iopub_socket.close()
454
context.term()
455
km.shutdown_kernel()
456
```
457

458
### Low-Level Kernel Launching
459

460
```python
461
from jupyter_client import launch_kernel
462
import subprocess
463
import sys
464

465
# Launch a Python kernel directly
466
kernel_cmd = [
467
    sys.executable, '-m', 'ipykernel_launcher',
468
    '-f', 'connection-file.json'
469
]
470

471
# Launch with custom environment
472
custom_env = {'PYTHONPATH': '/custom/path'}
473
kernel_proc = launch_kernel(
474
    kernel_cmd,
475
    env=custom_env,
476
    cwd='/custom/working/dir',
477
    independent=True  # Kernel survives if parent dies
478
)
479

480
print(f"Kernel PID: {kernel_proc.pid}")
481

482
# Monitor kernel status
483
if kernel_proc.poll() is None:
484
    print("Kernel is running")
485
else:
486
    print(f"Kernel exited with code: {kernel_proc.returncode}")
487

488
# Terminate kernel when done
489
kernel_proc.terminate()
490
kernel_proc.wait()
491
```