Note

This documentation is for a development version of IPython. There may be significant differences from the latest stable release (1.2.1).

2.0 Series

Release 2.0.0

April, 2014

IPython 2.0 requires Python ≥ 2.7.2 or ≥ 3.2.1. It does not support Python 3.0, 3.1, 2.5, or 2.6.

The principal milestones of 2.0 are:

• interactive widgets for the HTML notebook
• a new modal user interface in the notebook
• a security model for notebooks

Contribution summary since IPython 1.0 in August, 2013:

• ~8 months of work
• ~650 pull requests merged
• ~400 issues closed (non-pull requests)
• contributions from ~100 authors
• ~4000 commits

The amount of work included in this release is so large that we can only cover here the main highlights; please see our detailed release statistics for links to every issue and pull request closed on GitHub as well as a full list of individual contributors.

New stuff in the IPython notebook

Directory navigation

The IPython notebook dashboard allows navigation into subdirectories. URLs are persistent based on the notebook’s path, so no more random UUID URLs.

Serving local files no longer needs the files/ prefix. Relative links across notebooks and other files should work just as if notebooks were regular HTML files.

Notebook Widgets

Available in the new IPython.html.widgets module, widgets provide an easy way for IPython notebook users to display GUI controls in the IPython notebook. IPython comes with bundle of built-in widgets and also the ability for users to define their own widgets. A widget is displayed in the front-end using using a view. For example, a FloatRangeWidget can be displayed using a FloatSliderView (which is the default if no view is specified when displaying the widget). IPython also comes with a bundle of views and the ability for the user to define custom views. One widget can be displayed multiple times, in on or more cells, using one or more views. All views will automatically remain in sync with the widget which is accessible in the back-end.

The widget layer provides an MVC-like architecture on top of the comm layer. It’s useful for widgets that can be expressed via a list of properties. Widgets work by synchronizing IPython traitlet models in the back-end with backbone models in the front-end. The widget layer automatically handles

• delta compression (only sending the state information that has changed)
• wiring the message callbacks to the correct cells automatically
• inter-view synchronization (handled by backbone)
• message throttling (to avoid flooding the kernel)
• parent/child relationships between views (which one can override to specify custom parent/child relationships)
• ability to manipulate the widget view’s DOM from python using CSS, $().addClass, and $().removeClass methods

Interactive Notebook Tour

Familiarize yourself with the updated notebook user interface, including an explanation of Edit and Command modes, by going through the short guided tour which can be started from the Help menu.

Signing Notebooks

To prevent untrusted code from executing on users’ behalf when notebooks open, we have added a signature to the notebook, stored in metadata.

For more information, see Signing Notebooks.

Dashboard “Running” Tab

The dashboard now has a “Running” tab which shows all of the running notebooks.

Single codebase Python 3 support

IPython previously supported Python 3 by running 2to3 during setup. We have now switched to a single codebase which runs natively on Python 2.7 and 3.3.

For notes on how to maintain this, see Writing code for Python 2 and 3.

clear_output changes

• There is no longer a 500ms delay when calling clear_output.
• The ability to clear stderr and stdout individually was removed.
• A new wait flag that prevents clear_output from being executed until new output is available. This eliminates animation flickering by allowing the user to double buffer the output.
• The output div height is remembered when the wait=True flag is used.

Extending Configurable Containers

Some configurable traits are containers (list, dict, set) Config objects now support calling extend, update, insert, etc. on traits in config files, which will ultimately result in calling those methods on the original object.

The effect being that you can now add to containers without having to copy/paste the initial value:

c = get_config()
c.InlineBackend.rc.update({ 'figure.figsize' : (6, 4) })

changes to hidden namespace on startup

Previously, all names declared in code run at startup (startup files, ipython -i script.py, etc.) were added to the hidden namespace, which hides the names from tools like %whos. There are two changes to this behavior:

1. Scripts run on the command-line ipython -i script.py``now behave the same as if they were passed to ``%run, so their variables are never hidden.
2. A boolean config flag InteractiveShellApp.hide_initial_ns has been added to optionally disable the hidden behavior altogether. The default behavior is unchanged.

Using dill to expand serialization support

adds use_dill() for allowing dill to extend serialization support in IPython.parallel (closures, etc.). Also adds DirectView.use_dill() convenience method for enabling dill locally and on all engines with one call.

New IPython Console Lexer

The IPython console lexer has been rewritten and now supports tracebacks and customized input/output prompts. See the new lexer docs for details.

DisplayFormatter changes

There was no official way to query or remove callbacks in the Formatter API. To remedy this, the following methods are added to BaseFormatter:

• lookup(instance) - return appropriate callback or a given object
• lookup_by_type(type_or_str) - return appropriate callback for a given type or 'mod.name' type string
• pop(type_or_str) - remove a type (by type or string). Pass a second argument to avoid KeyError (like dict).

All of the above methods raise a KeyError if no match is found.

And the following methods are changed:

• for_type(type_or_str) - behaves the same as before, only adding support for 'mod.name' type strings in addition to plain types. This removes the need for for_type_by_name(), but it remains for backward compatibility.

Formatters can now raise NotImplementedError in addition to returning None to indicate that they cannot format a given object.

Exceptions and Warnings

Exceptions are no longer silenced when formatters fail. Instead, these are turned into FormatterWarnings. A FormatterWarning will also be issued if a formatter returns data of an invalid type (e.g. an integer for ‘image/png’).

Other changes

• %%capture cell magic now captures the rich display output, not just stdout/stderr
• In notebook, Showing tooltip on tab has been disables to avoid conflict with completion, Shift-Tab could still be used to invoke tooltip when inside function signature and/or on selection.
• object_info_request as been replaced by object_info for consistency in the javascript API. object_info as a simpler interface to register callback that is incompatible with object_info_request.
• Previous versions of IPython on Linux would use the XDG config directory, creating ~/.config/ipython by default. We have decided to go back to ~/.ipython for consistency among systems. IPython will issue a warning if it finds the XDG location, and will move it to the new location if there isn’t already a directory there.
• Equations, images and tables are now centered in Markdown cells.
• Multiline equations are now centered in output areas; single line equations remain left justified.
• IPython config objects can be loaded from and serialized to JSON. JSON config file have the same base name as their .py counterpart, and will be loaded with higher priority if found.
• bash completion updated with support for all ipython subcommands and flags, including nbconvert
• ipython history trim: added --keep=<N> as an alias for the more verbose --HistoryTrim.keep=<N>
• new ipython history clear subcommand, which is the same as the newly supported ipython history trim --keep=0
• You can now run notebooks in an interactive session via %run notebook.ipynb.
• Print preview is back in the notebook menus, along with options to download the open notebook in various formats. This is powered by nbconvert.
• PandocMissing exceptions will be raised if Pandoc is unavailable, and warnings will be printed if the version found is too old. The recommended Pandoc version for use with nbconvert is 1.12.1.
• The InlineBackend.figure_format now supports JPEG output if PIL/Pillow is available.
• Input transformers (see Custom input transformation) may now raise SyntaxError if they determine that input is invalid. The input transformation machinery in IPython will handle displaying the exception to the user and resetting state.
• Calling container.show() on javascript display is deprecated and will trigger errors on future IPython notebook versions. container now show itself as soon as non-empty
• Added InlineBackend.print_figure_kwargs to allow passing keyword arguments to matplotlib’s Canvas.print_figure. This can be used to change the value of bbox_inches, which is ‘tight’ by default, or set the quality of JPEG figures.
• A new callback system has been introduced. For details, see Registering callbacks.

Backwards incompatible changes

• Python 2.6 and 3.2 are no longer supported: the minimum required Python versions are now 2.7 and 3.3.

• The Transformer classes have been renamed to Preprocessor in nbconvert and their call methods for them have been renamed to preprocess.

• The call methods of nbconvert post-processsors have been renamed to postprocess.

• The module IPython.core.fakemodule has been removed.

• The alias system has been reimplemented to use magic functions. There should be little visible difference while automagics are enabled, as they are by default, but parts of the AliasManager API have been removed.

• We fixed an issue with switching between matplotlib inline and GUI backends, but the fix requires matplotlib 1.1 or newer. So from now on, we consider matplotlib 1.1 to be the minimally supported version for IPython. Older versions for the most part will work, but we make no guarantees about it.

• The pycolor command has been removed. We recommend the much more capable pygmentize command from the Pygments project. If you need to keep the exact output of pycolor, you can still use python -m IPython.utils.PyColorize foo.py.

• IPython.lib.irunner and its command-line entry point have been removed. It had fallen out of use long ago.

• The input_prefilter hook has been removed, as it was never actually used by the code. The input transformer system offers much more powerful APIs to work with input code. See Custom input transformation for details.

• IPython.core.inputsplitter.IPythonInputSplitter no longer has a method source_raw_reset(), but gains raw_reset() instead. Use of source_raw_reset can be replaced with:

  raw = isp.source_raw
  transformed = isp.source_reset()
  

• The Azure notebook manager was removed as it was no longer compatible with the notebook storage scheme

Simplifying configurable URLs

• base_project_url is renamed to base_url (base_project_url is kept as a deprecated alias, for now)
• base_kernel_url configurable is removed (use base_url)
• websocket_url configurable is removed (use base_url)