Shell

Module: Shell

Inheritance diagram for IPython.Shell:

IPython Shell classes.

All the matplotlib support code was co-developed with John Hunter, matplotlib’s author.

Classes

IPShell

class IPython.Shell.IPShell(argv=None, user_ns=None, user_global_ns=None, debug=1, shell_class=<class 'IPython.iplib.InteractiveShell'>)

Create an IPython instance.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=1, shell_class=<class 'IPython.iplib.InteractiveShell'>)

mainloop(sys_exit=0, banner=None)

IPShellEmbed

class IPython.Shell.IPShellEmbed(argv=None, banner='', exit_msg=None, rc_override=None, user_ns=None)

Allow embedding an IPython shell into a running program.

Instances of this class are callable, with the __call__ method being an alias to the embed() method of an InteractiveShell instance.

Usage (see also the example-embed.py file for a running example):

ipshell = IPShellEmbed([argv,banner,exit_msg,rc_override])

• argv: list containing valid command-line options for IPython, as they

would appear in sys.argv[1:].

For example, the following command-line options:

$ ipython -prompt_in1 ‘Input <#>’ -colors LightBG

would be passed in the argv list as:

[‘-prompt_in1’,’Input <#>’,’-colors’,’LightBG’]

• banner: string which gets printed every time the interpreter starts.
• exit_msg: string which gets printed every time the interpreter exits.
• rc_override: a dict or Struct of configuration options such as those

used by IPython. These options are read from your ~/.ipython/ipythonrc file when the Shell object is created. Passing an explicit rc_override dict with any options you want allows you to override those values at creation time without having to modify the file. This way you can create embeddable instances configured in any way you want without editing any global files (thus keeping your interactive IPython configuration unchanged).

Then the ipshell instance can be called anywhere inside your code:

ipshell(header=’‘) -> Opens up an IPython shell.

• header: string printed by the IPython shell upon startup. This can let

you know where in your code you are when dropping into the shell. Note that ‘banner’ gets prepended to all calls, so header is used for location-specific information.

For more details, see the __call__ method below.

When the IPython shell is exited with Ctrl-D, normal program execution resumes.

This functionality was inspired by a posting on comp.lang.python by cmkl <cmkleffner@gmx.de> on Dec. 06/01 concerning similar uses of pyrepl, and by the IDL stop/continue commands.

__init__(argv=None, banner='', exit_msg=None, rc_override=None, user_ns=None)

Note that argv here is a string, NOT a list.

get_dummy_mode()

Return the current value of the dummy mode parameter.

restore_system_completer()

Restores the readline completer which was in place.

This allows embedded IPython within IPython not to disrupt the parent’s completion.

set_banner(banner)

Sets the global banner.

This banner gets prepended to every header printed when the shell instance is called.

set_dummy_mode(dummy)

Sets the embeddable shell’s dummy mode parameter.

set_dummy_mode(dummy): dummy = 0 or 1.

This parameter is persistent and makes calls to the embeddable shell silently return without performing any action. This allows you to globally activate or deactivate a shell you’re using with a single call.

If you need to manually

set_exit_msg(exit_msg)

Sets the global exit_msg.

This exit message gets printed upon exiting every time the embedded shell is called. It is None by default.

IPShellGTK

class IPython.Shell.IPShellGTK(argv=None, user_ns=None, user_global_ns=None, debug=1, shell_class=<class 'IPython.Shell.MTInteractiveShell'>)

Bases: IPython.Shell.IPThread

Run a gtk mainloop() in a separate thread.

Python commands can be passed to the thread where they will be executed. This is implemented by periodically checking for passed code using a GTK timeout callback.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=1, shell_class=<class 'IPython.Shell.MTInteractiveShell'>)

mainloop(sys_exit=0, banner=None)

on_timer()

Called when GTK is idle.

Must return True always, otherwise GTK stops calling it

IPShellMatplotlib

class IPython.Shell.IPShellMatplotlib(argv=None, user_ns=None, user_global_ns=None, debug=1)

Bases: IPython.Shell.IPShell

Subclass IPShell with MatplotlibShell as the internal shell.

Single-threaded class, meant for the Tk* and FLTK* backends.

Having this on a separate class simplifies the external driver code.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=1)

IPShellMatplotlibGTK

class IPython.Shell.IPShellMatplotlibGTK(argv=None, user_ns=None, user_global_ns=None, debug=1)

Bases: IPython.Shell.IPShellGTK

Subclass IPShellGTK with MatplotlibMTShell as the internal shell.

Multi-threaded class, meant for the GTK* backends.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=1)

IPShellMatplotlibQt

class IPython.Shell.IPShellMatplotlibQt(argv=None, user_ns=None, user_global_ns=None, debug=1)

Bases: IPython.Shell.IPShellQt

Subclass IPShellQt with MatplotlibMTShell as the internal shell.

Multi-threaded class, meant for the Qt* backends.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=1)

IPShellMatplotlibQt4

class IPython.Shell.IPShellMatplotlibQt4(argv=None, user_ns=None, user_global_ns=None, debug=1)

Bases: IPython.Shell.IPShellQt4

Subclass IPShellQt4 with MatplotlibMTShell as the internal shell.

Multi-threaded class, meant for the Qt4* backends.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=1)

IPShellMatplotlibWX

class IPython.Shell.IPShellMatplotlibWX(argv=None, user_ns=None, user_global_ns=None, debug=1)

Bases: IPython.Shell.IPShellWX

Subclass IPShellWX with MatplotlibMTShell as the internal shell.

Multi-threaded class, meant for the WX* backends.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=1)

IPShellQt

class IPython.Shell.IPShellQt(argv=None, user_ns=None, user_global_ns=None, debug=0, shell_class=<class 'IPython.Shell.MTInteractiveShell'>)

Bases: IPython.Shell.IPThread

Run a Qt event loop in a separate thread.

Python commands can be passed to the thread where they will be executed. This is implemented by periodically checking for passed code using a Qt timer / slot.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=0, shell_class=<class 'IPython.Shell.MTInteractiveShell'>)

mainloop(sys_exit=0, banner=None)

on_timer()

IPShellQt4

class IPython.Shell.IPShellQt4(argv=None, user_ns=None, user_global_ns=None, debug=0, shell_class=<class 'IPython.Shell.MTInteractiveShell'>)

Bases: IPython.Shell.IPThread

Run a Qt event loop in a separate thread.

Python commands can be passed to the thread where they will be executed. This is implemented by periodically checking for passed code using a Qt timer / slot.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=0, shell_class=<class 'IPython.Shell.MTInteractiveShell'>)

mainloop(sys_exit=0, banner=None)

on_timer()

IPShellWX

class IPython.Shell.IPShellWX(argv=None, user_ns=None, user_global_ns=None, debug=1, shell_class=<class 'IPython.Shell.MTInteractiveShell'>)

Bases: IPython.Shell.IPThread

Run a wx mainloop() in a separate thread.

Python commands can be passed to the thread where they will be executed. This is implemented by periodically checking for passed code using a GTK timeout callback.

__init__(argv=None, user_ns=None, user_global_ns=None, debug=1, shell_class=<class 'IPython.Shell.MTInteractiveShell'>)

mainloop(sys_exit=0, banner=None)

wxexit(*args)

IPThread

class IPython.Shell.IPThread(group=None, target=None, name=None, args=(), kwargs=None, verbose=None)

Bases: threading.Thread

__init__(group=None, target=None, name=None, args=(), kwargs=None, verbose=None)

run()

MTInteractiveShell

class IPython.Shell.MTInteractiveShell(name, usage=None, rc=Struct({'__allownew': True, 'args': None, 'opts': None}), user_ns=None, user_global_ns=None, banner2='', gui_timeout=10, **kw)

Bases: IPython.iplib.InteractiveShell

Simple multi-threaded shell.

__init__(name, usage=None, rc=Struct({'__allownew': True, 'args': None, 'opts': None}), user_ns=None, user_global_ns=None, banner2='', gui_timeout=10, **kw)

Similar to the normal InteractiveShell, but with threading control

kill()

Kill the thread, returning when it has been shut down.

runcode()

Execute a code object.

Multithreaded wrapper around IPython’s runcode().

runsource(source, filename='<input>', symbol='single')

Compile and run some source in the interpreter.

Modified version of code.py’s runsource(), to handle threading issues. See the original for full docstring details.

MatplotlibMTShell

class IPython.Shell.MatplotlibMTShell(name, usage=None, rc=Struct({'__allownew': True, 'args': None, 'opts': None}), user_ns=None, user_global_ns=None, **kw)

Bases: IPython.Shell.MatplotlibShellBase, IPython.Shell.MTInteractiveShell

Multi-threaded shell with matplotlib support.

__init__(name, usage=None, rc=Struct({'__allownew': True, 'args': None, 'opts': None}), user_ns=None, user_global_ns=None, **kw)

MatplotlibShell

class IPython.Shell.MatplotlibShell(name, usage=None, rc=Struct({'__allownew': True, 'args': None, 'opts': None}), user_ns=None, user_global_ns=None, **kw)

Bases: IPython.Shell.MatplotlibShellBase, IPython.iplib.InteractiveShell

Single-threaded shell with matplotlib support.

__init__(name, usage=None, rc=Struct({'__allownew': True, 'args': None, 'opts': None}), user_ns=None, user_global_ns=None, **kw)

MatplotlibShellBase

class IPython.Shell.MatplotlibShellBase

Mixin class to provide the necessary modifications to regular IPython shell classes for matplotlib support.

Given Python’s MRO, this should be used as the FIRST class in the inheritance hierarchy, so that it overrides the relevant methods.

magic_run(parameter_s='')

Run the named file inside IPython as a program.

Usage:

%run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]

Parameters after the filename are passed as command-line arguments to the program (put in sys.argv). Then, control returns to IPython’s prompt.

This is similar to running at a system prompt:

$ python file args

but with the advantage of giving you IPython’s tracebacks, and of loading all variables into your interactive namespace for further use (unless -p is used, see below).

The file is executed in a namespace initially consisting only of __name__==’__main__’ and sys.argv constructed as indicated. It thus sees its environment as if it were being run as a stand-alone program (except for sharing global objects such as previously imported modules). But after execution, the IPython interactive namespace gets updated with all variables defined in the program (except for __name__ and sys.argv). This allows for very convenient loading of code for interactive work, while giving each program a ‘clean sheet’ to run in.

Options:

-n: __name__ is NOT set to ‘__main__’, but to the running file’s name without extension (as python does under import). This allows running scripts and reloading the definitions in them without calling code protected by an ‘ if __name__ == “__main__” ‘ clause.

-i: run the file in IPython’s namespace instead of an empty one. This is useful if you are experimenting with code written in a text editor which depends on variables defined interactively.

-e: ignore sys.exit() calls or SystemExit exceptions in the script being run. This is particularly useful if IPython is being used to run unittests, which always exit with a sys.exit() call. In such cases you are interested in the output of the test results, not in seeing a traceback of the unittest module.

-t: print timing information at the end of the run. IPython will give you an estimated CPU time consumption for your script, which under Unix uses the resource module to avoid the wraparound problems of time.clock(). Under Unix, an estimate of time spent on system tasks is also given (for Windows platforms this is reported as 0.0).

If -t is given, an additional -N<N> option can be given, where <N> must be an integer indicating how many times you want the script to run. The final timing report will include total and per run results.

For example (testing the script uniq_stable.py):

In [1]: run -t uniq_stable

IPython CPU timings (estimated):

User : 0.19597 s.System: 0.0 s.

In [2]: run -t -N5 uniq_stable

IPython CPU timings (estimated):Total runs performed: 5

Times : Total Per runUser : 0.910862 s, 0.1821724 s.System: 0.0 s, 0.0 s.

-d: run your program under the control of pdb, the Python debugger. This allows you to execute your program step by step, watch variables, etc. Internally, what IPython does is similar to calling:

pdb.run(‘execfile(“YOURFILENAME”)’)

with a breakpoint set on line 1 of your file. You can change the line number for this automatic breakpoint to be <N> by using the -bN option (where N must be an integer). For example:

%run -d -b40 myscript

will set the first breakpoint at line 40 in myscript.py. Note that the first breakpoint must be set on a line which actually does something (not a comment or docstring) for it to stop execution.

When the pdb debugger starts, you will see a (Pdb) prompt. You must first enter ‘c’ (without qoutes) to start execution up to the first breakpoint.

Entering ‘help’ gives information about the use of the debugger. You can easily see pdb’s full documentation with “import pdb;pdb.help()” at a prompt.

-p: run program under the control of the Python profiler module (which prints a detailed report of execution times, function calls, etc).

You can pass other options after -p which affect the behavior of the profiler itself. See the docs for %prun for details.

In this mode, the program’s variables do NOT propagate back to the IPython interactive namespace (because they remain in the namespace where the profiler executes them).

Internally this triggers a call to %prun, see its documentation for details on the options available specifically for profiling.

There is one special usage for which the text above doesn’t apply: if the filename ends with .ipy, the file is run as ipython script, just as if the commands were written on IPython prompt.

* Modified %run for Matplotlib, with proper interactive handling *

mplot_exec(fname, *where, **kw)

Execute a matplotlib script.

This is a call to execfile(), but wrapped in safeties to properly handle interactive rendering and backend switching.

Functions

IPython.Shell.get_tk()

Tries to import Tkinter and returns a withdrawn Tkinter root window. If Tkinter is already imported or not available, this returns None. This function calls hijack_tk underneath.

IPython.Shell.hijack_gtk()

Modifies pyGTK’s mainloop with a dummy so user code does not block IPython. This function returns the original gtk.mainloop function that has been hijacked.

IPython.Shell.hijack_qt()

Modifies PyQt’s mainloop with a dummy so user code does not block IPython. This function returns the original qt.qApp.exec_loop function that has been hijacked.

IPython.Shell.hijack_qt4()

Modifies PyQt4’s mainloop with a dummy so user code does not block IPython. This function returns the original QtGui.qApp.exec_ function that has been hijacked.

IPython.Shell.hijack_tk()

Modifies Tkinter’s mainloop with a dummy so when a module calls mainloop, it does not block.

IPython.Shell.hijack_wx()

Modifies wxPython’s MainLoop with a dummy so user code does not block IPython. The hijacked mainloop function is returned.

IPython.Shell.kill_embedded(self, parameter_s='')

%kill_embedded : deactivate for good the current embedded IPython.

This function (after asking for confirmation) sets an internal flag so that an embedded IPython will never activate again. This is useful to permanently disable a shell that is being called inside a loop: once you’ve figured out what you needed from it, you may then kill it and the program will then continue to run without the interactive shell interfering again.

IPython.Shell.start(user_ns=None)

Return a running shell instance, dealing with threading options.

This is a factory function which will instantiate the proper IPython shell based on the user’s threading choice. Such a selector is needed because different GUI toolkits require different thread handling details.

IPython.Shell.update_tk(tk)

Updates the Tkinter event loop. This is typically called from the respective WX or GTK mainloops.