diff --git a/docs/examples/core/example-embed-short.py b/docs/examples/core/example-embed-short.py index 4b2e735..cc5824d 100644 --- a/docs/examples/core/example-embed-short.py +++ b/docs/examples/core/example-embed-short.py @@ -8,29 +8,28 @@ cut and paste use once you understand how to use the system.""" # embedded in another IPython session (helps avoid confusion) try: - __IPYTHON__ + get_ipython except NameError: - argv = [''] - banner = exit_msg = '' + banner=exit_msg='' else: - # Command-line options for IPython (a list like sys.argv) - argv = ['-pi1','In <\\#>:','-pi2',' .\\D.:','-po','Out<\\#>:'] banner = '*** Nested interpreter ***' exit_msg = '*** Back in main IPython ***' -# First import the embeddable shell class -from IPython.Shell import IPShellEmbed +# First import the embed function +from IPython.frontend.terminal.embed import InteractiveShellEmbed # Now create the IPython shell instance. Put ipshell() anywhere in your code # where you want it to open. -ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg) +ipshell = InteractiveShellEmbed(banner1=banner, exit_msg=exit_msg) #--------------------------------------------------------------------------- # This code will load an embeddable IPython shell always with no changes for # nested embededings. -from IPython.Shell import IPShellEmbed -ipshell = IPShellEmbed() -# Now ipshell() will open IPython anywhere in the code. +# This code will load an embeddable IPython shell always with no changes for +# nested embededings. + +from IPython import embed +# Now embed() will open IPython anywhere in the code. #--------------------------------------------------------------------------- # This code loads an embeddable shell only if NOT running inside @@ -38,10 +37,10 @@ ipshell = IPShellEmbed() # dummy function. try: - __IPYTHON__ + get_ipython except NameError: - from IPython.Shell import IPShellEmbed - ipshell = IPShellEmbed() + from IPython.frontend.terminal.embed import InteractiveShellEmbed + ipshell = InteractiveShellEmbed() # Now ipshell() will open IPython anywhere in the code else: # Define a dummy ipshell() so the same code doesn't crash inside an diff --git a/docs/examples/core/example-embed.py b/docs/examples/core/example-embed.py index 3c451ef..a384e5b 100755 --- a/docs/examples/core/example-embed.py +++ b/docs/examples/core/example-embed.py @@ -17,37 +17,43 @@ The code in this file is deliberately extra-verbose, meant for learning.""" # Try running this code both at the command line and from inside IPython (with # %run example-embed.py) +from IPython.config.loader import Config try: - __IPYTHON__ + get_ipython except NameError: nested = 0 - args = [''] + cfg = Config() + shell_config = cfg.InteractiveShellEmbed + shell_config.prompt_in1 = 'In <\\#>: ' + shell_config.prompt_in2 = ' .\\D.: ' + shell_config.prompt_out = 'Out<\\#>: ' else: print "Running nested copies of IPython." print "The prompts for the nested copy have been modified" + cfg = Config() 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.core.shell import IPShellEmbed +from IPython.frontend.terminal.embed import InteractiveShellEmbed # 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', +ipshell = InteractiveShellEmbed(config=cfg, + banner1 = '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.') +cfg2 = cfg.copy() +shell_config = cfg2.InteractiveShellEmbed +shell_config.prompt_in1 = 'In2<\\#>: ' +if not nested: + shell_config.prompt_in1 = 'In2<\\#>: ' + shell_config.prompt_in2 = ' .\\D.: ' + shell_config.prompt_out = 'Out<\\#>: ' +ipshell2 = InteractiveShellEmbed(config=cfg, + banner1 = 'Second IPython instance.') print '\nHello. This is printed from the main controller program.\n' @@ -63,11 +69,11 @@ print '\nBack in caller program, moving along...\n' #--------------------------------------------------------------------------- # More details: -# IPShellEmbed instances don't print the standard system banner and +# InteractiveShellEmbed instances don't print the standard system banner and # messages. The IPython banner (which actually may contain initialization -# messages) is available as .IP.BANNER in case you want it. +# messages) is available as get_ipython().banner in case you want it. -# IPShellEmbed instances print the following information everytime they +# InteractiveShellEmbed instances print the following information everytime they # start: # - A global startup banner. @@ -79,7 +85,7 @@ print '\nBack in caller program, moving along...\n' # 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. +# by setting the banner and exit_msg attributes. # 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 @@ -89,17 +95,17 @@ print '\nBack in caller program, moving along...\n' # 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') +ipshell.banner = 'Entering interpreter - New Banner' +ipshell.exit_msg = 'Leaving interpreter - New exit_msg' def foo(m): s = 'spam' - ipshell('***In foo(). Try @whos, or print s or m:') + 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:') + 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: @@ -109,16 +115,16 @@ 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) +ipshell.dummy_mode = True 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) +ipshell(dummy=False) # Reactivate the IPython shell -ipshell.set_dummy_mode(0) +ipshell.dummy_mode = False print 'You can even have multiple embedded instances:' ipshell2() diff --git a/docs/examples/core/new-embed.py b/docs/examples/core/new-embed.py index f0eddf5..cc9ff4e 100644 --- a/docs/examples/core/new-embed.py +++ b/docs/examples/core/new-embed.py @@ -6,7 +6,7 @@ from IPython import embed a = 10 b = 20 -embed('First time') +embed(header='First time', banner1='') c = 30 d = 40 @@ -14,4 +14,4 @@ d = 40 try: raise Exception('adsfasdf') except: - embed('The second time') + embed(header='The second time') diff --git a/docs/source/interactive/reference.txt b/docs/source/interactive/reference.txt index c09d9be..c7898f2 100644 --- a/docs/source/interactive/reference.txt +++ b/docs/source/interactive/reference.txt @@ -166,9 +166,9 @@ All options with a [no] prepended can be specified in negated form logfile as a file to be executed with option -logplay (see below). - -logfile, lf specify the name of your logfile. + logfile= specify the name of your logfile. - -logplay, lp + logplay= you can replay a previous log. For restoring a session as close as possible to the state you left it in, use this option (don't just run @@ -201,10 +201,6 @@ All options with a [no] prepended can be specified in negated form IPython or in code called by it) which triggers an exception which goes uncaught. - --pydb - Makes IPython use the third party "pydb" package as debugger, - instead of pdb. Requires that pydb is installed. - --[no-]pprint ipython can optionally use the pprint (pretty printer) module for displaying results. pprint tends to give a nicer display @@ -213,24 +209,24 @@ All options with a [no] prepended can be specified in negated form profile= - assume that your config file is ipythonrc- or - ipy_profile_.py (looks in current dir first, then in - IPYTHON_DIR). This is a quick way to keep and load multiple + Select the IPython profile by name. + + This is a quick way to keep and load multiple config files for different tasks, especially if you use the include option of config files. You can keep a basic IPYTHON_DIR/ipythonrc file and then have other 'profiles' which include this one and load extra things for particular tasks. For example: - 1. $IPYTHON_DIR/ipythonrc : load basic things you always want. - 2. $IPYTHON_DIR/ipythonrc-math : load (1) and basic math-related modules. - 3. $IPYTHON_DIR/ipythonrc-numeric : load (1) and Numeric and plotting modules. + 1. $IPYTHON_DIR/profile_default : load basic things you always want. + 2. $IPYTHON_DIR/profile_math : load (1) and basic math-related modules. + 3. $IPYTHON_DIR/profile_numeric : load (1) and Numeric and plotting modules. Since it is possible to create an endless loop by having circular file inclusions, IPython will stop if it reaches 15 recursive inclusions. - pi1= + InteractiveShell.prompt_in1= Specify the string used for input prompts. Note that if you are using numbered prompts, the number is represented with a '\#' in the @@ -239,7 +235,7 @@ All options with a [no] prepended can be specified in negated form discusses in detail all the available escapes to customize your prompts. - pi2= + InteractiveShell.prompt_in2= Similar to the previous option, but used for the continuation prompts. The special sequence '\D' is similar to '\#', but with all digits replaced dots (so you can have your @@ -247,7 +243,7 @@ All options with a [no] prepended can be specified in negated form ' .\D.:' (note three spaces at the start for alignment with 'In [\#]'). - po= + InteractiveShell.prompt_out= String used for output prompts, also uses numbers like prompt_in1. Default: 'Out[\#]:' @@ -272,7 +268,7 @@ All options with a [no] prepended can be specified in negated form IPython's readline and syntax coloring fine, only 'emacs' (M-x shell and C-c !) buffers do not. - sl= + TerminalInteractiveShell.screen_length= number of lines of your screen. This is used to control printing of very long strings. Strings longer than this number of lines will be sent through a pager instead of directly @@ -285,34 +281,31 @@ All options with a [no] prepended can be specified in negated form reason this isn't working well (it needs curses support), specify it yourself. Otherwise don't change the default. - si= + TerminalInteractiveShell.separate_in= separator before input prompts. Default: '\n' - so= + TerminalInteractiveShell.separate_out= separator before output prompts. Default: nothing. - so2= + TerminalInteractiveShell.separate_out2= separator after output prompts. Default: nothing. For these three options, use the value 0 to specify no separator. --nosep - shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2 - 0'. Simply removes all input/output separators. + shorthand for setting the above separators to empty strings. + + Simply removes all input/output separators. --init - allows you to initialize your IPYTHON_DIR configuration when you - install a new version of IPython. Since new versions may - include new command line options or example files, this copies - updated config files. However, it backs up (with a - .old extension) all files which it overwrites so that you can - merge back any customizations you might have in your personal - files. Note that you should probably use %upgrade instead, - it's a safer alternative. - + allows you to initialize a profile dir for configuration when you + install a new version of IPython or want to use a new profile. + Since new versions may include new command line options or example + files, this copies updated config files. Note that you should probably + use %upgrade instead,it's a safer alternative. --version print version information and exit. @@ -337,11 +330,7 @@ All options with a [no] prepended can be specified in negated form Interactive use =============== -Warning: IPython relies on the existence of a global variable called -_ip which controls the shell itself. If you redefine _ip to anything, -bizarre behavior will quickly occur. - -Other than the above warning, IPython is meant to work as a drop-in +IPython is meant to work as a drop-in replacement for the standard interactive interpreter. As such, any code which is valid python should execute normally under IPython (cases where this is not true should be reported as bugs). It does, however, offer @@ -384,7 +373,9 @@ an identifier with the same name as an existing magic function will shadow it for automagic use. You can still access the shadowed magic function by explicitly using the % character at the beginning of the line. -An example (with automagic on) should clarify all this:: +An example (with automagic on) should clarify all this: + +.. sourcecode:: ipython In [1]: cd ipython # %cd is called by automagic @@ -415,11 +406,11 @@ An example (with automagic on) should clarify all this:: /home/fperez/ipython You can define your own magic functions to extend the system. The -following example defines a new magic command, %impall:: +following example defines a new magic command, %impall: - import IPython.ipapi +.. sourcecode:: python - ip = IPython.ipapi.get() + ip = get_ipython() def doimp(self, arg): @@ -433,20 +424,13 @@ following example defines a new magic command, %impall:: ip.expose_magic('impall', doimp) -You can also define your own aliased names for magic functions. In your -ipythonrc file, placing a line like:: - - execute __IP.magic_cl = __IP.magic_clear - -will define %cl as a new name for %clear. - Type %magic for more information, including a list of all available magic functions at any time and their docstrings. You can also type %magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for information on the '?' system) to get information about any particular magic function you are interested in. -The API documentation for the :mod:`IPython.Magic` module contains the full +The API documentation for the :mod:`IPython.core.magic` module contains the full docstrings of all currently available magic commands. @@ -543,8 +527,7 @@ Persistent command history across sessions IPython will save your input history when it leaves and reload it next time you restart it. By default, the history file is named -$IPYTHON_DIR/history, but if you've loaded a named profile, -'-PROFILE_NAME' is appended to the name. This allows you to keep +$IPYTHON_DIR/profile_/history.sqlite. This allows you to keep separate histories related to various tasks: commands related to numerical work will not be clobbered by a system shell history, for example. @@ -568,11 +551,17 @@ more convenient (M-i indents, M-u unindents):: Note that there are 4 spaces between the quote marks after "M-i" above. -Warning: this feature is ON by default, but it can cause problems with -the pasting of multi-line indented code (the pasted code gets -re-indented on each line). A magic function %autoindent allows you to -toggle it on/off at runtime. You can also disable it permanently on in -your ipythonrc file (set autoindent 0). +.. warning:: + + Setting the above indents will cause problems with unicode text entry in the terminal. + +.. warning:: + + This feature is ON by default, but it can cause problems with + the pasting of multi-line indented code (the pasted code gets + re-indented on each line). A magic function %autoindent allows you to + toggle it on/off at runtime. You can also disable it permanently on in + your :file:`ipython_config.py` file (set TerminalInteractiveShell.autoindent=False). Customizing readline behavior @@ -967,11 +956,12 @@ Python honors the environment variable PYTHONSTARTUP and will execute at startup the file referenced by this variable. If you put at the end of this file the following two lines of code:: - import IPython - IPython.Shell.IPShell().mainloop(sys_exit=1) + from IPython.frontend.terminal.ipapp import launch_new_instance + launch_new_instance() + raise SystemExit then IPython will be your working environment anytime you start Python. -The sys_exit=1 is needed to have IPython issue a call to sys.exit() when +The ``raise SystemExit`` is needed to exit Python when it finishes, otherwise you'll be back at the normal Python '>>>' prompt. @@ -1009,11 +999,9 @@ needed). The following code snippet is the bare minimum you need to include in your Python programs for this to work (detailed examples follow later):: - from IPython.Shell import IPShellEmbed + from IPython import embed - ipshell = IPShellEmbed() - - ipshell() # this call anywhere in your program will start IPython + embed() # this call anywhere in your program will start IPython You can run embedded instances even in code which is itself being run at the IPython interactive prompt with '%run '. Since it's easy @@ -1027,13 +1015,14 @@ them separately, for example with different options for data presentation. If you close and open the same instance multiple times, its prompt counters simply continue from each execution to the next. -Please look at the docstrings in the Shell.py module for more details on -the use of this system. +Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed` +module for more details on the use of this system. The following sample file illustrating how to use the embedding functionality is provided in the examples directory as example-embed.py. -It should be fairly self-explanatory:: +It should be fairly self-explanatory: +.. sourcecode:: python #!/usr/bin/env python @@ -1054,37 +1043,43 @@ It should be fairly self-explanatory:: # Try running this code both at the command line and from inside IPython (with # %run example-embed.py) + from IPython.config.loader import Config try: - __IPYTHON__ + get_ipython except NameError: nested = 0 - args = [''] + cfg = Config() + shell_config = cfg.InteractiveShellEmbed + shell_config.prompt_in1 = 'In <\\#>: ' + shell_config.prompt_in2 = ' .\\D.: ' + shell_config.prompt_out = 'Out<\\#>: ' else: print "Running nested copies of IPython." print "The prompts for the nested copy have been modified" + cfg = Config() 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 + from IPython.frontend.terminal.embed import InteractiveShellEmbed # 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', + ipshell = InteractiveShellEmbed(config=cfg, + banner1 = '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.') + cfg2 = cfg.copy() + shell_config = cfg2.InteractiveShellEmbed + shell_config.prompt_in1 = 'In2<\\#>: ' + if not nested: + shell_config.prompt_in1 = 'In2<\\#>: ' + shell_config.prompt_in2 = ' .\\D.: ' + shell_config.prompt_out = 'Out<\\#>: ' + ipshell2 = InteractiveShellEmbed(config=cfg, + banner1 = 'Second IPython instance.') print '\nHello. This is printed from the main controller program.\n' @@ -1100,11 +1095,11 @@ It should be fairly self-explanatory:: #--------------------------------------------------------------------------- # More details: - # IPShellEmbed instances don't print the standard system banner and + # InteractiveShellEmbed instances don't print the standard system banner and # messages. The IPython banner (which actually may contain initialization - # messages) is available as .IP.BANNER in case you want it. + # messages) is available as get_ipython().banner in case you want it. - # IPShellEmbed instances print the following information everytime they + # InteractiveShellEmbed instances print the following information everytime they # start: # - A global startup banner. @@ -1116,7 +1111,7 @@ It should be fairly self-explanatory:: # 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. + # by setting the banner and exit_msg attributes. # 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 @@ -1126,17 +1121,17 @@ It should be fairly self-explanatory:: # 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') + ipshell.banner = 'Entering interpreter - New Banner' + ipshell.exit_msg = 'Leaving interpreter - New exit_msg' def foo(m): s = 'spam' - ipshell('***In foo(). Try @whos, or print s or m:') + 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:') + 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: @@ -1146,16 +1141,16 @@ It should be fairly self-explanatory:: # 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) + ipshell.dummy_mode = True 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) + ipshell(dummy=False) # Reactivate the IPython shell - ipshell.set_dummy_mode(0) + ipshell.dummy_mode = False print 'You can even have multiple embedded instances:' ipshell2() @@ -1168,8 +1163,9 @@ It should be fairly self-explanatory:: #********************** End of file *********************** Once you understand how the system functions, you can use the following -code fragments in your programs which are ready for cut and paste:: +code fragments in your programs which are ready for cut and paste: +.. sourcecode:: python """Quick code snippets for embedding IPython into other programs. @@ -1181,7 +1177,7 @@ code fragments in your programs which are ready for cut and paste:: # embedded in another IPython session (helps avoid confusion) try: - __IPYTHON__ + get_ipython except NameError: argv = [''] banner = exit_msg = '' @@ -1201,9 +1197,8 @@ code fragments in your programs which are ready for cut and paste:: # This code will load an embeddable IPython shell always with no changes for # nested embededings. - from IPython.Shell import IPShellEmbed - ipshell = IPShellEmbed() - # Now ipshell() will open IPython anywhere in the code. + from IPython import embed + # Now embed() will open IPython anywhere in the code. #--------------------------------------------------------------------------- # This code loads an embeddable shell only if NOT running inside @@ -1211,15 +1206,14 @@ code fragments in your programs which are ready for cut and paste:: # dummy function. try: - __IPYTHON__ + get_ipython except NameError: - from IPython.Shell import IPShellEmbed - ipshell = IPShellEmbed() - # Now ipshell() will open IPython anywhere in the code + from IPython.frontend.terminal.embed import embed + # Now embed() will open IPython anywhere in the code else: - # Define a dummy ipshell() so the same code doesn't crash inside an + # Define a dummy embed() so the same code doesn't crash inside an # interactive IPython - def ipshell(): pass + def embed(): pass #******************* End of file ******************** @@ -1266,7 +1260,7 @@ the origin of the problem. Furthermore, you can use these debugging facilities both with the embedded IPython mode and without IPython at all. For an embedded shell (see sec. Embedding_), simply call the constructor with -'-pdb' in the argument string and automatically pdb will be called if an +'--pdb' in the argument string and automatically pdb will be called if an uncaught exception is triggered by your code. For stand-alone use of the feature in your programs which do not use