Merge pull request #10881 from JeremySikes73/doc

Add notes to doc section on event loop integration

docs/source/config/callbacks.rst

@@ -1,99 +1,99 b''
 .. _events:
 .. _callbacks:
 
 ==============
 IPython Events
 ==============
 
 Extension code can register callbacks functions which will be called on specific
 events within the IPython code. You can see the current list of available
 callbacks, and the parameters that will be passed with each, in the callback
-prototype functions defined in :mod:`IPython.core.callbacks`.
+prototype functions defined in :mod:`IPython.core.events`.
 
 To register callbacks, use :meth:`IPython.core.events.EventManager.register`.
 For example::
 
     class VarWatcher(object):
         def __init__(self, ip):
             self.shell = ip
             self.last_x = None
         
         def pre_execute(self):
             self.last_x = self.shell.user_ns.get('x', None)
         
         def pre_run_cell(self, info):
             print('Cell code: "%s"' % info.raw_cell)
         
         def post_execute(self):
             if self.shell.user_ns.get('x', None) != self.last_x:
                 print("x changed!")
         
         def post_run_cell(self, result):
             print('Cell code: "%s"' % result.info.raw_cell)
             if result.error_before_exec:
                 print('Error before execution: %s' % result.error_before_exec)
         
     def load_ipython_extension(ip):
         vw = VarWatcher(ip)
         ip.events.register('pre_execute', vw.pre_execute)
         ip.events.register('pre_run_cell', vw.pre_run_cell)
         ip.events.register('post_execute', vw.post_execute)
         ip.events.register('post_run_cell', vw.post_run_cell)
 
 
 Events
 ======
 
 These are the events IPython will emit. Callbacks will be passed no arguments, unless otherwise specified.
 
 shell_initialized
 -----------------
 
 .. code-block:: python
 
     def shell_initialized(ipython):
         ...
 
 This event is triggered only once, at the end of setting up IPython.
 Extensions registered to load by default as part of configuration can use this to execute code to finalize setup.
 Callbacks will be passed the InteractiveShell instance.
 
 pre_run_cell
 ------------
 
 ``pre_run_cell`` fires prior to interactive execution (e.g. a cell in a notebook).
 It can be used to note the state prior to execution, and keep track of changes.
 An object containing information used for the code execution is provided as an argument.
 
 pre_execute
 -----------
 
 ``pre_execute`` is like ``pre_run_cell``, but is triggered prior to *any* execution.
 Sometimes code can be executed by libraries, etc. which
 skipping the history/display mechanisms, in which cases ``pre_run_cell`` will not fire.
 
 post_run_cell
 -------------
 
 ``post_run_cell`` runs after interactive execution (e.g. a cell in a notebook).
 It can be used to cleanup or notify or perform operations on any side effects produced during execution.
 For instance, the inline matplotlib backend uses this event to display any figures created but not explicitly displayed during the course of the cell.
 The object which will be returned as the execution result is provided as an
 argument.
 
 post_execute
 ------------
 
 The same as ``pre_execute``, ``post_execute`` is like ``post_run_cell``,
 but fires for *all* executions, not just interactive ones.
 
 
 .. seealso::
 
    Module :mod:`IPython.core.hooks`
      The older 'hooks' system allows end users to customise some parts of
      IPython's behaviour.
    
    :doc:`inputtransforms`
      By registering input transformers that don't change code, you can monitor
      what is being executed.

docs/source/config/eventloops.rst

@@ -1,95 +1,108 b''
 ================================
 Integrating with GUI event loops
 ================================
 
 When the user types ``%gui qt``, IPython integrates itself with the Qt event
 loop, so you can use both a GUI and an interactive prompt together. IPython
 supports a number of common GUI toolkits, but from IPython 3.0, it is possible
 to integrate other event loops without modifying IPython itself.
 
-Terminal IPython handles event loops very differently from the IPython kernel,
-so different steps are needed to integrate with each.
+Supported event loops include ``qt4``, ``qt5``, ``gtk2``, ``gtk3``, ``wx``,
+``osx`` and ``tk``. Make sure the event loop you specify matches the GUI
+toolkit used by your own code.
 
-Event loops in the terminal
----------------------------
+To make IPython GUI event loop integration occur automatically at every
+startup, set the ``c.InteractiveShellApp.gui`` configuration key in your
+IPython profile (see :ref:`setting_config`).
+
+If the event loop you use is supported by IPython, turning on event loop
+integration follows the steps just described whether you use Terminal IPython
+or an IPython kernel.
+
+However, the way Terminal IPython handles event loops is very different from
+the way IPython kernel does, so if you need to integrate with a new kind of
+event loop, different steps are needed to integrate with each.
+
+Integrating with a new event loop in the terminal
+-------------------------------------------------
 
 .. versionchanged:: 5.0
 
    There is a new API for event loop integration using prompt_toolkit.
 
 In the terminal, IPython uses prompt_toolkit to prompt the user for input.
 prompt_toolkit provides hooks to integrate with an external event loop.
 
 To integrate an event loop, define a function which runs the GUI event loop
 until there is input waiting for prompt_toolkit to process. There are two ways
 to detect this condition::
 
     # Polling for input.
     def inputhook(context):
         while not context.input_is_ready():
             # Replace this with the appropriate call for the event loop:
             iterate_loop_once()
 
     # Using a file descriptor to notify the event loop to stop.
     def inputhook2(context):
         fd = context.fileno()
         # Replace the functions below with those for the event loop.
         add_file_reader(fd, callback=stop_the_loop)
         run_the_loop()
 
 Once you have defined this function, register it with IPython:
 
 .. currentmodule:: IPython.terminal.pt_inputhooks
 
 .. function:: register(name, inputhook)
 
    Register the function *inputhook* as the event loop integration for the
    GUI *name*. If ``name='foo'``, then the user can enable this integration
    by running ``%gui foo``.
 
 
-Event loops in the kernel
--------------------------
+Integrating with a new event loop in the kernel
+-----------------------------------------------
 
 The kernel runs its own event loop, so it's simpler to integrate with others.
 IPython allows the other event loop to take control, but it must call
 :meth:`IPython.kernel.zmq.kernelbase.Kernel.do_one_iteration` periodically.
 
 To integrate with this, write a function that takes a single argument,
 the IPython kernel instance, arranges for your event loop to call
 ``kernel.do_one_iteration()`` at least every ``kernel._poll_interval`` seconds,
 and starts the event loop.
 
 Decorate this function with :func:`IPython.kernel.zmq.eventloops.register_integration`,
 passing in the names you wish to register it for. Here is a slightly simplified
 version of the Tkinter integration already included in IPython::
 
     @register_integration('tk')
     def loop_tk(kernel):
         """Start a kernel with the Tk event loop."""
         from tkinter import Tk
 
         # Tk uses milliseconds
         poll_interval = int(1000*kernel._poll_interval)
         # For Tkinter, we create a Tk object and call its withdraw method.
         class Timer(object):
             def __init__(self, func):
                 self.app = Tk()
                 self.app.withdraw()
                 self.func = func
 
             def on_timer(self):
                 self.func()
                 self.app.after(poll_interval, self.on_timer)
 
             def start(self):
                 self.on_timer()  # Call it once to get things going.
                 self.app.mainloop()
 
         kernel.timer = Timer(kernel.do_one_iteration)
         kernel.timer.start()
 
 Some event loops can go one better, and integrate checking for messages on the
 kernel's ZMQ sockets, making the kernel more responsive than plain polling. How
 to do this is outside the scope of this document; if you are interested, look at
 the integration with Qt in :mod:`IPython.kernel.zmq.eventloops`.