Add note about experimental API

IPython/core/events.py

@@ -1,129 +1,137 b''
 """Infrastructure for registering and firing callbacks on application events.
 
 Unlike :mod:`IPython.core.hooks`, which lets end users set single functions to
 be called at specific times, or a collection of alternative methods to try,
 callbacks are designed to be used by extension authors. A number of callbacks
 can be registered for the same event without needing to be aware of one another.
 
 The functions defined in this module are no-ops indicating the names of available
 events and the arguments which will be passed to them.
+
+.. note::
+
+   This API is experimental in IPython 2.0, and may be revised in future versions.
 """
 from __future__ import print_function
 
 class EventManager(object):
     """Manage a collection of events and a sequence of callbacks for each.
     
     This is attached to :class:`~IPython.core.interactiveshell.InteractiveShell`
     instances as a ``callbacks`` attribute.
+    
+    .. note::
+
+       This API is experimental in IPython 2.0, and may be revised in future versions.
     """
     def __init__(self, shell, available_events):
         """Initialise the :class:`CallbackManager`.
         
         Parameters
         ----------
         shell
           The :class:`~IPython.core.interactiveshell.InteractiveShell` instance
         available_callbacks
           An iterable of names for callback events.
         """
         self.shell = shell
         self.callbacks = {n:[] for n in available_events}
     
     def register(self, event, function):
         """Register a new callback
         
         Parameters
         ----------
         event : str
           The event for which to register this callback.
         function : callable
           A function to be called on the given event. It should take the same
           parameters as the appropriate callback prototype.
         
         Raises
         ------
         TypeError
           If ``function`` is not callable.
         KeyError
           If ``event`` is not one of the known events.
         """
         if not callable(function):
             raise TypeError('Need a callable, got %r' % function)
         self.callbacks[event].append(function)
     
     def unregister(self, event, function):
         """Remove a callback from the given event."""
         self.callbacks[event].remove(function)
     
     def reset(self, event):
         """Clear all callbacks for the given event."""
         self.callbacks[event] = []
     
     def reset_all(self):
         """Clear all callbacks for all events."""
         self.callbacks = {n:[] for n in self.callbacks}
     
     def trigger(self, event, *args, **kwargs):
         """Call callbacks for ``event``.
         
         Any additional arguments are passed to all callbacks registered for this
         event. Exceptions raised by callbacks are caught, and a message printed.
         """
         for func in self.callbacks[event]:
             try:
                 func(*args, **kwargs)
             except Exception:
                 print("Error in callback {} (for {}):".format(func, event))
                 self.shell.showtraceback()
 
 # event_name -> prototype mapping
 available_events = {}
 
 def _collect(callback_proto):
     available_events[callback_proto.__name__] = callback_proto
     return callback_proto
 
 # ------------------------------------------------------------------------------
 # Callback prototypes
 #
 # No-op functions which describe the names of available events and the
 # signatures of callbacks for those events.
 # ------------------------------------------------------------------------------
 
 @_collect
 def pre_execute():
     """Fires before code is executed in response to user/frontend action.
     
     This includes comm and widget messages as well as user code cells."""
     pass
 
 @_collect
 def pre_execute_explicit():
     """Fires before user-entered code runs."""
     pass
 
 @_collect
 def post_execute():
     """Fires after code is executed in response to user/frontend action.
     
     This includes comm and widget messages as well as user code cells."""
     pass
 
 @_collect
 def post_execute_explicit():
     """Fires after user-entered code runs."""
     pass
 
 @_collect
 def shell_initialised(ip):
     """Fires after initialisation of :class:`~IPython.core.interactiveshell.InteractiveShell`.
     
     This is before extensions and startup scripts are loaded, so it can only be
     set by subclassing.
     
     Parameters
     ----------
     ip : :class:`~IPython.core.interactiveshell.InteractiveShell`
       The newly initialised shell.
     """
     pass

docs/source/config/callbacks.rst

@@ -1,38 +1,42 b''
 =====================
 Registering callbacks
 =====================
 
 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`.
 
 To register callbacks, use :meth:`IPython.core.callbacks.CallbackManager.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 post_execute(self):
             if self.shell.user_ns.get('x', None) != self.last_x:
                 print("x changed!")
 
     def load_ipython_extension(ip):
         vw = VarWatcher(ip)
         ip.callbacks.register('pre_execute', vw.pre_execute)
         ip.callbacks.register('post_execute', vw.post_execute)
 
+.. note::
+
+   This API is experimental in IPython 2.0, and may be revised in future versions.
+
 .. 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.