1# encoding: utf-8
2"""
3IPython: tools for interactive and parallel computing in Python.
4
5http://ipython.org
6"""
7#-----------------------------------------------------------------------------
8#  Copyright (c) 2008-2011, IPython Development Team.
9#  Copyright (c) 2001-2007, Fernando Perez <fernando.perez@colorado.edu>
10#  Copyright (c) 2001, Janko Hauser <jhauser@zscout.de>
11#  Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>
12#
13#  Distributed under the terms of the Modified BSD License.
14#
15#  The full license is in the file COPYING.txt, distributed with this software.
16#-----------------------------------------------------------------------------
17
18#-----------------------------------------------------------------------------
19# Imports
20#-----------------------------------------------------------------------------
21from __future__ import absolute_import
22
23import os
24import sys
25import warnings
26
27#-----------------------------------------------------------------------------
28# Setup everything
29#-----------------------------------------------------------------------------
30
31# Don't forget to also update setup.py when this changes!
32v = sys.version_info
33if v[:2] < (2,7) or (v[0] >= 3 and v[:2] < (3,3)):
34    raise ImportError('IPython requires Python version 2.7 or 3.3 or above.')
35del v
36
37# Make it easy to import extensions - they are always directly on pythonpath.
38# Therefore, non-IPython modules can be added to extensions directory.
39# This should probably be in ipapp.py.
40sys.path.append(os.path.join(os.path.dirname(__file__), "extensions"))
41
42#-----------------------------------------------------------------------------
43# Setup the top level names
44#-----------------------------------------------------------------------------
45
46from .core.getipython import get_ipython
47from .core import release
48from .core.application import Application
49from .terminal.embed import embed
50
51from .core.interactiveshell import InteractiveShell
52from .testing import test
53from .utils.sysinfo import sys_info
54from .utils.frame import extract_module_locals
55
56# Release data
57__author__ = '%s <%s>' % (release.author, release.author_email)
58__license__  = release.license
59__version__  = release.version
60version_info = release.version_info
61
62def embed_kernel(module=None, local_ns=None, **kwargs):
63    """Embed and start an IPython kernel in a given scope.
64
65    If you don't want the kernel to initialize the namespace
66    from the scope of the surrounding function,
67    and/or you want to load full IPython configuration,
68    you probably want `IPython.start_kernel()` instead.
69
70    Parameters
71    ----------
72    module : ModuleType, optional
73        The module to load into IPython globals (default: caller)
74    local_ns : dict, optional
75        The namespace to load into IPython user namespace (default: caller)
76
77    kwargs : various, optional
78        Further keyword args are relayed to the IPKernelApp constructor,
79        allowing configuration of the Kernel.  Will only have an effect
80        on the first embed_kernel call for a given process.
81    """
82
83    (caller_module, caller_locals) = extract_module_locals(1)
84    if module is None:
85        module = caller_module
86    if local_ns is None:
87        local_ns = caller_locals
88
89    # Only import .zmq when we really need it
90    from ipykernel.embed import embed_kernel as real_embed_kernel
91    real_embed_kernel(module=module, local_ns=local_ns, **kwargs)
92
93def start_ipython(argv=None, **kwargs):
94    """Launch a normal IPython instance (as opposed to embedded)
95
96    `IPython.embed()` puts a shell in a particular calling scope,
97    such as a function or method for debugging purposes,
98    which is often not desirable.
99
100    `start_ipython()` does full, regular IPython initialization,
101    including loading startup files, configuration, etc.
102    much of which is skipped by `embed()`.
103
104    This is a public API method, and will survive implementation changes.
105
106    Parameters
107    ----------
108
109    argv : list or None, optional
110        If unspecified or None, IPython will parse command-line options from sys.argv.
111        To prevent any command-line parsing, pass an empty list: `argv=[]`.
112    user_ns : dict, optional
113        specify this dictionary to initialize the IPython user namespace with particular values.
114    kwargs : various, optional
115        Any other kwargs will be passed to the Application constructor,
116        such as `config`.
117    """
118    from IPython.terminal.ipapp import launch_new_instance
119    return launch_new_instance(argv=argv, **kwargs)
120
121def start_kernel(argv=None, **kwargs):
122    """Launch a normal IPython kernel instance (as opposed to embedded)
123
124    `IPython.embed_kernel()` puts a shell in a particular calling scope,
125    such as a function or method for debugging purposes,
126    which is often not desirable.
127
128    `start_kernel()` does full, regular IPython initialization,
129    including loading startup files, configuration, etc.
130    much of which is skipped by `embed()`.
131
132    Parameters
133    ----------
134
135    argv : list or None, optional
136        If unspecified or None, IPython will parse command-line options from sys.argv.
137        To prevent any command-line parsing, pass an empty list: `argv=[]`.
138    user_ns : dict, optional
139        specify this dictionary to initialize the IPython user namespace with particular values.
140    kwargs : various, optional
141        Any other kwargs will be passed to the Application constructor,
142        such as `config`.
143    """
144    from IPython.kernel.zmq.kernelapp import launch_new_instance
145    return launch_new_instance(argv=argv, **kwargs)
146
147