add IPython.get_ipython

library entry point for get_ipython

does not rely on injection into globals

IPython/__init__.py

@@ -1,85 +1,86 b''
 # encoding: utf-8
 """
 IPython: tools for interactive and parallel computing in Python.
 
 http://ipython.org
 """
 #-----------------------------------------------------------------------------
 #  Copyright (c) 2008-2011, IPython Development Team.
 #  Copyright (c) 2001-2007, Fernando Perez <[e-mail]>
 #  Copyright (c) 2001, Janko Hauser <[e-mail]>
 #  Copyright (c) 2001, Nathaniel Gray <[e-mail]>
 #
 #  Distributed under the terms of the Modified BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import absolute_import
 
 import os
 import sys
 
 #-----------------------------------------------------------------------------
 # Setup everything
 #-----------------------------------------------------------------------------
 
 # Don't forget to also update setup.py when this changes!
 if sys.version[0:3] < '2.6':
     raise ImportError('Python Version 2.6 or above is required for IPython.')
 
 # Make it easy to import extensions - they are always directly on pythonpath.
 # Therefore, non-IPython modules can be added to extensions directory.
 # This should probably be in ipapp.py.
 sys.path.append(os.path.join(os.path.dirname(__file__), "extensions"))
 
 #-----------------------------------------------------------------------------
 # Setup the top level names
 #-----------------------------------------------------------------------------
 
 from .config.loader import Config
+from .core.ipapi import get_ipython
 from .core import release
 from .core.application import Application
 from .frontend.terminal.embed import embed
 
 from .core.error import TryNext
 from .core.interactiveshell import InteractiveShell
 from .testing import test
 from .utils.sysinfo import sys_info
 from .utils.frame import extract_module_locals
 
 # Release data
 __author__ = '%s <%s>' % (release.author, release.author_email)
 __license__  = release.license
 __version__  = release.version
 version_info = release.version_info
 
 def embed_kernel(module=None, local_ns=None, **kwargs):
     """Embed and start an IPython kernel in a given scope.
     
     Parameters
     ----------
     module : ModuleType, optional
         The module to load into IPython globals (default: caller)
     local_ns : dict, optional
         The namespace to load into IPython user namespace (default: caller)
     
     kwargs : various, optional
         Further keyword args are relayed to the IPKernelApp constructor,
         allowing configuration of the Kernel.  Will only have an effect
         on the first embed_kernel call for a given process.
     
     """
     
     (caller_module, caller_locals) = extract_module_locals(1)
     if module is None:
         module = caller_module
     if local_ns is None:
         local_ns = caller_locals
     
     # Only import .zmq when we really need it
     from IPython.kernel.zmq.embed import embed_kernel as real_embed_kernel
     real_embed_kernel(module=module, local_ns=local_ns, **kwargs)

IPython/core/ipapi.py

@@ -1,29 +1,37 b''
 # encoding: utf-8
-"""
-This module is *completely* deprecated and should no longer be used for
-any purpose.  Currently, we have a few parts of the core that have
-not been componentized and thus, still rely on this module.  When everything
-has been made into a component, this module will be sent to deathrow.
+"""Simple function to call to get the current InteractiveShell instance
 """
 
 #-----------------------------------------------------------------------------
-#  Copyright (C) 2008-2011  The IPython Development Team
+#  Copyright (C) 2013  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
 #-----------------------------------------------------------------------------
 
+import warnings
+
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 
-def get():
-    """Get the global InteractiveShell instance."""
+def get_ipython():
+    """Get the global InteractiveShell instance.
+    
+    Returns None if no InteractiveShell instance is registered.
+    """
     from IPython.core.interactiveshell import InteractiveShell
-    return InteractiveShell.instance()
+    if InteractiveShell.initialized():
+        return InteractiveShell.instance()
+
+def get():
+    warnings.warn("ipapi.get has been deprecated since IPython 0.11",
+        DeprecationWarning
+    )
+    return get_ipython()