##// END OF EJS Templates
Fixing missing metaclass in KernelManagerABC.
Brian Granger -
Show More
@@ -1,399 +1,401 b''
1 1 """Abstract base classes for kernel manager and channels."""
2 2
3 3 #-----------------------------------------------------------------------------
4 4 # Copyright (C) 2013 The IPython Development Team
5 5 #
6 6 # Distributed under the terms of the BSD License. The full license is in
7 7 # the file COPYING, distributed as part of this software.
8 8 #-----------------------------------------------------------------------------
9 9
10 10 #-----------------------------------------------------------------------------
11 11 # Imports
12 12 #-----------------------------------------------------------------------------
13 13
14 14 # Standard library imports.
15 15 import abc
16 16
17 17 #-----------------------------------------------------------------------------
18 18 # Channels
19 19 #-----------------------------------------------------------------------------
20 20
21 21
22 22 class ChannelABC(object):
23 23 """A base class for all channel ABCs."""
24 24
25 25 __metaclass__ = abc.ABCMeta
26 26
27 27 @abc.abstractmethod
28 28 def start(self):
29 29 pass
30 30
31 31 @abc.abstractmethod
32 32 def stop(self):
33 33 pass
34 34
35 35 @abc.abstractmethod
36 36 def is_alive(self):
37 37 pass
38 38
39 39
40 40 class ShellChannelABC(ChannelABC):
41 41 """The DEALER channel for issues request/replies to the kernel.
42 42 """
43 43
44 44 @abc.abstractproperty
45 45 def allow_stdin(self):
46 46 pass
47 47
48 48 @abc.abstractmethod
49 49 def execute(self, code, silent=False, store_history=True,
50 50 user_variables=None, user_expressions=None, allow_stdin=None):
51 51 """Execute code in the kernel.
52 52
53 53 Parameters
54 54 ----------
55 55 code : str
56 56 A string of Python code.
57 57
58 58 silent : bool, optional (default False)
59 59 If set, the kernel will execute the code as quietly possible, and
60 60 will force store_history to be False.
61 61
62 62 store_history : bool, optional (default True)
63 63 If set, the kernel will store command history. This is forced
64 64 to be False if silent is True.
65 65
66 66 user_variables : list, optional
67 67 A list of variable names to pull from the user's namespace. They
68 68 will come back as a dict with these names as keys and their
69 69 :func:`repr` as values.
70 70
71 71 user_expressions : dict, optional
72 72 A dict mapping names to expressions to be evaluated in the user's
73 73 dict. The expression values are returned as strings formatted using
74 74 :func:`repr`.
75 75
76 76 allow_stdin : bool, optional (default self.allow_stdin)
77 77 Flag for whether the kernel can send stdin requests to frontends.
78 78
79 79 Some frontends (e.g. the Notebook) do not support stdin requests.
80 80 If raw_input is called from code executed from such a frontend, a
81 81 StdinNotImplementedError will be raised.
82 82
83 83 Returns
84 84 -------
85 85 The msg_id of the message sent.
86 86 """
87 87 pass
88 88
89 89 @abc.abstractmethod
90 90 def complete(self, text, line, cursor_pos, block=None):
91 91 """Tab complete text in the kernel's namespace.
92 92
93 93 Parameters
94 94 ----------
95 95 text : str
96 96 The text to complete.
97 97 line : str
98 98 The full line of text that is the surrounding context for the
99 99 text to complete.
100 100 cursor_pos : int
101 101 The position of the cursor in the line where the completion was
102 102 requested.
103 103 block : str, optional
104 104 The full block of code in which the completion is being requested.
105 105
106 106 Returns
107 107 -------
108 108 The msg_id of the message sent.
109 109 """
110 110 pass
111 111
112 112 @abc.abstractmethod
113 113 def object_info(self, oname, detail_level=0):
114 114 """Get metadata information about an object.
115 115
116 116 Parameters
117 117 ----------
118 118 oname : str
119 119 A string specifying the object name.
120 120 detail_level : int, optional
121 121 The level of detail for the introspection (0-2)
122 122
123 123 Returns
124 124 -------
125 125 The msg_id of the message sent.
126 126 """
127 127 pass
128 128
129 129 @abc.abstractmethod
130 130 def history(self, raw=True, output=False, hist_access_type='range', **kwargs):
131 131 """Get entries from the history list.
132 132
133 133 Parameters
134 134 ----------
135 135 raw : bool
136 136 If True, return the raw input.
137 137 output : bool
138 138 If True, then return the output as well.
139 139 hist_access_type : str
140 140 'range' (fill in session, start and stop params), 'tail' (fill in n)
141 141 or 'search' (fill in pattern param).
142 142
143 143 session : int
144 144 For a range request, the session from which to get lines. Session
145 145 numbers are positive integers; negative ones count back from the
146 146 current session.
147 147 start : int
148 148 The first line number of a history range.
149 149 stop : int
150 150 The final (excluded) line number of a history range.
151 151
152 152 n : int
153 153 The number of lines of history to get for a tail request.
154 154
155 155 pattern : str
156 156 The glob-syntax pattern for a search request.
157 157
158 158 Returns
159 159 -------
160 160 The msg_id of the message sent.
161 161 """
162 162 pass
163 163
164 164 @abc.abstractmethod
165 165 def kernel_info(self):
166 166 """Request kernel info."""
167 167 pass
168 168
169 169 @abc.abstractmethod
170 170 def shutdown(self, restart=False):
171 171 """Request an immediate kernel shutdown.
172 172
173 173 Upon receipt of the (empty) reply, client code can safely assume that
174 174 the kernel has shut down and it's safe to forcefully terminate it if
175 175 it's still alive.
176 176
177 177 The kernel will send the reply via a function registered with Python's
178 178 atexit module, ensuring it's truly done as the kernel is done with all
179 179 normal operation.
180 180 """
181 181 pass
182 182
183 183
184 184 class IOPubChannelABC(ChannelABC):
185 185 """The SUB channel which listens for messages that the kernel publishes."""
186 186
187 187
188 188 @abc.abstractmethod
189 189 def flush(self, timeout=1.0):
190 190 """Immediately processes all pending messages on the SUB channel.
191 191
192 192 Callers should use this method to ensure that :method:`call_handlers`
193 193 has been called for all messages that have been received on the
194 194 0MQ SUB socket of this channel.
195 195
196 196 This method is thread safe.
197 197
198 198 Parameters
199 199 ----------
200 200 timeout : float, optional
201 201 The maximum amount of time to spend flushing, in seconds. The
202 202 default is one second.
203 203 """
204 204 pass
205 205
206 206
207 207 class StdInChannelABC(ChannelABC):
208 208 """A reply channel to handle raw_input requests that the kernel makes."""
209 209
210 210 @abc.abstractmethod
211 211 def input(self, string):
212 212 """Send a string of raw input to the kernel."""
213 213 pass
214 214
215 215
216 216 class HBChannelABC(ChannelABC):
217 217 """The heartbeat channel which monitors the kernel heartbeat."""
218 218
219 219 @abc.abstractproperty
220 220 def time_to_dead(self):
221 221 pass
222 222
223 223 @abc.abstractmethod
224 224 def pause(self):
225 225 """Pause the heartbeat."""
226 226 pass
227 227
228 228 @abc.abstractmethod
229 229 def unpause(self):
230 230 """Unpause the heartbeat."""
231 231 pass
232 232
233 233 @abc.abstractmethod
234 234 def is_beating(self):
235 235 """Is the heartbeat running and responsive (and not paused)."""
236 236 pass
237 237
238 238
239 239 #-----------------------------------------------------------------------------
240 240 # Main kernel manager class
241 241 #-----------------------------------------------------------------------------
242 242
243 243 class KernelManagerABC(object):
244 244 """ Manages a kernel for a frontend."""
245 245
246 __metaclass__ = abc.ABCMeta
247
246 248 @abc.abstractproperty
247 249 def kernel(self):
248 250 pass
249 251
250 252 @abc.abstractproperty
251 253 def shell_channel_class(self):
252 254 pass
253 255
254 256 @abc.abstractproperty
255 257 def iopub_channel_class(self):
256 258 pass
257 259
258 260 @abc.abstractproperty
259 261 def hb_channel_class(self):
260 262 pass
261 263
262 264 @abc.abstractproperty
263 265 def stdin_channel_class(self):
264 266 pass
265 267
266 268 #--------------------------------------------------------------------------
267 269 # Channel management methods:
268 270 #--------------------------------------------------------------------------
269 271
270 272 @abc.abstractmethod
271 273 def start_channels(self, shell=True, iopub=True, stdin=True, hb=True):
272 274 """Starts the channels for this kernel.
273 275
274 276 This will create the channels if they do not exist and then start
275 277 them. If port numbers of 0 are being used (random ports) then you
276 278 must first call :method:`start_kernel`. If the channels have been
277 279 stopped and you call this, :class:`RuntimeError` will be raised.
278 280 """
279 281 pass
280 282
281 283 @abc.abstractmethod
282 284 def stop_channels(self):
283 285 """Stops all the running channels for this kernel."""
284 286 pass
285 287
286 288 @abc.abstractproperty
287 289 def channels_running(self):
288 290 """Are any of the channels created and running?"""
289 291 pass
290 292
291 293 @abc.abstractproperty
292 294 def shell_channel(self):
293 295 """Get the REQ socket channel object to make requests of the kernel."""
294 296 pass
295 297
296 298 @abc.abstractproperty
297 299 def iopub_channel(self):
298 300 """Get the SUB socket channel object."""
299 301 pass
300 302
301 303 @abc.abstractproperty
302 304 def stdin_channel(self):
303 305 """Get the REP socket channel object to handle stdin (raw_input)."""
304 306 pass
305 307
306 308 @abc.abstractproperty
307 309 def hb_channel(self):
308 310 """Get the heartbeat socket channel object to check that the
309 311 kernel is alive."""
310 312 pass
311 313
312 314 #--------------------------------------------------------------------------
313 315 # Kernel management.
314 316 #--------------------------------------------------------------------------
315 317
316 318 @abc.abstractmethod
317 319 def start_kernel(self, **kw):
318 320 """Starts a kernel process and configures the manager to use it.
319 321
320 322 If random ports (port=0) are being used, this method must be called
321 323 before the channels are created.
322 324
323 325 Parameters:
324 326 -----------
325 327 launcher : callable, optional (default None)
326 328 A custom function for launching the kernel process (generally a
327 329 wrapper around ``entry_point.base_launch_kernel``). In most cases,
328 330 it should not be necessary to use this parameter.
329 331
330 332 **kw : optional
331 333 See respective options for IPython and Python kernels.
332 334 """
333 335 pass
334 336
335 337 @abc.abstractmethod
336 338 def shutdown_kernel(self, now=False, restart=False):
337 339 """ Attempts to the stop the kernel process cleanly."""
338 340 pass
339 341
340 342 @abc.abstractmethod
341 343 def restart_kernel(self, now=False, **kw):
342 344 """Restarts a kernel with the arguments that were used to launch it.
343 345
344 346 If the old kernel was launched with random ports, the same ports will be
345 347 used for the new kernel.
346 348
347 349 Parameters
348 350 ----------
349 351 now : bool, optional
350 352 If True, the kernel is forcefully restarted *immediately*, without
351 353 having a chance to do any cleanup action. Otherwise the kernel is
352 354 given 1s to clean up before a forceful restart is issued.
353 355
354 356 In all cases the kernel is restarted, the only difference is whether
355 357 it is given a chance to perform a clean shutdown or not.
356 358
357 359 **kw : optional
358 360 Any options specified here will replace those used to launch the
359 361 kernel.
360 362 """
361 363 pass
362 364
363 365 @abc.abstractproperty
364 366 def has_kernel(self):
365 367 """Returns whether a kernel process has been specified for the kernel
366 368 manager.
367 369 """
368 370 pass
369 371
370 372 @abc.abstractmethod
371 373 def kill_kernel(self):
372 374 """ Kill the running kernel.
373 375
374 376 This method blocks until the kernel process has terminated.
375 377 """
376 378 pass
377 379
378 380 @abc.abstractmethod
379 381 def interrupt_kernel(self):
380 382 """ Interrupts the kernel.
381 383
382 384 Unlike ``signal_kernel``, this operation is well supported on all
383 385 platforms.
384 386 """
385 387 pass
386 388
387 389 @abc.abstractmethod
388 390 def signal_kernel(self, signum):
389 391 """ Sends a signal to the kernel.
390 392
391 393 Note that since only SIGTERM is supported on Windows, this function is
392 394 only useful on Unix systems.
393 395 """
394 396 pass
395 397
396 398 @abc.abstractproperty
397 399 def is_alive(self):
398 400 """Is the kernel process still running?"""
399 401 pass
General Comments 0
You need to be logged in to leave comments. Login now