docs/source/changes.txt

.. Developers should add in this file, during each release cycle, information
.. about important changes they've made, in a summary format that's meant for
.. end users.  For each release we normally have three sections: features,  bug
.. fixes and api breakage.
.. Please remember to credit the authors of the contributions by name,
.. especially when they are new users or developers who do not regularly
.. participate  in IPython's development.

.. _changes:

==========
What's new
==========

Release 0.10
============

This release brings months of slow but steady development, and will be the last
before a major restructuring and cleanup of IPython's internals that is already
under way.  For this reason, we hope that 0.10 will be a stable and robust
release so that while users adapt to some of the API changes that will come
with the refactoring that will become IPython 0.11, they can safely use 0.10 in
all existing projects with minimal changes (if any).

IPython 0.10 is now a medium-sized project, with roughly (as reported by David
Wheeler's :command:`sloccount` utility) 40750 lines of Python code, and a diff
between 0.9.1 and this release that contains almost 28000 lines of code and
documentation.  Our documentation, in PDF format, is a 495-page long PDF
document (also available in HTML format, both generated from the same sources).

Many users and developers contributed code, features, bug reports and ideas to
this release.  Please do not hesitate in contacting us if we've failed to
acknowledge your contribution here.  In particular, for this release we have
contribution from the following people, a mix of new and regular names (in
alphabetical order by first name):

* Alexander Clausen: fix #341726.
* Brian Granger: lots of work everywhere (features, bug fixes, etc).
* Daniel Ashbrook: bug report on MemoryError during compilation, now fixed.
* Darren Dale: improvements to documentation build system, feedback, design
  ideas.
* Fernando Perez: various places.
* Gaël Varoquaux: core code, ipythonx GUI, design discussions, etc. Lots...
* John Hunter: suggestions, bug fixes, feedback.
* Jorgen Stenarson: work on many fronts, tests, fixes, win32 support, etc.
* Laurent Dufréchou: many improvements to ipython-wx standalone app.
* Lukasz Pankowski: prefilter, `%edit`, demo improvements.
* Matt Foster: TextMate support in `%edit`.
* Nathaniel Smith: fix #237073.
* Pauli Virtanen: fixes and improvements to extensions, documentation.
* Prabhu Ramachandran: improvements to `%timeit`.
* Robert Kern: several extensions.
* Sameer D'Costa: help on critical bug #269966.
* Stephan Peijnik: feedback on Debian compliance and many man pages.
* Steven Bethard: we are now shipping his :mod:`argparse` module.
* Tom Fetherston: many improvements to :mod:`IPython.demo` module.
* Ville Vainio: lots of work everywhere (features, bug fixes, etc).
* Vishal Vasta: ssh support in ipcluster.
* Walter Doerwald: work on the :mod:`IPython.ipipe` system.

Below we give an overview of new features, bug fixes and backwards-incompatible
changes.  For a detailed account of every change made, feel free to view the
project log with :command:`bzr log`.

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

* New `%paste` magic automatically extracts current contents of clipboard and
  pastes it directly, while correctly handling code that is indented or
  prepended with `>>>` or `...` python prompt markers.  A very useful new
  feature contributed by Robert Kern.

* IPython 'demos', created with the :mod:`IPython.demo` module, can now be
  created from files on disk or strings in memory.  Other fixes and
  improvements to the demo system, by Tom Fetherston.

* Added :func:`find_cmd` function to :mod:`IPython.platutils` module, to find
  commands in a cross-platform manner.

* Many improvements and fixes to Gaël Varoquaux's :command:`ipythonx`, a
  WX-based lightweight IPython instance that can be easily embedded in other WX
  applications.  These improvements have made it possible to now have an
  embedded IPython in Mayavi and other tools.

* :class:`MultiengineClient` objects now have a :meth:`benchmark` method.

* The manual now includes a full set of auto-generated API documents from the
  code sources, using Sphinx and some of our own support code.  We are now
  using the `Numpy Documentation Standard`_  for all docstrings, and we have
  tried to update as many existing ones as possible to this format.

* The new :mod:`IPython.Extensions.ipy_pretty` extension by Robert Kern
  provides configurable pretty-printing.

* Many improvements to the :command:`ipython-wx` standalone WX-based IPython
  application by Laurent Dufréchou.  It can optionally run in a thread, and
  this can be toggled at runtime (allowing the loading of Matplotlib in a
  running session without ill effects).

* IPython includes a copy of Steven Bethard's argparse_ in the
  :mod:`IPython.external` package, so we can use it internally and it is also
  available to any IPython user.  By installing it in this manner, we ensure
  zero conflicts with any system-wide installation you may already have while
  minimizing external dependencies for new users.  In IPython 0.10, We ship
  argparse version 1.0.

* An improved and much more robust test suite, that runs groups of tests in
  separate subprocesses using either Nose or Twisted's :command:`trial` runner
  to ensure proper management of Twisted-using code.  The test suite degrades
  gracefully if optional dependencies are not available, so that the
  :command:`iptest` command can be run with only Nose installed and nothing
  else.  We also have more and cleaner test decorators to better select tests
  depending on runtime conditions, do setup/teardown, etc.

* The new ipcluster now has a fully working ssh mode that should work on
  Linux, Unix and OS X.  Thanks to Vishal Vatsa for implementing this!

* The wonderful TextMate editor can now be used with %edit on OS X.  Thanks
  to Matt Foster for this patch.

* The documentation regarding parallel uses of IPython, including MPI and PBS,
  has been significantly updated and improved.

* The developer guidelines in the documentation have been updated to explain
  our workflow using :command:`bzr` and Launchpad.
  
* Fully refactored :command:`ipcluster` command line program for starting
  IPython clusters.  This new version is a complete rewrite and 1) is fully
  cross platform (we now use Twisted's process management), 2) has much
  improved performance, 3) uses subcommands for different types of clusters, 4)
  uses argparse for parsing command line options, 5) has better support for
  starting clusters using :command:`mpirun`, 6) has experimental support for
  starting engines using PBS.  It can also reuse FURL files, by appropriately
  passing options to its subcommands.  However, this new version of ipcluster
  should be considered a technology preview.  We plan on changing the API in
  significant ways before it is final.

* Full description of the security model added to the docs.

* cd completer: show bookmarks if no other completions are available.

* sh profile: easy way to give 'title' to prompt: assign to variable
  '_prompt_title'. It looks like this::
      
        [~]|1> _prompt_title = 'sudo!'
        sudo![~]|2>

* %edit: If you do '%edit pasted_block', pasted_block variable gets updated
  with new data (so repeated editing makes sense)

.. _Numpy Documentation Standard: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard

.. _argparse: http://code.google.com/p/argparse/

Bug fixes
---------

* Fix #368719, removed top-level debian/ directory to make the job of Debian
  packagers easier.
  
* Fix #291143 by including man pages contributed by Stephan Peijnik from the
  Debian project.

* Fix #358202, effectively a race condition, by properly synchronizing file
  creation at cluster startup time.

* `%timeit` now handles correctly functions that take a long time to execute
  even the first time, by not repeating them.

* Fix #239054, releasing of references after exiting.

* Fix #341726, thanks to Alexander Clausen.

* Fix #269966.  This long-standing and very difficult bug (which is actually a
  problem in Python itself) meant long-running sessions would inevitably grow
  in memory size, often with catastrophic consequences if users had large
  objects in their scripts.  Now, using `%run` repeatedly should not cause any
  memory leaks.  Special thanks to John Hunter and Sameer D'Costa for their
  help with this bug.

* Fix #295371, bug in `%history`.

* Improved support for py2exe.

* Fix #270856: IPython hangs with PyGTK

* Fix #270998: A magic with no docstring breaks the '%magic magic'

* fix #271684: -c startup commands screw up raw vs. native history

* Numerous bugs on Windows with the new ipcluster have been fixed.

* The ipengine and ipcontroller scripts now handle missing furl files
  more gracefully by giving better error messages.

* %rehashx: Aliases no longer contain dots. python3.0 binary
  will create alias python30. Fixes:
  #259716 "commands with dots in them don't work"

* %cpaste: %cpaste -r repeats the last pasted block.
  The block is assigned to pasted_block even if code
  raises exception.

* Bug #274067 'The code in get_home_dir is broken for py2exe' was
  fixed.

* Many other small bug fixes not listed here by number (see the bzr log for
  more info).
  
Backwards incompatible changes
------------------------------

* `ipykit` and related files were unmaintained and have been removed.

* The :func:`IPython.genutils.doctest_reload` does not actually call
  `reload(doctest)` anymore, as this was causing many problems with the test
  suite.  It still resets `doctest.master` to None.

* While we have not deliberately broken Python 2.4 compatibility, only minor
  testing was done with Python 2.4, while 2.5 and 2.6 were fully tested.  But
  if you encounter problems with 2.4, please do report them as bugs.

* The :command:`ipcluster` now requires a mode argument; for example to start a
  cluster on the local machine with 4 engines, you must now type::

    $ ipcluster local -n 4

* The controller now has a ``-r`` flag that needs to be used if you want to
  reuse existing furl files.  Otherwise they are deleted (the default).

* Remove ipy_leo.py. You can use :command:`easy_install ipython-extension` to
  get it.  (done to decouple it from ipython release cycle)


Release 0.9.1
=============

This release was quickly made to restore compatibility with Python 2.4, which
version 0.9 accidentally broke.  No new features were introduced, other than
some additional testing support for internal use.


Release 0.9
===========

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

* All furl files and security certificates are now put in a read-only
  directory named ~./ipython/security.

* A single function :func:`get_ipython_dir`, in :mod:`IPython.genutils` that
  determines the user's IPython directory in a robust manner.

* Laurent's WX application has been given a top-level script called
  ipython-wx, and it has received numerous fixes. We expect this code to be
  architecturally better integrated with Gael's WX 'ipython widget' over the
  next few releases.

* The Editor synchronization work by Vivian De Smedt has been merged in.  This
  code adds a number of new editor hooks to synchronize with editors under
  Windows.

* A new, still experimental but highly functional, WX shell by Gael Varoquaux.
  This work was sponsored by Enthought, and while it's still very new, it is
  based on a more cleanly organized arhictecture of the various IPython
  components. We will continue to develop this over the next few releases as a
  model for GUI components that use IPython.

* Another GUI frontend, Cocoa based (Cocoa is the OSX native GUI framework),
  authored by Barry Wark.  Currently the WX and the Cocoa ones have slightly
  different internal organizations, but the whole team is working on finding
  what the right abstraction points are for a unified codebase.

* As part of the frontend work, Barry Wark also implemented an experimental
  event notification system that various ipython components can use.  In the
  next release the implications and use patterns of this system regarding the
  various GUI options will be worked out.

* IPython finally has a full test system, that can test docstrings with
  IPython-specific functionality.  There are still a few pieces missing for it
  to be widely accessible to all users (so they can run the test suite at any
  time and report problems), but it now works for the developers.  We are
  working hard on continuing to improve it, as this was probably IPython's
  major Achilles heel (the lack of proper test coverage made it effectively
  impossible to do large-scale refactoring).  The full test suite can now
  be run using the :command:`iptest` command line program.

* The notion of a task has been completely reworked.  An `ITask` interface has
  been created.  This interface defines the methods that tasks need to
  implement.  These methods are now responsible for things like submitting
  tasks and processing results.  There are two basic task types:
  :class:`IPython.kernel.task.StringTask` (this is the old `Task` object, but
  renamed) and the new :class:`IPython.kernel.task.MapTask`, which is based on
  a function.

* A new interface, :class:`IPython.kernel.mapper.IMapper` has been defined to
  standardize the idea of a `map` method.  This interface has a single `map`
  method that has the same syntax as the built-in `map`.  We have also defined
  a `mapper` factory interface that creates objects that implement
  :class:`IPython.kernel.mapper.IMapper` for different controllers.  Both the
  multiengine and task controller now have mapping capabilties.

* The parallel function capabilities have been reworks.  The major changes are
  that i) there is now an `@parallel` magic that creates parallel functions,
  ii) the syntax for mulitple variable follows that of `map`, iii) both the
  multiengine and task controller now have a parallel function implementation.

* All of the parallel computing capabilities from `ipython1-dev` have been
  merged into IPython proper.  This resulted in the following new subpackages:
  :mod:`IPython.kernel`, :mod:`IPython.kernel.core`, :mod:`IPython.config`,
  :mod:`IPython.tools` and :mod:`IPython.testing`.

* As part of merging in the `ipython1-dev` stuff, the `setup.py` script and
  friends have been completely refactored.  Now we are checking for
  dependencies using the approach that matplotlib uses.

* The documentation has been completely reorganized to accept the 
  documentation from `ipython1-dev`.

* We have switched to using Foolscap for all of our network protocols in
  :mod:`IPython.kernel`.  This gives us secure connections that are both
  encrypted and authenticated.

* We have a brand new `COPYING.txt` files that describes the IPython license
  and copyright. The biggest change is that we are putting "The IPython
  Development Team" as the copyright holder. We give more details about
  exactly what this means in this file. All developer should read this and use
  the new banner in all IPython source code files.

* sh profile: ./foo runs foo as system command, no need to do !./foo anymore

* String lists now support ``sort(field, nums = True)`` method (to easily sort
  system command output). Try it with ``a = !ls -l ; a.sort(1, nums=1)``.

* '%cpaste foo' now assigns the pasted block as string list, instead of string

* The ipcluster script now run by default with no security.  This is done
  because the main usage of the script is for starting things on localhost.
  Eventually when ipcluster is able to start things on other hosts, we will put
  security back.

* 'cd --foo' searches directory history for string foo, and jumps to that dir.
  Last part of dir name is checked first. If no matches for that are found,
  look at the whole path.

  
Bug fixes
---------

* The Windows installer has been fixed.  Now all IPython scripts have ``.bat``
  versions created.  Also, the Start Menu shortcuts have been updated.

* The colors escapes in the multiengine client are now turned off on win32 as
  they don't print correctly.

* The :mod:`IPython.kernel.scripts.ipengine` script was exec'ing
  mpi_import_statement incorrectly, which was leading the engine to crash when
  mpi was enabled.

* A few subpackages had missing ``__init__.py`` files.

* The documentation is only created if Sphinx is found.  Previously, the
  ``setup.py`` script would fail if it was missing.

* Greedy ``cd`` completion has been disabled again (it was enabled in 0.8.4) as
  it caused problems on certain platforms.
          

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

* The ``clusterfile`` options of the :command:`ipcluster` command has been
  removed as it was not working and it will be replaced soon by something much
  more robust.

* The :mod:`IPython.kernel` configuration now properly find the user's
  IPython directory.

* In ipapi, the :func:`make_user_ns` function has been replaced with
  :func:`make_user_namespaces`, to support dict subclasses in namespace
  creation.

* :class:`IPython.kernel.client.Task` has been renamed
  :class:`IPython.kernel.client.StringTask` to make way for new task types.

* The keyword argument `style` has been renamed `dist` in `scatter`, `gather`
  and `map`.

* Renamed the values that the rename `dist` keyword argument can have from
  `'basic'` to `'b'`.

* IPython has a larger set of dependencies if you want all of its capabilities.
  See the `setup.py` script for details.

* The constructors for :class:`IPython.kernel.client.MultiEngineClient` and 
  :class:`IPython.kernel.client.TaskClient` no longer take the (ip,port) tuple.
  Instead they take the filename of a file that contains the FURL for that
  client.  If the FURL file is in your IPYTHONDIR, it will be found automatically
  and the constructor can be left empty.

* The asynchronous clients in :mod:`IPython.kernel.asyncclient` are now created 
  using the factory functions :func:`get_multiengine_client` and 
  :func:`get_task_client`.  These return a `Deferred` to the actual client.

* The command line options to `ipcontroller` and `ipengine` have changed to
  reflect the new Foolscap network protocol and the FURL files.  Please see the
  help for these scripts for details.

* The configuration files for the kernel have changed because of the Foolscap
  stuff.  If you were using custom config files before, you should delete them
  and regenerate new ones.

Changes merged in from IPython1
-------------------------------

New features
............

* Much improved ``setup.py`` and ``setupegg.py`` scripts.  Because Twisted and
  zope.interface are now easy installable, we can declare them as dependencies
  in our setupegg.py script.

* IPython is now compatible with Twisted 2.5.0 and 8.x.

* Added a new example of how to use :mod:`ipython1.kernel.asynclient`.

* Initial draft of a process daemon in :mod:`ipython1.daemon`.  This has not
  been merged into IPython and is still in `ipython1-dev`.
  
* The ``TaskController`` now has methods for getting the queue status.

* The ``TaskResult`` objects not have information about how long the task
  took to run.
  
* We are attaching additional attributes to exceptions ``(_ipython_*)`` that 
  we use to carry additional info around.
  
* New top-level module :mod:`asyncclient` that has asynchronous versions (that
  return deferreds) of the client classes.  This is designed to users who want
  to run their own Twisted reactor.
  
* All the clients in :mod:`client` are now based on Twisted.  This is done by 
  running the Twisted reactor in a separate thread and using the
  :func:`blockingCallFromThread` function that is in recent versions of Twisted.

* Functions can now be pushed/pulled to/from engines using
  :meth:`MultiEngineClient.push_function` and
  :meth:`MultiEngineClient.pull_function`.

* Gather/scatter are now implemented in the client to reduce the work load
  of the controller and improve performance.

* Complete rewrite of the IPython docuementation.  All of the documentation
  from the IPython website has been moved into docs/source as restructured
  text documents.  PDF and HTML documentation are being generated using 
  Sphinx.

* New developer oriented documentation: development guidelines and roadmap. 

* Traditional ``ChangeLog`` has been changed to a more useful ``changes.txt``
  file that is organized by release and is meant to provide something more
  relevant for users.

Bug fixes
.........

* Created a proper ``MANIFEST.in`` file to create source distributions.

* Fixed a bug in the ``MultiEngine`` interface.  Previously, multi-engine 
  actions were being collected with a :class:`DeferredList` with 
  ``fireononeerrback=1``.  This meant that methods were returning 
  before all engines had given their results.  This was causing extremely odd 
  bugs in certain cases. To fix this problem, we have 1) set 
  ``fireononeerrback=0`` to make sure all results (or exceptions) are in 
  before returning and 2) introduced a :exc:`CompositeError` exception 
  that wraps all of the engine exceptions.  This is a huge change as it means 
  that users will have to catch :exc:`CompositeError` rather than the actual
  exception.

Backwards incompatible changes
..............................

* All names have been renamed to conform to the lowercase_with_underscore
  convention.  This will require users to change references to all names like
  ``queueStatus`` to ``queue_status``.

* Previously, methods like :meth:`MultiEngineClient.push` and
  :meth:`MultiEngineClient.push` used ``*args`` and ``**kwargs``.  This was
  becoming a problem as we weren't able to introduce new keyword arguments into
  the API.  Now these methods simple take a dict or sequence.  This has also
  allowed us to get rid of the ``*All`` methods like :meth:`pushAll` and
  :meth:`pullAll`.  These things are now handled with the ``targets`` keyword
  argument that defaults to ``'all'``.

* The :attr:`MultiEngineClient.magicTargets` has been renamed to
  :attr:`MultiEngineClient.targets`. 

* All methods in the MultiEngine interface now accept the optional keyword
  argument ``block``.

* Renamed :class:`RemoteController` to :class:`MultiEngineClient` and 
  :class:`TaskController` to :class:`TaskClient`.

* Renamed the top-level module from :mod:`api` to :mod:`client`.

* Most methods in the multiengine interface now raise a :exc:`CompositeError`
  exception that wraps the user's exceptions, rather than just raising the raw
  user's exception.

* Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class to ``push`` 
  and ``pull``.

  
Release 0.8.4
=============

This was a quick release to fix an unfortunate bug that slipped into the 0.8.3
release.  The ``--twisted`` option was disabled, as it turned out to be broken
across several platforms.


Release 0.8.3
=============
  
* pydb is now disabled by default (due to %run -d problems). You can enable
  it by passing -pydb command line argument to IPython. Note that setting
  it in config file won't work.

  
Release 0.8.2
=============

* %pushd/%popd behave differently; now "pushd /foo" pushes CURRENT directory 
  and jumps to /foo. The current behaviour is closer to the documented 
  behaviour, and should not trip anyone.

  
Older releases
==============

Changes in earlier releases of IPython are described in the older file
``ChangeLog``.  Please refer to this document for details.