|
|
#!/usr/bin/env python
|
|
|
|
|
|
"""An example of how to embed an IPython shell into a running program.
|
|
|
|
|
|
Please see the documentation in the IPython.Shell module for more details.
|
|
|
|
|
|
The accompanying file example-embed-short.py has quick code fragments for
|
|
|
embedding which you can cut and paste in your code once you understand how
|
|
|
things work.
|
|
|
|
|
|
The code in this file is deliberately extra-verbose, meant for learning."""
|
|
|
|
|
|
# The basics to get you going:
|
|
|
|
|
|
# IPython sets the __IPYTHON__ variable so you can know if you have nested
|
|
|
# copies running.
|
|
|
|
|
|
# Try running this code both at the command line and from inside IPython (with
|
|
|
# %run example-embed.py)
|
|
|
try:
|
|
|
__IPYTHON__
|
|
|
except NameError:
|
|
|
nested = 0
|
|
|
args = ['']
|
|
|
else:
|
|
|
print "Running nested copies of IPython."
|
|
|
print "The prompts for the nested copy have been modified"
|
|
|
nested = 1
|
|
|
# what the embedded instance will see as sys.argv:
|
|
|
args = ['-pi1','In <\\#>:','-pi2',' .\\D.:','-po','Out<\\#>:','-nosep']
|
|
|
|
|
|
# First import the embeddable shell class
|
|
|
from IPython.Shell import IPShellEmbed
|
|
|
|
|
|
# Now create an instance of the embeddable shell. The first argument is a
|
|
|
# string with options exactly as you would type them if you were starting
|
|
|
# IPython at the system command line. Any parameters you want to define for
|
|
|
# configuration can thus be specified here.
|
|
|
ipshell = IPShellEmbed(args,
|
|
|
banner = 'Dropping into IPython',
|
|
|
exit_msg = 'Leaving Interpreter, back to program.')
|
|
|
|
|
|
# Make a second instance, you can have as many as you want.
|
|
|
if nested:
|
|
|
args[1] = 'In2<\\#>'
|
|
|
else:
|
|
|
args = ['-pi1','In2<\\#>:','-pi2',' .\\D.:','-po','Out<\\#>:','-nosep']
|
|
|
ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
|
|
|
|
|
|
print '\nHello. This is printed from the main controller program.\n'
|
|
|
|
|
|
# You can then call ipshell() anywhere you need it (with an optional
|
|
|
# message):
|
|
|
ipshell('***Called from top level. '
|
|
|
'Hit Ctrl-D to exit interpreter and continue program.')
|
|
|
|
|
|
print '\nBack in caller program, moving along...\n'
|
|
|
|
|
|
#---------------------------------------------------------------------------
|
|
|
# More details:
|
|
|
|
|
|
# IPShellEmbed instances don't print the standard system banner and
|
|
|
# messages. The IPython banner (which actually may contain initialization
|
|
|
# messages) is available as <instance>.IP.BANNER in case you want it.
|
|
|
|
|
|
# IPShellEmbed instances print the following information everytime they
|
|
|
# start:
|
|
|
|
|
|
# - A global startup banner.
|
|
|
|
|
|
# - A call-specific header string, which you can use to indicate where in the
|
|
|
# execution flow the shell is starting.
|
|
|
|
|
|
# They also print an exit message every time they exit.
|
|
|
|
|
|
# Both the startup banner and the exit message default to None, and can be set
|
|
|
# either at the instance constructor or at any other time with the
|
|
|
# set_banner() and set_exit_msg() methods.
|
|
|
|
|
|
# The shell instance can be also put in 'dummy' mode globally or on a per-call
|
|
|
# basis. This gives you fine control for debugging without having to change
|
|
|
# code all over the place.
|
|
|
|
|
|
# The code below illustrates all this.
|
|
|
|
|
|
|
|
|
# This is how the global banner and exit_msg can be reset at any point
|
|
|
ipshell.set_banner('Entering interpreter - New Banner')
|
|
|
ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
|
|
|
|
|
|
def foo(m):
|
|
|
s = 'spam'
|
|
|
ipshell('***In foo(). Try @whos, or print s or m:')
|
|
|
print 'foo says m = ',m
|
|
|
|
|
|
def bar(n):
|
|
|
s = 'eggs'
|
|
|
ipshell('***In bar(). Try @whos, or print s or n:')
|
|
|
print 'bar says n = ',n
|
|
|
|
|
|
# Some calls to the above functions which will trigger IPython:
|
|
|
print 'Main program calling foo("eggs")\n'
|
|
|
foo('eggs')
|
|
|
|
|
|
# The shell can be put in 'dummy' mode where calls to it silently return. This
|
|
|
# allows you, for example, to globally turn off debugging for a program with a
|
|
|
# single call.
|
|
|
ipshell.set_dummy_mode(1)
|
|
|
print '\nTrying to call IPython which is now "dummy":'
|
|
|
ipshell()
|
|
|
print 'Nothing happened...'
|
|
|
# The global 'dummy' mode can still be overridden for a single call
|
|
|
print '\nOverriding dummy mode manually:'
|
|
|
ipshell(dummy=0)
|
|
|
|
|
|
# Reactivate the IPython shell
|
|
|
ipshell.set_dummy_mode(0)
|
|
|
|
|
|
print 'You can even have multiple embedded instances:'
|
|
|
ipshell2()
|
|
|
|
|
|
print '\nMain program calling bar("spam")\n'
|
|
|
bar('spam')
|
|
|
|
|
|
print 'Main program finished. Bye!'
|
|
|
|
|
|
#********************** End of file <example-embed.py> ***********************
|
|
|
|
