docs/source/config/editors.txt

.. _editors:

====================
Editor configuration
====================

IPython can integrate with text editors in a number of different ways:

* Editors (such as (X)Emacs [Emacs]_, vim [vim]_ and TextMate [TextMate]_) can
  send code to IPython for execution.

* IPython's ``%edit`` magic command can open an editor of choice to edit
  a code block.

The %edit command (and its alias %ed) will invoke the editor set in your
environment as :envvar:`EDITOR`. If this variable is not set, it will default
to vi under Linux/Unix and to notepad under Windows. You may want to set this
variable properly and to a lightweight editor which doesn't take too long to
start (that is, something other than a new instance of Emacs). This way you
can edit multi-line code quickly and with the power of a real editor right
inside IPython.

You can also control the editor via the commmand-line option '-editor' or in
your configuration file, by setting the :attr:`InteractiveShell.editor`
configuration attribute.

TextMate
========

Currently, TextMate support in IPython is broken.  It used to work well,
but the code has been moved to :mod:`IPython.quarantine` until it is updated.

vim configuration
=================

Currently, vim support in IPython is broken.  Like the TextMate code,
the vim support code has been moved to :mod:`IPython.quarantine` until it
is updated.

.. _emacs:

(X)Emacs
========

Editor
======

If you are a dedicated Emacs user, and want to use Emacs when IPython's
``%edit`` magic command is called you should set up the Emacs server so that
new requests are handled by the original process. This means that almost no
time is spent in handling the request (assuming an Emacs process is already
running). For this to work, you need to set your EDITOR environment variable
to 'emacsclient'. The code below, supplied by Francois Pinard, can then be
used in your :file:`.emacs` file to enable the server::

    (defvar server-buffer-clients)
    (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
      (server-start)
      (defun fp-kill-server-with-buffer-routine ()
        (and server-buffer-clients (server-done)))
      (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))

Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
currently (X)Emacs and IPython get along very well in other ways.

.. note::

    You will need to use a recent enough version of :file:`python-mode.el`,
    along with the file :file:`ipython.el`. You can check that the version you
    have of :file:`python-mode.el` is new enough by either looking at the
    revision number in the file itself, or asking for it in (X)Emacs via ``M-x
    py-version``. Versions 4.68 and newer contain the necessary fixes for
    proper IPython support.

The file :file:`ipython.el` is included with the IPython distribution, in the
directory :file:`docs/emacs`. Once you put these files in your Emacs path, all
you need in your :file:`.emacs` file is::

    (require 'ipython)

This should give you full support for executing code snippets via
IPython, opening IPython as your Python shell via ``C-c !``, etc.

You can customize the arguments passed to the IPython instance at startup by
setting the ``py-python-command-args`` variable.  For example, to start always
in ``pylab`` mode with hardcoded light-background colors, you can use::

    (setq py-python-command-args '("-pylab" "-colors" "LightBG"))

If you happen to get garbage instead of colored prompts as described in
the previous section, you may need to set also in your :file:`.emacs` file::

    (setq ansi-color-for-comint-mode t)

Notes on emacs support:

* There is one caveat you should be aware of: you must start the IPython shell
  before attempting to execute any code regions via ``C-c |``. Simply type
  ``C-c !`` to start IPython before passing any code regions to the
  interpreter, and you shouldn't experience any problems. This is due to a bug
  in Python itself, which has been fixed for Python 2.3, but exists as of
  Python 2.2.2 (reported as SF bug [ 737947 ]).

* The (X)Emacs support is maintained by Alexander Schmolck, so all
  comments/requests should be directed to him through the IPython mailing
  lists.

* This code is still somewhat experimental so it's a bit rough around the
  edges (although in practice, it works quite well).

* Be aware that if you customized ``py-python-command`` previously, this value
  will override what :file:`ipython.el` does (because loading the customization
  variables comes later).

.. [Emacs] Emacs. http://www.gnu.org/software/emacs/
.. [TextMate] TextMate: the missing editor.  http://macromates.com/
.. [vim] vim. http://www.vim.org/