Warning
This documentation is for an old version of IPython. You can find docs for newer versions here.
Implementation of code management magic functions.
Bases: exceptions.ValueError
Bases: exceptions.Exception
Exception for interactively defined variable in magic_edit
Bases: IPython.core.magic.Magics
Magics related to code management (loading, saving, editing, ...).
Bring up an editor and execute the resulting code.
%edit runs IPython’s editor hook. The default version of this hook is set to call the editor specified by your $EDITOR environment variable. If this isn’t found, it will default to vi under Linux/Unix and to notepad under Windows. See the end of this docstring for how to change the editor hook.
You can also set the value of this editor via the TerminalInteractiveShell.editor option in your configuration file. This is useful if you wish to use a different editor from your typical default with IPython (and for Windows users who typically don’t set environment variables).
This command allows you to conveniently edit multi-line code right in your IPython session.
If called without arguments, %edit opens up an empty editor with a temporary file and will execute the contents of this file when you close it (don’t forget to save it!).
Options:
-n <number>: open the editor at a specified line number. By default, the IPython editor hook uses the unix syntax ‘editor +N filename’, but you can configure this by providing your own modified hook if your favorite editor supports line-number specifications with a different syntax.
-p: this will call the editor with the same data as the previous time it was used, regardless of how long ago (in your current session) it was.
-r: use ‘raw’ input. This option only applies to input taken from the user’s history. By default, the ‘processed’ history is used, so that magics are loaded in their transformed version to valid Python. If this option is given, the raw input as typed as the command line is used instead. When you exit the editor, it will be executed by IPython’s own processor.
-x: do not execute the edited code immediately upon exit. This is mainly useful if you are editing programs which need to be called with command line arguments, which you can then do using %run.
Arguments:
If arguments are given, the following possibilities exist:
Note: opening at an exact line is only supported under Unix, and some editors (like kedit and gedit up to Gnome 2.8) do not understand the ‘+NUMBER’ parameter necessary for this feature. Good editors like (X)Emacs, vi, jed, pico and joe all do.
After executing your code, %edit will return as output the code you typed in the editor (except when it was an existing file). This way you can reload the code in further invocations of %edit as a variable, via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of the output.
Note that %edit is also available through the alias %ed.
This is an example of creating a simple function inside the editor and then modifying it. First, start up the editor:
In [1]: edit
Editing... done. Executing edited code...
Out[1]: 'def foo():\n print "foo() was defined in an editing
session"\n'
We can then call the function foo():
In [2]: foo()
foo() was defined in an editing session
Now we edit foo. IPython automatically loads the editor with the (temporary) file where foo() was previously defined:
In [3]: edit foo
Editing... done. Executing edited code...
And if we call foo() again we get the modified version:
In [4]: foo()
foo() has now been changed!
Here is an example of how to edit a code snippet successive times. First we call the editor:
In [5]: edit
Editing... done. Executing edited code...
hello
Out[5]: "print 'hello'\n"
Now we call it again with the previous output (stored in _):
In [6]: edit _
Editing... done. Executing edited code...
hello world
Out[6]: "print 'hello world'\n"
Now we call it with the output #8 (stored in _8, also as Out[8]):
In [7]: edit _8
Editing... done. Executing edited code...
hello again
Out[7]: "print 'hello again'\n"
Changing the default editor hook:
If you wish to write your own editor hook, you can put it in a configuration file which you load at startup time. The default hook is defined in the IPython.core.hooks module, and you can use that as a starting example for further modifications. That file also has general instructions on how to set a new hook for use once you’ve defined it.
Load code into the current frontend.
%load [options] source
where source can be a filename, URL, input history range or macro
Alias of %load
%loadpy has gained some flexibility and dropped the requirement of a .py extension. So it has been renamed simply into %load. You can look at %load‘s docstring for more info.
Upload code to Github’s Gist paste bin, returning the URL.
The argument can be an input history range, a filename, or the name of a string or macro.
Options:
- -d: Pass a custom description for the gist. The default will say
- “Pasted from IPython”.
Save a set of lines or a macro to a given filename.
Options:
-r: use ‘raw’ input. By default, the ‘processed’ history is used, so that magics are loaded in their transformed version to valid Python. If this option is given, the raw input as typed as the command line is used instead.
-f: force overwrite. If file exists, %save will prompt for overwrite unless -f is given.
-a: append to the file instead of overwriting it.
This function uses the same syntax as %history for input ranges, then saves the lines to the filename you specify.
It adds a ‘.py’ extension to the file if you don’t do so yourself, and it asks for confirmation before overwriting existing files.
If -r option is used, the default extension is .ipy.