0
# Connection Management
1

2
Utilities for establishing and managing connections between Jupyter frontends and kernels. Handles connection files, ZMQ socket configuration, and communication setup for the Jupyter messaging protocol.
3

4
## Capabilities
5

6
### Connection File Operations
7

8
Functions for creating, locating, and managing kernel connection files that contain network configuration for frontend-kernel communication.
9

10
```python { .api }
11
def write_connection_file(fname=None, shell_port=0, iopub_port=0, 
12
                         stdin_port=0, control_port=0, hb_port=0,
13
                         ip='127.0.0.1', key=b'', transport='tcp',
14
                         signature_scheme='hmac-sha256', kernel_name=''):
15
    """
16
    Write connection information to a JSON file.
17
    
18
    Re-exported from jupyter_client for convenience.
19
    
20
    Parameters:
21
    - fname (str, optional): Filename for connection file
22
    - shell_port (int): Port for shell channel
23
    - iopub_port (int): Port for IOPub channel  
24
    - stdin_port (int): Port for stdin channel
25
    - control_port (int): Port for control channel
26
    - hb_port (int): Port for heartbeat
27
    - ip (str): IP address for connections
28
    - key (bytes): HMAC key for message authentication
29
    - transport (str): Transport protocol ('tcp' or 'ipc')
30
    - signature_scheme (str): Message signature scheme
31
    - kernel_name (str): Name of the kernel
32
    
33
    Returns:
34
    str: Path to the written connection file
35
    """
36

37
def get_connection_file():
38
    """
39
    Get the path to the current kernel's connection file.
40
    
41
    Returns the connection file path for the currently running kernel,
42
    or None if not running in a kernel context.
43
    
44
    Returns:
45
    str or None: Path to connection file, or None if not in kernel
46
    """
47

48
def find_connection_file(filename_or_glob='kernel-*.json', profile=None):
49
    """
50
    Find a connection file by name or glob pattern.
51
    
52
    **DEPRECATED**: This function is deprecated and may be removed.
53
    
54
    Parameters:
55
    - filename_or_glob (str): Filename or glob pattern to search
56
    - profile (str, optional): IPython profile directory to search
57
    
58
    Returns:
59
    str: Path to found connection file
60
    
61
    Raises:
62
    IOError: If no matching connection file is found
63
    """
64
```
65

66
### Connection Information
67

68
Functions for retrieving and using connection information from running kernels.
69

70
```python { .api }
71
def get_connection_info():
72
    """
73
    Get connection information for the current kernel.
74
    
75
    Returns connection details including ports, IP address, and other
76
    network configuration needed to connect to the running kernel.
77
    
78
    Returns:
79
    dict: Connection information dictionary containing:
80
        - shell_port (int): Shell channel port
81
        - iopub_port (int): IOPub channel port
82
        - stdin_port (int): Stdin channel port
83
        - control_port (int): Control channel port
84
        - hb_port (int): Heartbeat port
85
        - ip (str): IP address
86
        - key (str): HMAC key (base64 encoded)
87
        - transport (str): Transport protocol
88
        - signature_scheme (str): Signature scheme
89
    
90
    Raises:
91
    RuntimeError: If not running in a kernel context
92
    """
93
```
94

95
### Frontend Connection
96

97
Utilities for connecting external frontends to running kernels.
98

99
```python { .api }
100
def connect_qtconsole(argv=None, **kwargs):
101
    """
102
    Connect a qtconsole to the current kernel.
103
    
104
    Launches a new qtconsole instance connected to the currently
105
    running kernel using the kernel's connection information.
106
    
107
    Parameters:
108
    - argv (list, optional): Additional command-line arguments for qtconsole
109
    - **kwargs: Additional options passed to qtconsole
110
    
111
    Returns:
112
    subprocess.Popen: Process object for the launched qtconsole
113
    
114
    Raises:
115
    RuntimeError: If not running in a kernel context
116
    ImportError: If qtconsole is not available
117
    """
118
```
119

120
## Usage Examples
121

122
### Basic Connection Information
123

124
```python
125
from ipykernel import get_connection_info, get_connection_file
126

127
# Get current kernel's connection info (only works in kernel context)
128
try:
129
    info = get_connection_info()
130
    print(f"Kernel IP: {info['ip']}")
131
    print(f"Shell port: {info['shell_port']}")
132
    print(f"IOPub port: {info['iopub_port']}")
133
    
134
    # Get connection file path
135
    conn_file = get_connection_file()
136
    print(f"Connection file: {conn_file}")
137
    
138
except RuntimeError:
139
    print("Not running in a kernel context")
140
```
141

142
### Connecting External Frontends
143

144
```python
145
from ipykernel import connect_qtconsole
146

147
# Connect qtconsole to current kernel (only works in kernel context)
148
try:
149
    process = connect_qtconsole()
150
    print(f"Started qtconsole with PID: {process.pid}")
151
    
152
except RuntimeError:
153
    print("Not running in a kernel context")
154
except ImportError:
155
    print("qtconsole not available")
156
```
157

158
### Creating Connection Files
159

160
```python
161
from ipykernel import write_connection_file
162

163
# Create a connection file with specific configuration
164
conn_file = write_connection_file(
165
    fname='my-kernel.json',
166
    ip='192.168.1.100',
167
    shell_port=54321,
168
    iopub_port=54322,
169
    stdin_port=54323,
170
    control_port=54324,
171
    hb_port=54325,
172
    key=b'my-secret-key',
173
    kernel_name='my-python-kernel'
174
)
175

176
print(f"Created connection file: {conn_file}")
177
```
178

179
### Finding Connection Files
180

181
```python
182
from ipykernel import find_connection_file
183

184
# Find connection files (deprecated function)
185
try:
186
    conn_file = find_connection_file('kernel-*.json')
187
    print(f"Found connection file: {conn_file}")
188
    
189
except IOError:
190
    print("No connection files found")
191
```
192

193
### Reading Connection Information
194

195
```python
196
import json
197
from ipykernel import get_connection_file
198

199
# Read connection info from file
200
try:
201
    conn_file = get_connection_file()
202
    if conn_file:
203
        with open(conn_file, 'r') as f:
204
            conn_info = json.load(f)
205
        
206
        print("Connection configuration:")
207
        for key, value in conn_info.items():
208
            print(f"  {key}: {value}")
209
            
210
except (RuntimeError, FileNotFoundError):
211
    print("Could not read connection information")
212
```
213

214
## Connection File Format
215

216
Connection files are JSON documents with the following structure:
217

218
```python { .api }
219
ConnectionInfo = {
220
    "shell_port": int,      # Port for shell messages
221
    "iopub_port": int,      # Port for IOPub messages  
222
    "stdin_port": int,      # Port for stdin messages
223
    "control_port": int,    # Port for control messages
224
    "hb_port": int,         # Port for heartbeat
225
    "ip": str,              # IP address for connections
226
    "key": str,             # HMAC key (base64 encoded)
227
    "transport": str,       # Transport protocol ('tcp' or 'ipc')
228
    "signature_scheme": str, # Message signature scheme
229
    "kernel_name": str      # Kernel identifier
230
}
231
```