Warning

This documentation is for an old version of IPython. You can find docs for newer versions here.

Module: terminal.embed

An embedded IPython shell.

Authors:

• Brian Granger
• Fernando Perez

Notes

2 Classes

class IPython.terminal.embed.EmbeddedMagics(shell)

Bases: IPython.core.magic.Magics

kill_embedded(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.

class IPython.terminal.embed.InteractiveShellEmbed(config=None, ipython_dir=None, user_ns=None, user_module=None, custom_exceptions=((), None), usage=None, banner1=None, banner2=None, display_banner=None, exit_msg=u'', user_global_ns=None)

Bases: IPython.terminal.interactiveshell.TerminalInteractiveShell

__init__(config=None, ipython_dir=None, user_ns=None, user_module=None, custom_exceptions=((), None), usage=None, banner1=None, banner2=None, display_banner=None, exit_msg=u'', user_global_ns=None)

mainloop(local_ns=None, module=None, stack_depth=0, display_banner=None, global_ns=None, compile_flags=None)

Embeds IPython into a running python program.

Input:

• header: An optional header message can be specified.
• local_ns, module: working local namespace (a dict) and module (a

module or similar object). If given as None, they are automatically taken from the scope where the shell was called, so that program variables become visible.

• stack_depth: specifies how many levels in the stack to go to

looking for namespaces (when local_ns or module is None). This allows an intermediate caller to make sure that this function gets the namespace from the intended level in the stack. By default (0) it will get its locals and globals from the immediate caller.

• compile_flags: A bit field identifying the __future__ features

that are enabled, as passed to the builtin compile function. If given as None, they are automatically taken from the scope where the shell was called.

Warning: it’s possible to use this in a program which is being run by IPython itself (via %run), but some funny things will happen (a few globals get overwritten). In the future this will be cleaned up, as there is no fundamental reason why it can’t work perfectly.

1 Function

IPython.terminal.embed.embed(**kwargs)

Call this to embed IPython at the current point in your program.

The first invocation of this will create an InteractiveShellEmbed instance and then call it. Consecutive calls just call the already created instance.

If you don’t want the kernel to initialize the namespace from the scope of the surrounding function, and/or you want to load full IPython configuration, you probably want IPython.start_ipython() instead.

Here is a simple example:

from IPython import embed
a = 10
b = 20
embed('First time')
c = 30
d = 40
embed

Full customization can be done by passing a Config in as the config argument.