From b96d9ca9073b232a1b703342a9eec8216868df8c 2013-01-16 22:53:34 From: Brian Granger Date: 2013-01-16 22:53:34 Subject: [PATCH] Creating an ABC for kernel managers and channels. --- diff --git a/IPython/frontend/html/notebook/kernelmanager.py b/IPython/frontend/html/notebook/kernelmanager.py index 1bfae33..6828f17 100644 --- a/IPython/frontend/html/notebook/kernelmanager.py +++ b/IPython/frontend/html/notebook/kernelmanager.py @@ -17,8 +17,6 @@ Authors: #----------------------------------------------------------------------------- import os -import signal -import sys import uuid import zmq @@ -94,7 +92,7 @@ class MultiKernelManager(LoggingConfigurable): ) km.start_kernel(**kwargs) # start just the shell channel, needed for graceful restart - km.start_channels(shell=True, sub=False, stdin=False, hb=False) + km.start_channels(shell=True, iopub=False, stdin=False, hb=False) self._kernels[kernel_id] = km return kernel_id diff --git a/IPython/inprocess/blockingkernelmanager.py b/IPython/inprocess/blockingkernelmanager.py index e9dc184..38a2a08 100644 --- a/IPython/inprocess/blockingkernelmanager.py +++ b/IPython/inprocess/blockingkernelmanager.py @@ -14,10 +14,6 @@ Useful for test suites and blocking terminal interfaces. #----------------------------------------------------------------------------- from __future__ import print_function -# Standard library imports. -import Queue -from threading import Event - # Local imports. from IPython.utils.io import raw_print from IPython.utils.traitlets import Type diff --git a/IPython/inprocess/kernelmanager.py b/IPython/inprocess/kernelmanager.py index 77b525f..f5137a8 100644 --- a/IPython/inprocess/kernelmanager.py +++ b/IPython/inprocess/kernelmanager.py @@ -15,6 +15,11 @@ from IPython.config.loader import Config from IPython.inprocess.socket import DummySocket from IPython.utils.traitlets import HasTraits, Any, Instance, Type +from IPython.zmq.kernelmanagerabc import ( + ShellChannelABC, IOPubChannelABC, + HBChannelABC, StdInChannelABC, + KernelManagerABC +) #----------------------------------------------------------------------------- # Channel classes @@ -322,15 +327,15 @@ class InProcessKernelManager(HasTraits): _hb_channel = Any #-------------------------------------------------------------------------- - # Channel management methods: + # Channel management methods. #-------------------------------------------------------------------------- - def start_channels(self, shell=True, sub=True, stdin=True, hb=True): + def start_channels(self, shell=True, iopub=True, stdin=True, hb=True): """ Starts the channels for this kernel. """ if shell: self.shell_channel.start() - if sub: + if iopub: self.iopub_channel.start() if stdin: self.stdin_channel.start() @@ -358,6 +363,35 @@ class InProcessKernelManager(HasTraits): return (self.shell_channel.is_alive() or self.iopub_channel.is_alive() or self.stdin_channel.is_alive() or self.hb_channel.is_alive()) + @property + def shell_channel(self): + """Get the REQ socket channel object to make requests of the kernel.""" + if self._shell_channel is None: + self._shell_channel = self.shell_channel_class(self) + return self._shell_channel + + @property + def iopub_channel(self): + """Get the SUB socket channel object.""" + if self._iopub_channel is None: + self._iopub_channel = self.iopub_channel_class(self) + return self._iopub_channel + + @property + def stdin_channel(self): + """Get the REP socket channel object to handle stdin (raw_input).""" + if self._stdin_channel is None: + self._stdin_channel = self.stdin_channel_class(self) + return self._stdin_channel + + @property + def hb_channel(self): + """Get the heartbeat socket channel object to check that the + kernel is alive.""" + if self._hb_channel is None: + self._hb_channel = self.hb_channel_class(self) + return self._hb_channel + #-------------------------------------------------------------------------- # Kernel management methods: #-------------------------------------------------------------------------- @@ -409,35 +443,13 @@ class InProcessKernelManager(HasTraits): """ Is the kernel process still running? """ return True - #-------------------------------------------------------------------------- - # Channels used for communication with the kernel: - #-------------------------------------------------------------------------- - - @property - def shell_channel(self): - """Get the REQ socket channel object to make requests of the kernel.""" - if self._shell_channel is None: - self._shell_channel = self.shell_channel_class(self) - return self._shell_channel - - @property - def iopub_channel(self): - """Get the SUB socket channel object.""" - if self._iopub_channel is None: - self._iopub_channel = self.iopub_channel_class(self) - return self._iopub_channel - @property - def stdin_channel(self): - """Get the REP socket channel object to handle stdin (raw_input).""" - if self._stdin_channel is None: - self._stdin_channel = self.stdin_channel_class(self) - return self._stdin_channel +#----------------------------------------------------------------------------- +# ABC Registration +#----------------------------------------------------------------------------- - @property - def hb_channel(self): - """Get the heartbeat socket channel object to check that the - kernel is alive.""" - if self._hb_channel is None: - self._hb_channel = self.hb_channel_class(self) - return self._hb_channel +ShellChannelABC.register(InProcessShellChannel) +IOPubChannelABC.register(InProcessIOPubChannel) +HBChannelABC.register(InProcessHBChannel) +StdInChannelABC.register(InProcessStdInChannel) +KernelManagerABC.register(InProcessKernelManager) diff --git a/IPython/zmq/blockingkernelmanager.py b/IPython/zmq/blockingkernelmanager.py index 6b53697..69aac2f 100644 --- a/IPython/zmq/blockingkernelmanager.py +++ b/IPython/zmq/blockingkernelmanager.py @@ -13,6 +13,8 @@ Useful for test suites and blocking terminal interfaces. # Imports #----------------------------------------------------------------------------- +import Queue + from IPython.utils.traitlets import Type from kernelmanager import KernelManager, IOPubChannel, HBChannel, \ ShellChannel, StdInChannel @@ -81,4 +83,4 @@ class BlockingKernelManager(KernelManager): iopub_channel_class = Type(BlockingIOPubChannel) stdin_channel_class = Type(BlockingStdInChannel) hb_channel_class = Type(BlockingHBChannel) - + diff --git a/IPython/zmq/kernelmanager.py b/IPython/zmq/kernelmanager.py index 00d3ed0..10a6ceb 100644 --- a/IPython/zmq/kernelmanager.py +++ b/IPython/zmq/kernelmanager.py @@ -34,15 +34,20 @@ from zmq import ZMQError from zmq.eventloop import ioloop, zmqstream # Local imports. -from IPython.config.loader import Config from IPython.config.configurable import Configurable from IPython.utils.localinterfaces import LOCALHOST, LOCAL_IPS from IPython.utils.traitlets import ( - HasTraits, Any, Instance, Type, Unicode, Integer, Bool, CaselessStrEnum + Any, Instance, Type, Unicode, Integer, Bool, CaselessStrEnum ) from IPython.utils.py3compat import str_to_bytes from IPython.zmq.entry_point import write_connection_file from session import Session +from IPython.zmq.kernelmanagerabc import ( + ShellChannelABC, IOPubChannelABC, + HBChannelABC, StdInChannelABC, + KernelManagerABC +) + #----------------------------------------------------------------------------- # Constants and exceptions @@ -698,7 +703,7 @@ class KernelManager(Configurable): # Channel management methods: #-------------------------------------------------------------------------- - def start_channels(self, shell=True, sub=True, stdin=True, hb=True): + def start_channels(self, shell=True, iopub=True, stdin=True, hb=True): """Starts the channels for this kernel. This will create the channels if they do not exist and then start @@ -708,7 +713,7 @@ class KernelManager(Configurable): """ if shell: self.shell_channel.start() - if sub: + if iopub: self.iopub_channel.start() if stdin: self.stdin_channel.start() @@ -736,8 +741,56 @@ class KernelManager(Configurable): return (self.shell_channel.is_alive() or self.iopub_channel.is_alive() or self.stdin_channel.is_alive() or self.hb_channel.is_alive()) + def _make_url(self, port): + """make a zmq url with a port""" + if self.transport == 'tcp': + return "tcp://%s:%i" % (self.ip, port) + else: + return "%s://%s-%s" % (self.transport, self.ip, port) + + @property + def shell_channel(self): + """Get the REQ socket channel object to make requests of the kernel.""" + if self._shell_channel is None: + self._shell_channel = self.shell_channel_class(self.context, + self.session, + self._make_url(self.shell_port), + ) + return self._shell_channel + + @property + def iopub_channel(self): + """Get the SUB socket channel object.""" + if self._iopub_channel is None: + self._iopub_channel = self.iopub_channel_class(self.context, + self.session, + self._make_url(self.iopub_port), + ) + return self._iopub_channel + + @property + def stdin_channel(self): + """Get the REP socket channel object to handle stdin (raw_input).""" + if self._stdin_channel is None: + self._stdin_channel = self.stdin_channel_class(self.context, + self.session, + self._make_url(self.stdin_port), + ) + return self._stdin_channel + + @property + def hb_channel(self): + """Get the heartbeat socket channel object to check that the + kernel is alive.""" + if self._hb_channel is None: + self._hb_channel = self.hb_channel_class(self.context, + self.session, + self._make_url(self.hb_port), + ) + return self._hb_channel + #-------------------------------------------------------------------------- - # Kernel process management methods: + # Connection and ipc file management. #-------------------------------------------------------------------------- def cleanup_connection_file(self): @@ -796,7 +849,11 @@ class KernelManager(Configurable): self.hb_port = cfg['hb_port'] self._connection_file_written = True - + + #-------------------------------------------------------------------------- + # Kernel management. + #-------------------------------------------------------------------------- + def start_kernel(self, **kw): """Starts a kernel process and configures the manager to use it. @@ -985,54 +1042,13 @@ class KernelManager(Configurable): # so naively return True return True - #-------------------------------------------------------------------------- - # Channels used for communication with the kernel: - #-------------------------------------------------------------------------- - - def _make_url(self, port): - """make a zmq url with a port""" - if self.transport == 'tcp': - return "tcp://%s:%i" % (self.ip, port) - else: - return "%s://%s-%s" % (self.transport, self.ip, port) - - @property - def shell_channel(self): - """Get the REQ socket channel object to make requests of the kernel.""" - if self._shell_channel is None: - self._shell_channel = self.shell_channel_class(self.context, - self.session, - self._make_url(self.shell_port), - ) - return self._shell_channel - - @property - def iopub_channel(self): - """Get the SUB socket channel object.""" - if self._iopub_channel is None: - self._iopub_channel = self.iopub_channel_class(self.context, - self.session, - self._make_url(self.iopub_port), - ) - return self._iopub_channel - @property - def stdin_channel(self): - """Get the REP socket channel object to handle stdin (raw_input).""" - if self._stdin_channel is None: - self._stdin_channel = self.stdin_channel_class(self.context, - self.session, - self._make_url(self.stdin_port), - ) - return self._stdin_channel +#----------------------------------------------------------------------------- +# ABC Registration +#----------------------------------------------------------------------------- - @property - def hb_channel(self): - """Get the heartbeat socket channel object to check that the - kernel is alive.""" - if self._hb_channel is None: - self._hb_channel = self.hb_channel_class(self.context, - self.session, - self._make_url(self.hb_port), - ) - return self._hb_channel +ShellChannelABC.register(ShellChannel) +IOPubChannelABC.register(IOPubChannel) +HBChannelABC.register(HBChannel) +StdInChannelABC.register(StdInChannel) +KernelManagerABC.register(KernelManager) diff --git a/IPython/zmq/kernelmanagerabc.py b/IPython/zmq/kernelmanagerabc.py new file mode 100644 index 0000000..a43266b --- /dev/null +++ b/IPython/zmq/kernelmanagerabc.py @@ -0,0 +1,399 @@ +"""Abstract base classes for kernel manager and channels.""" + +#----------------------------------------------------------------------------- +# Copyright (C) 2013 The IPython Development Team +# +# Distributed under the terms of the BSD License. The full license is in +# the file COPYING, distributed as part of this software. +#----------------------------------------------------------------------------- + +#----------------------------------------------------------------------------- +# Imports +#----------------------------------------------------------------------------- + +# Standard library imports. +import abc + +#----------------------------------------------------------------------------- +# Channels +#----------------------------------------------------------------------------- + + +class ChannelABC(object): + """A base class for all channel ABCs.""" + + __metaclass__ = abc.ABCMeta + + @abc.abstractmethod + def start(self): + pass + + @abc.abstractmethod + def stop(self): + pass + + @abc.abstractmethod + def is_alive(self): + pass + + +class ShellChannelABC(ChannelABC): + """The DEALER channel for issues request/replies to the kernel. + """ + + @abc.abstractproperty + def allow_stdin(self): + pass + + @abc.abstractmethod + def execute(self, code, silent=False, store_history=True, + user_variables=None, user_expressions=None, allow_stdin=None): + """Execute code in the kernel. + + Parameters + ---------- + code : str + A string of Python code. + + silent : bool, optional (default False) + If set, the kernel will execute the code as quietly possible, and + will force store_history to be False. + + store_history : bool, optional (default True) + If set, the kernel will store command history. This is forced + to be False if silent is True. + + user_variables : list, optional + A list of variable names to pull from the user's namespace. They + will come back as a dict with these names as keys and their + :func:`repr` as values. + + user_expressions : dict, optional + A dict mapping names to expressions to be evaluated in the user's + dict. The expression values are returned as strings formatted using + :func:`repr`. + + allow_stdin : bool, optional (default self.allow_stdin) + Flag for whether the kernel can send stdin requests to frontends. + + Some frontends (e.g. the Notebook) do not support stdin requests. + If raw_input is called from code executed from such a frontend, a + StdinNotImplementedError will be raised. + + Returns + ------- + The msg_id of the message sent. + """ + pass + + @abc.abstractmethod + def complete(self, text, line, cursor_pos, block=None): + """Tab complete text in the kernel's namespace. + + Parameters + ---------- + text : str + The text to complete. + line : str + The full line of text that is the surrounding context for the + text to complete. + cursor_pos : int + The position of the cursor in the line where the completion was + requested. + block : str, optional + The full block of code in which the completion is being requested. + + Returns + ------- + The msg_id of the message sent. + """ + pass + + @abc.abstractmethod + def object_info(self, oname, detail_level=0): + """Get metadata information about an object. + + Parameters + ---------- + oname : str + A string specifying the object name. + detail_level : int, optional + The level of detail for the introspection (0-2) + + Returns + ------- + The msg_id of the message sent. + """ + pass + + @abc.abstractmethod + def history(self, raw=True, output=False, hist_access_type='range', **kwargs): + """Get entries from the history list. + + Parameters + ---------- + raw : bool + If True, return the raw input. + output : bool + If True, then return the output as well. + hist_access_type : str + 'range' (fill in session, start and stop params), 'tail' (fill in n) + or 'search' (fill in pattern param). + + session : int + For a range request, the session from which to get lines. Session + numbers are positive integers; negative ones count back from the + current session. + start : int + The first line number of a history range. + stop : int + The final (excluded) line number of a history range. + + n : int + The number of lines of history to get for a tail request. + + pattern : str + The glob-syntax pattern for a search request. + + Returns + ------- + The msg_id of the message sent. + """ + pass + + @abc.abstractmethod + def kernel_info(self): + """Request kernel info.""" + pass + + @abc.abstractmethod + def shutdown(self, restart=False): + """Request an immediate kernel shutdown. + + Upon receipt of the (empty) reply, client code can safely assume that + the kernel has shut down and it's safe to forcefully terminate it if + it's still alive. + + The kernel will send the reply via a function registered with Python's + atexit module, ensuring it's truly done as the kernel is done with all + normal operation. + """ + pass + + +class IOPubChannelABC(ChannelABC): + """The SUB channel which listens for messages that the kernel publishes.""" + + + @abc.abstractmethod + def flush(self, timeout=1.0): + """Immediately processes all pending messages on the SUB channel. + + Callers should use this method to ensure that :method:`call_handlers` + has been called for all messages that have been received on the + 0MQ SUB socket of this channel. + + This method is thread safe. + + Parameters + ---------- + timeout : float, optional + The maximum amount of time to spend flushing, in seconds. The + default is one second. + """ + pass + + +class StdInChannelABC(ChannelABC): + """A reply channel to handle raw_input requests that the kernel makes.""" + + @abc.abstractmethod + def input(self, string): + """Send a string of raw input to the kernel.""" + pass + + +class HBChannelABC(ChannelABC): + """The heartbeat channel which monitors the kernel heartbeat.""" + + @abc.abstractproperty + def time_to_dead(self): + pass + + @abc.abstractmethod + def pause(self): + """Pause the heartbeat.""" + pass + + @abc.abstractmethod + def unpause(self): + """Unpause the heartbeat.""" + pass + + @abc.abstractmethod + def is_beating(self): + """Is the heartbeat running and responsive (and not paused).""" + pass + + +#----------------------------------------------------------------------------- +# Main kernel manager class +#----------------------------------------------------------------------------- + +class KernelManagerABC(object): + """ Manages a kernel for a frontend.""" + + @abc.abstractproperty + def kernel(self): + pass + + @abc.abstractproperty + def shell_channel_class(self): + pass + + @abc.abstractproperty + def iopub_channel_class(self): + pass + + @abc.abstractproperty + def hb_channel_class(self): + pass + + @abc.abstractproperty + def stdin_channel_class(self): + pass + + #-------------------------------------------------------------------------- + # Channel management methods: + #-------------------------------------------------------------------------- + + @abc.abstractmethod + def start_channels(self, shell=True, iopub=True, stdin=True, hb=True): + """Starts the channels for this kernel. + + This will create the channels if they do not exist and then start + them. If port numbers of 0 are being used (random ports) then you + must first call :method:`start_kernel`. If the channels have been + stopped and you call this, :class:`RuntimeError` will be raised. + """ + pass + + @abc.abstractmethod + def stop_channels(self): + """Stops all the running channels for this kernel.""" + pass + + @abc.abstractproperty + def channels_running(self): + """Are any of the channels created and running?""" + pass + + @abc.abstractproperty + def shell_channel(self): + """Get the REQ socket channel object to make requests of the kernel.""" + pass + + @abc.abstractproperty + def iopub_channel(self): + """Get the SUB socket channel object.""" + pass + + @abc.abstractproperty + def stdin_channel(self): + """Get the REP socket channel object to handle stdin (raw_input).""" + pass + + @abc.abstractproperty + def hb_channel(self): + """Get the heartbeat socket channel object to check that the + kernel is alive.""" + pass + + #-------------------------------------------------------------------------- + # Kernel management. + #-------------------------------------------------------------------------- + + @abc.abstractmethod + def start_kernel(self, **kw): + """Starts a kernel process and configures the manager to use it. + + If random ports (port=0) are being used, this method must be called + before the channels are created. + + Parameters: + ----------- + launcher : callable, optional (default None) + A custom function for launching the kernel process (generally a + wrapper around ``entry_point.base_launch_kernel``). In most cases, + it should not be necessary to use this parameter. + + **kw : optional + See respective options for IPython and Python kernels. + """ + pass + + @abc.abstractmethod + def shutdown_kernel(self, now=False, restart=False): + """ Attempts to the stop the kernel process cleanly.""" + pass + + @abc.abstractmethod + def restart_kernel(self, now=False, **kw): + """Restarts a kernel with the arguments that were used to launch it. + + If the old kernel was launched with random ports, the same ports will be + used for the new kernel. + + Parameters + ---------- + now : bool, optional + If True, the kernel is forcefully restarted *immediately*, without + having a chance to do any cleanup action. Otherwise the kernel is + given 1s to clean up before a forceful restart is issued. + + In all cases the kernel is restarted, the only difference is whether + it is given a chance to perform a clean shutdown or not. + + **kw : optional + Any options specified here will replace those used to launch the + kernel. + """ + pass + + @abc.abstractproperty + def has_kernel(self): + """Returns whether a kernel process has been specified for the kernel + manager. + """ + pass + + @abc.abstractmethod + def kill_kernel(self): + """ Kill the running kernel. + + This method blocks until the kernel process has terminated. + """ + pass + + @abc.abstractmethod + def interrupt_kernel(self): + """ Interrupts the kernel. + + Unlike ``signal_kernel``, this operation is well supported on all + platforms. + """ + pass + + @abc.abstractmethod + def signal_kernel(self, signum): + """ Sends a signal to the kernel. + + Note that since only SIGTERM is supported on Windows, this function is + only useful on Unix systems. + """ + pass + + @abc.abstractproperty + def is_alive(self): + """Is the kernel process still running?""" + pass