diff --git a/IPython/inprocess/kernelmanager.py b/IPython/inprocess/kernelmanager.py index 74f1936..4776e32 100644 --- a/IPython/inprocess/kernelmanager.py +++ b/IPython/inprocess/kernelmanager.py @@ -26,8 +26,7 @@ from IPython.zmq.kernelmanagerabc import ( #----------------------------------------------------------------------------- class InProcessChannel(object): - """ Base class for in-process channels. - """ + """Base class for in-process channels.""" def __init__(self, manager): super(InProcessChannel, self).__init__() @@ -77,8 +76,7 @@ class InProcessChannel(object): class InProcessShellChannel(InProcessChannel): - """The DEALER channel for issues request/replies to the kernel. - """ + """See `IPython.zmq.kernelmanager.ShellChannel` for docstrings.""" # flag for whether execute requests should be allowed to call raw_input allow_stdin = True @@ -89,42 +87,6 @@ class InProcessShellChannel(InProcessChannel): def execute(self, code, silent=False, store_history=True, user_variables=[], user_expressions={}, 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. - """ if allow_stdin is None: allow_stdin = self.allow_stdin content = dict(code=code, silent=silent, store_history=store_history, @@ -136,81 +98,18 @@ class InProcessShellChannel(InProcessChannel): return msg['header']['msg_id'] 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. - """ content = dict(text=text, line=line, block=block, cursor_pos=cursor_pos) msg = self.manager.session.msg('complete_request', content) self._dispatch_to_kernel(msg) return msg['header']['msg_id'] 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. - """ content = dict(oname=oname, detail_level=detail_level) msg = self.manager.session.msg('object_info_request', content) self._dispatch_to_kernel(msg) return msg['header']['msg_id'] def history(self, raw=True, output=False, hist_access_type='range', **kwds): - """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. - """ content = dict(raw=raw, output=output, hist_access_type=hist_access_type, **kwds) msg = self.manager.session.msg('history_request', content) @@ -218,10 +117,6 @@ class InProcessShellChannel(InProcessChannel): return msg['header']['msg_id'] def shutdown(self, restart=False): - """ Request an immediate kernel shutdown. - - A dummy method for the in-process kernel. - """ # FIXME: What to do here? raise NotImplementedError('Cannot shutdown in-process kernel') @@ -246,23 +141,16 @@ class InProcessShellChannel(InProcessChannel): class InProcessIOPubChannel(InProcessChannel): - """The SUB channel which listens for messages that the kernel publishes. - """ + """See `IPython.zmq.kernelmanager.IOPubChannel` for docstrings.""" def flush(self, timeout=1.0): - """ Immediately processes all pending messages on the SUB channel. - - A dummy method for the in-process kernel. - """ pass class InProcessStdInChannel(InProcessChannel): - """ A reply channel to handle raw_input requests that the kernel makes. """ + """See `IPython.zmq.kernelmanager.StdInChannel` for docstrings.""" def input(self, string): - """ Send a string of raw input to the kernel. - """ kernel = self.manager.kernel if kernel is None: raise RuntimeError('Cannot send input reply. No kernel exists.') @@ -270,7 +158,7 @@ class InProcessStdInChannel(InProcessChannel): class InProcessHBChannel(InProcessChannel): - """ A dummy heartbeat channel. """ + """See `IPython.zmq.kernelmanager.HBChannel` for docstrings.""" time_to_dead = 3.0 @@ -279,15 +167,12 @@ class InProcessHBChannel(InProcessChannel): self._pause = True def pause(self): - """ Pause the heartbeat. """ self._pause = True def unpause(self): - """ Unpause the heartbeat. """ self._pause = False def is_beating(self): - """ Is the heartbeat running and responsive (and not paused). """ return not self._pause @@ -296,11 +181,13 @@ class InProcessHBChannel(InProcessChannel): #----------------------------------------------------------------------------- class InProcessKernelManager(Configurable): - """ A manager for an in-process kernel. + """A manager for an in-process kernel. - This class implements most of the interface of - ``IPython.zmq.kernelmanager.KernelManager`` and allows (asynchronous) - frontends to be used seamlessly with an in-process kernel. + This class implements the interface of + `IPython.zmq.kernelmanagerabc.KernelManagerABC` and allows + (asynchronous) frontends to be used seamlessly with an in-process kernel. + + See `IPython.zmq.kernelmanager.KernelManager` for docstrings. """ # The Session to use for building messages. @@ -329,8 +216,6 @@ class InProcessKernelManager(Configurable): #-------------------------------------------------------------------------- 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 iopub: @@ -344,8 +229,6 @@ class InProcessKernelManager(Configurable): self.hb_channel.start() def stop_channels(self): - """ Stops all the running channels for this kernel. - """ if self.shell_channel.is_alive(): self.shell_channel.stop() if self.iopub_channel.is_alive(): @@ -357,35 +240,29 @@ class InProcessKernelManager(Configurable): @property def channels_running(self): - """ Are any of the channels created and running? """ 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 @@ -395,50 +272,33 @@ class InProcessKernelManager(Configurable): #-------------------------------------------------------------------------- def start_kernel(self, **kwds): - """ Starts a kernel process and configures the manager to use it. - """ from IPython.inprocess.ipkernel import InProcessKernel self.kernel = InProcessKernel() self.kernel.frontends.append(self) def shutdown_kernel(self): - """ Attempts to the stop the kernel process cleanly. If the kernel - cannot be stopped and the kernel is local, it is killed. - """ self.kill_kernel() def restart_kernel(self, now=False, **kwds): - """ Restarts a kernel with the arguments that were used to launch it. - - The 'now' parameter is ignored. - """ self.shutdown_kernel() self.start_kernel(**kwds) @property def has_kernel(self): - """ Returns whether a kernel process has been specified for the kernel - manager. - """ return self.kernel is not None def kill_kernel(self): - """ Kill the running kernel. - """ self.kernel.frontends.remove(self) self.kernel = None def interrupt_kernel(self): - """ Interrupts the kernel. """ raise NotImplementedError("Cannot interrupt in-process kernel.") def signal_kernel(self, signum): - """ Sends a signal to the kernel. """ raise NotImplementedError("Cannot signal in-process kernel.") @property def is_alive(self): - """ Is the kernel process still running? """ return True diff --git a/IPython/zmq/kernelmanagerabc.py b/IPython/zmq/kernelmanagerabc.py index d05ac44..280dd33 100644 --- a/IPython/zmq/kernelmanagerabc.py +++ b/IPython/zmq/kernelmanagerabc.py @@ -38,7 +38,11 @@ class ChannelABC(object): class ShellChannelABC(ChannelABC): - """The DEALER channel for issues request/replies to the kernel. + """ShellChannel ABC. + + The docstrings for this class can be found in the base implementation: + + `IPython.zmq.kernelmanager.ShellChannel` """ @abc.abstractproperty @@ -48,173 +52,62 @@ class ShellChannelABC(ChannelABC): @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.""" + """IOPubChannel ABC. + + The docstrings for this class can be found in the base implementation: + `IPython.zmq.kernelmanager.IOPubChannel` + """ @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.""" + """StdInChannel ABC. + + The docstrings for this class can be found in the base implementation: + + `IPython.zmq.kernelmanager.StdInChannel` + """ @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.""" + """HBChannel ABC. + + The docstrings for this class can be found in the base implementation: + + `IPython.zmq.kernelmanager.HBChannel` + """ @abc.abstractproperty def time_to_dead(self): @@ -222,17 +115,14 @@ class HBChannelABC(ChannelABC): @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 @@ -241,7 +131,12 @@ class HBChannelABC(ChannelABC): #----------------------------------------------------------------------------- class KernelManagerABC(object): - """ Manages a kernel for a frontend.""" + """KernelManager ABC. + + The docstrings for this class can be found in the base implementation: + + `IPython.zmq.kernelmanager.KernelManager` + """ __metaclass__ = abc.ABCMeta @@ -271,44 +166,30 @@ class KernelManagerABC(object): @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 #-------------------------------------------------------------------------- @@ -317,85 +198,32 @@ class KernelManagerABC(object): @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