Update docs about embedding.

IPython/frontend/terminal/embed.py

@@ -1,274 +1,271 b''
 # encoding: utf-8
 """
 An embedded IPython shell.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 
 Notes
 -----
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from __future__ import with_statement
 import __main__
 
 import sys
 try:
     from contextlib import nested
 except:
     from IPython.utils.nested_context import nested
 import warnings
 
 from IPython.core import ultratb
 from IPython.frontend.terminal.interactiveshell import TerminalInteractiveShell
 from IPython.frontend.terminal.ipapp import load_default_config
 
 from IPython.utils.traitlets import Bool, CBool, Unicode
 from IPython.utils.io import ask_yes_no
 
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 # This is an additional magic that is exposed in embedded shells.
 def 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.
     """
 
     kill = ask_yes_no("Are you sure you want to kill this embedded instance "
                      "(y/n)? [y/N] ",'n')
     if kill:
         self.embedded_active = False
         print "This embedded IPython will not reactivate anymore once you exit."
 
 
 class InteractiveShellEmbed(TerminalInteractiveShell):
 
     dummy_mode = Bool(False)
     exit_msg = Unicode('')
     embedded = CBool(True)
     embedded_active = CBool(True)
     # Like the base class display_banner is not configurable, but here it
     # is True by default.
     display_banner = CBool(True)
 
     def __init__(self, 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):
     
         if user_global_ns is not None:
             warnings.warn("user_global_ns has been replaced by user_module. The\
                            parameter will be ignored.", DeprecationWarning)
 
         super(InteractiveShellEmbed,self).__init__(
             config=config, ipython_dir=ipython_dir, user_ns=user_ns,
             user_module=user_module, custom_exceptions=custom_exceptions,
             usage=usage, banner1=banner1, banner2=banner2,
             display_banner=display_banner
         )
 
         self.exit_msg = exit_msg
         self.define_magic("kill_embedded", kill_embedded)
 
         # don't use the ipython crash handler so that user exceptions aren't
         # trapped
         sys.excepthook = ultratb.FormattedTB(color_scheme=self.colors,
                                              mode=self.xmode,
                                              call_pdb=self.pdb)
 
     def init_sys_modules(self):
         pass
 
     def __call__(self, header='', local_ns=None, module=None, dummy=None,
                  stack_depth=1, global_ns=None):
         """Activate the interactive interpreter.
 
-        __call__(self,header='',local_ns=None,global_ns,dummy=None) -> Start
+        __call__(self,header='',local_ns=None,module=None,dummy=None) -> Start
         the interpreter shell with the given local and global namespaces, and
         optionally print a header string at startup.
 
         The shell can be globally activated/deactivated using the
-        set/get_dummy_mode methods. This allows you to turn off a shell used
+        dummy_mode attribute. This allows you to turn off a shell used
         for debugging globally.
 
         However, *each* time you call the shell you can override the current
         state of dummy_mode with the optional keyword parameter 'dummy'. For
-        example, if you set dummy mode on with IPShell.set_dummy_mode(1), you
-        can still have a specific call work by making it as IPShell(dummy=0).
-
-        The optional keyword parameter dummy controls whether the call
-        actually does anything.
+        example, if you set dummy mode on with IPShell.dummy_mode = True, you
+        can still have a specific call work by making it as IPShell(dummy=False).
         """
 
         # If the user has turned it off, go away
         if not self.embedded_active:
             return
 
         # Normal exits from interactive mode set this flag, so the shell can't
         # re-enter (it checks this variable at the start of interactive mode).
         self.exit_now = False
 
         # Allow the dummy parameter to override the global __dummy_mode
         if dummy or (dummy != 0 and self.dummy_mode):
             return
 
         if self.has_readline:
             self.set_readline_completer()
 
         # self.banner is auto computed
         if header:
             self.old_banner2 = self.banner2
             self.banner2 = self.banner2 + '\n' + header + '\n'
         else:
             self.old_banner2 = ''
 
         # Call the embedding code with a stack depth of 1 so it can skip over
         # our call and get the original caller's namespaces.
         self.mainloop(local_ns, module, stack_depth=stack_depth, global_ns=global_ns)
 
         self.banner2 = self.old_banner2
 
         if self.exit_msg is not None:
             print self.exit_msg
 
     def mainloop(self, local_ns=None, module=None, stack_depth=0,
                  display_banner=None, global_ns=None):
         """Embeds IPython into a running python program.
 
         Input:
 
           - header: An optional header message can be specified.
 
-          - local_ns, global_ns: working namespaces. If given as None, the
-          IPython-initialized one is updated with __main__.__dict__, so that
-          program variables become visible but user-specific configuration
-          remains possible.
+          - 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 and global_ns are None).  This
+          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.
 
         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."""
         
         if (global_ns is not None) and (module is None):
             class DummyMod(object):
                 """A dummy module object for embedded IPython."""
                 pass
             warnings.warn("global_ns is deprecated, use module instead.", DeprecationWarning)
             module = DummyMod()
             module.__dict__ = global_ns
 
         # Get locals and globals from caller
         if (local_ns is None or module is None) and self.default_user_namespaces:
             call_frame = sys._getframe(stack_depth).f_back
 
             if local_ns is None:
                 local_ns = call_frame.f_locals
             if module is None:
                 global_ns = call_frame.f_globals
                 module = sys.modules[global_ns['__name__']]
         
         # Save original namespace and module so we can restore them after 
         # embedding; otherwise the shell doesn't shut down correctly.
         orig_user_module = self.user_module
         orig_user_ns = self.user_ns
         
         # Update namespaces and fire up interpreter
         
         # The global one is easy, we can just throw it in
         if module is not None:
             self.user_module = module
 
         # But the user/local one is tricky: ipython needs it to store internal
         # data, but we also need the locals. We'll throw our hidden variables
         # like _ih and get_ipython() into the local namespace, but delete them
         # later.
         if local_ns is not None:
             self.user_ns = local_ns
             self.init_user_ns()
 
         # Patch for global embedding to make sure that things don't overwrite
         # user globals accidentally. Thanks to Richard <[e-mail]>
         # FIXME. Test this a bit more carefully (the if.. is new)
         # N.B. This can't now ever be called. Not sure what it was for.
         # And now, since it wasn't called in the previous version, I'm
         # commenting out these lines so they can't be called with my new changes
         # --TK, 2011-12-10
         #if local_ns is None and module is None:
         #    self.user_global_ns.update(__main__.__dict__)
 
         # make sure the tab-completer has the correct frame information, so it
         # actually completes using the frame's locals/globals
         self.set_completer_frame()
 
         with nested(self.builtin_trap, self.display_trap):
             self.interact(display_banner=display_banner)
         
         # now, purge out the local namespace of IPython's hidden variables.
         if local_ns is not None:
             for name in self.user_ns_hidden:
                 local_ns.pop(name, None)
         
         # Restore original namespace so shell can shut down when we exit.
         self.user_module = orig_user_module
         self.user_ns = orig_user_ns
 
 _embedded_shell = None
 
 
 def embed(**kwargs):
     """Call this to embed IPython at the current point in your program.
 
     The first invocation of this will create an :class:`InteractiveShellEmbed`
     instance and then call it.  Consecutive calls just call the already
     created instance.
 
     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 :class:`Struct` in as the
     config argument.
     """
     config = kwargs.get('config')
     header = kwargs.pop('header', u'')
     if config is None:
         config = load_default_config()
         config.InteractiveShellEmbed = config.TerminalInteractiveShell
         kwargs['config'] = config
     global _embedded_shell
     if _embedded_shell is None:
         _embedded_shell = InteractiveShellEmbed(**kwargs)
     _embedded_shell(header=header, stack_depth=2)

docs/source/whatsnew/development.txt

@@ -1,154 +1,156 b''
 ================================================
 Development version
 ================================================
 
 The changes listed here are a brief summary of the substantial work on IPython
 since the 0.11.x release series. For more details, please consult the actual
 source.
 
 Main `ipython` branch
 =====================
 
 
 New features
 ------------
 
 .. Expand on this:
 * **HTML Notebook**: A powerful new interface puts IPython in your browser. You
   can start it with the command ``ipython notebook``. See :ref:`the Notebook
   docs <htmlnotebook>` for technical details.
 
 * **Tabbed QtConsole**: The QtConsole now supports starting multiple kernels in
   tabs, and has a menubar, so it looks and behaves more like a real application.
   Keyboard enthusiasts can disable the menubar with ctrl-shift-M (:ghpull:`887`).
 
 * **Python 3 compatibility**: IPython can now be installed from a single
   codebase on Python 2 and Python 3. The installation process for Python 3
   automatically runs 2to3. The same 'default' profile is now used for
   Python 2 and 3 (the previous version had a separate 'python3' profile).
 
 * **PyPy support**: The terminal interface to IPython now runs under
   `PyPy <http://pypy.org/>`_.
 
 * **SSH Tunnels**: In 0.11, the :mod:`IPython.parallel` Client could tunnel its
   connections to the Controller via ssh. Now, the QtConsole :ref:`supports
   <ssh_tunnels>` ssh tunneling, as do parallel engines.
 
 * **relaxed command-line parsing**: 0.11 was released with overly-strict
   command-line parsing, preventing the ability to specify arguments with spaces,
   e.g. ``ipython --pylab qt`` or ``ipython -c "print 'hi'"``. This has
   been fixed, by using argparse. The new parsing is a strict superset of 0.11, so
   any commands in 0.11 should still work in 0.12.
 
 * **HistoryAccessor**: The :class:`~IPython.core.history.HistoryManager` class for
   interacting with your IPython SQLite history database has been split, adding
   a parent :class:`~IPython.core.history.HistoryAccessor` class, so that users can
   write code to access and search their IPython history without being in an IPython
   session (:ghpull:`824`).
 
 * **kernel %gui and %pylab**: The ``%gui`` and ``%pylab`` magics have been restored
   to the IPython kernel (e.g. in the qtconsole or notebook). This allows activation
   of pylab-mode, or eventloop integration after starting the kernel, which was
   unavailable in 0.11.  Unlike in the terminal, this can be set only once, and
   cannot be changed.
 
 * **%config**: A new ``%config`` magic has been added, giving easy access to the
   IPython configuration system at runtime (:ghpull:`923`).
 
 * **Standalone Kernel**: ``ipython kernel`` subcommand has been added, to allow
   starting a standalone kernel, that can be used with various frontends.
 
 * **Multiline History**: Multiline readline history has been restored to the
   Terminal frontend by default (:ghpull:`838`).
 
 * **%store**: The ``%store`` magic from earlier versions has been updated and
   placed in an extension, :ref:`extensions_storemagic`. Add 'storemagic' to ``c.InteractiveShellApp.extensions``
   in ipython_config.py to enable it (:ghpull:`1029`).
 
 
 
 Major Bugs fixed
 ----------------
 
 * Simple configuration errors should no longer crash IPython. In 0.11, errors in
   config files, as well as invalid trait values, could crash IPython. Now, such
   errors are reported, and help is displayed.
 
 * Certain SyntaxErrors no longer crash IPython (e.g. just typing keywords, such as
   ``return``, ``break``, etc.). See :ghissue:`704`.
 
 * IPython path utils, such as :func:`~IPython.utils.path.get_ipython_dir` now check
   for write permissions, so IPython should function on systems where the default
   path resolution might point to a read-only location, such as ``HOMESHARE`` on
   Windows (:ghissue:`669`).
 
 * :func:`raw_input` now works in the kernel when multiple frontends are in use. The
   request will be sent to the frontend that made the request, and an exception is
   raised if that frontend does not support stdin requests (e.g. the notebook)
   (:ghissue:`673`).
 
 * :mod:`zmq` version detection no longer uses simple lexicographical comparison to
   check minimum version, which prevents 0.11 from working with pyzmq-2.1.10
   (:ghpull:`758`).
 
 * A bug in PySide < 1.0.7 caused crashes on OSX when tooltips were shown
   (:ghissue:`711`). these tooltips are now disabled on old PySide (:ghpull:`963`).
 
 * IPython no longer crashes when started on recent versions of Python 3 in
   Windows (:ghissue:`737`).
 
 * Instances of classes defined interactively can now be pickled (:ghissue:`29`;
   :ghpull:`648`). Note that pickling saves a reference to the class definition,
   so unpickling the instances will only work where the class has been defined.
 
 .. * use bullet list
 
 Backwards incompatible changes
 ------------------------------
 
 * IPython connection information is no longer specified via ip/port directly,
   rather via json connection files.  These files are stored in the security
   directory, and enable us to turn on HMAC message authentication by default,
   significantly improving the security of kernels.  Various utility functions
   have been added to :mod:`IPython.lib.kernel`, for easier connecting to existing
   kernels.
 
 * :class:`~IPython.zmq.kernelmanager.KernelManager` now has one ip, and several port
   traits, rather than several ip/port pair ``_addr`` traits. This better matches the
   rest of the code, where the ip cannot not be set separately for each channel.
 
 * Custom prompts are now configured using a new class,
   :class:`~IPython.core.prompts.PromptManager`, which has traits for :attr:`in_template`,
   :attr:`in2_template` (the ``...:`` continuation prompt), :attr:`out_template`
   and :attr:`rewrite_template`. This uses Python's string formatting system, so
   you can use ``{time}`` and ``{cwd}``, although we have preserved the abbreviations
   from previous versions, e.g. ``\#`` (prompt number) and ``\w`` (working 
   directory). For the list of available fields, refer to the source of
   :file:`IPython/core/prompts.py`.
 
 * The class inheritance of the Launchers in :mod:`IPython.parallel.apps.launcher`
   used by ipcluster has changed, so that trait names are more consistent across
   batch systems. This may require a few renames in your config files, if you
   customized the command-line args for launching controllers and engines. The
   configurable names have also been changed to be clearer that they point to class
   names, and can now be specified by name only, rather than requiring the full
   import path of each class, e.g.::
 
     IPClusterEngines.engine_launcher = 'IPython.parallel.apps.launcher.MPIExecEngineSetLauncher'
     IPClusterStart.controller_launcher = 'IPython.parallel.apps.launcher.SSHControllerLauncher'
 
   would now be specified as::
 
     IPClusterEngines.engine_launcher_class = 'MPIExec'
     IPClusterStart.controller_launcher_class = 'SSH'
 
   The full path will still work, and is necessary for using custom launchers not in
   IPython's launcher module.
 
-* For embedding a shell, note that the parameter ``user_global_ns`` has been
-  replaced by ``user_module``, and expects a module-like object, rather than
-  a namespace dict. The ``user_ns`` parameter works the same way as before, and
+* For embedding a shell, note that the parameters ``user_global_ns`` and ``global_ns``
+  have been deprectated in favour of ``user_module`` and ``module`` respsectively.
+  The new parameters expect a module-like object, rather than a namespace dict.
+  The old parameters remain for backwards compatibility, although ``user_global_ns``
+  is now ignored. The ``user_ns`` parameter works the same way as before, and
   calling :func:`~IPython.frontend.terminal.embed.embed` with no arguments still
-  works the same way.
+  works as before.
 
 .. * use bullet list