docs/source/whatsnew/development.txt

================================================
Development version
================================================

The changes listed here are a brief summary of the substantial work on IPython
since the 0.11.x release series. For more details, please consult the actual
source.

Main `ipython` branch
=====================


New features
------------

.. Expand on this:
* **HTML Notebook**: A powerful new interface puts IPython in your browser. You
  can start it with the command ``ipython notebook``. See :ref:`the Notebook
  docs <htmlnotebook>` for technical details.

* **Tabbed QtConsole**: The QtConsole now supports starting multiple kernels in
  tabs, and has a menubar, so it looks and behaves more like a real application.
  Keyboard enthusiasts can disable the menubar with ctrl-shift-M (:ghpull:`887`).

* **Python 3 compatibility**: IPython can now be installed from a single
  codebase on Python 2 and Python 3. The installation process for Python 3
  automatically runs 2to3. The same 'default' profile is now used for
  Python 2 and 3 (the previous version had a separate 'python3' profile).

* **PyPy support**: The terminal interface to IPython now runs under
  `PyPy <http://pypy.org/>`_.

* **SSH Tunnels**: In 0.11, the :mod:`IPython.parallel` Client could tunnel its
  connections to the Controller via ssh. Now, the QtConsole :ref:`supports
  <ssh_tunnels>` ssh tunneling, as do parallel engines.

* **relaxed command-line parsing**: 0.11 was released with overly-strict
  command-line parsing, preventing the ability to specify arguments with spaces,
  e.g. ``ipython --pylab qt`` or ``ipython -c "print 'hi'"``. This has
  been fixed, by using argparse. The new parsing is a strict superset of 0.11, so
  any commands in 0.11 should still work in 0.12.

* **HistoryAccessor**: The :class:`~IPython.core.history.HistoryManager` class for
  interacting with your IPython SQLite history database has been split, adding
  a parent :class:`~IPython.core.history.HistoryAccessor` class, so that users can
  write code to access and search their IPython history without being in an IPython
  session (:ghpull:`824`).

* **kernel %gui and %pylab**: The ``%gui`` and ``%pylab`` magics have been restored
  to the IPython kernel (e.g. in the qtconsole or notebook). This allows activation
  of pylab-mode, or eventloop integration after starting the kernel, which was
  unavailable in 0.11.  Unlike in the terminal, this can be set only once, and
  cannot be changed.

* **%config**: A new ``%config`` magic has been added, giving easy access to the
  IPython configuration system at runtime (:ghpull:`923`).

* **Standalone Kernel**: ``ipython kernel`` subcommand has been added, to allow
  starting a standalone kernel, that can be used with various frontends.

* **Multiline History**: Multiline readline history has been restored to the
  Terminal frontend by default (:ghpull:`838`).

* **%store**: The ``%store`` magic from earlier versions has been updated and
  placed in an extension, :ref:`extensions_storemagic`. Add 'storemagic' to ``c.InteractiveShellApp.extensions``
  in ipython_config.py to enable it (:ghpull:`1029`).



Major Bugs fixed
----------------

* Simple configuration errors should no longer crash IPython. In 0.11, errors in
  config files, as well as invalid trait values, could crash IPython. Now, such
  errors are reported, and help is displayed.

* Certain SyntaxErrors no longer crash IPython (e.g. just typing keywords, such as
  ``return``, ``break``, etc.). See :ghissue:`704`.

* IPython path utils, such as :func:`~IPython.utils.path.get_ipython_dir` now check
  for write permissions, so IPython should function on systems where the default
  path resolution might point to a read-only location, such as ``HOMESHARE`` on
  Windows (:ghissue:`669`).

* :func:`raw_input` now works in the kernel when multiple frontends are in use. The
  request will be sent to the frontend that made the request, and an exception is
  raised if that frontend does not support stdin requests (e.g. the notebook)
  (:ghissue:`673`).

* :mod:`zmq` version detection no longer uses simple lexicographical comparison to
  check minimum version, which prevents 0.11 from working with pyzmq-2.1.10
  (:ghpull:`758`).

* A bug in PySide < 1.0.7 caused crashes on OSX when tooltips were shown
  (:ghissue:`711`). these tooltips are now disabled on old PySide (:ghpull:`963`).

* IPython no longer crashes when started on recent versions of Python 3 in
  Windows (:ghissue:`737`).

* Instances of classes defined interactively can now be pickled (:ghissue:`29`;
  :ghpull:`648`). Note that pickling saves a reference to the class definition,
  so unpickling the instances will only work where the class has been defined.

.. * use bullet list

Backwards incompatible changes
------------------------------

* IPython connection information is no longer specified via ip/port directly,
  rather via json connection files.  These files are stored in the security
  directory, and enable us to turn on HMAC message authentication by default,
  significantly improving the security of kernels.  Various utility functions
  have been added to :mod:`IPython.lib.kernel`, for easier connecting to existing
  kernels.

* :class:`~IPython.zmq.kernelmanager.KernelManager` now has one ip, and several port
  traits, rather than several ip/port pair ``_addr`` traits. This better matches the
  rest of the code, where the ip cannot not be set separately for each channel.

* Custom prompts are now configured using a new class,
  :class:`~IPython.core.prompts.PromptManager`, which has traits for :attr:`in_template`,
  :attr:`in2_template` (the ``...:`` continuation prompt), :attr:`out_template`
  and :attr:`rewrite_template`. This uses Python's string formatting system, so
  you can use ``{time}`` and ``{cwd}``, although we have preserved the abbreviations
  from previous versions, e.g. ``\#`` (prompt number) and ``\w`` (working 
  directory). For the list of available fields, refer to the source of
  :file:`IPython/core/prompts.py`.

* The class inheritance of the Launchers in :mod:`IPython.parallel.apps.launcher`
  used by ipcluster has changed, so that trait names are more consistent across
  batch systems. This may require a few renames in your config files, if you
  customized the command-line args for launching controllers and engines. The
  configurable names have also been changed to be clearer that they point to class
  names, and can now be specified by name only, rather than requiring the full
  import path of each class, e.g.::

    IPClusterEngines.engine_launcher = 'IPython.parallel.apps.launcher.MPIExecEngineSetLauncher'
    IPClusterStart.controller_launcher = 'IPython.parallel.apps.launcher.SSHControllerLauncher'

  would now be specified as::

    IPClusterEngines.engine_launcher_class = 'MPIExec'
    IPClusterStart.controller_launcher_class = 'SSH'

  The full path will still work, and is necessary for using custom launchers not in
  IPython's launcher module.

* For embedding a shell, note that the parameters ``user_global_ns`` and ``global_ns``
  have been deprectated in favour of ``user_module`` and ``module`` respsectively.
  The new parameters expect a module-like object, rather than a namespace dict.
  The old parameters remain for backwards compatibility, although ``user_global_ns``
  is now ignored. The ``user_ns`` parameter works the same way as before, and
  calling :func:`~IPython.frontend.terminal.embed.embed` with no arguments still
  works as before.

.. * use bullet list