##// END OF EJS Templates
docs: refer to 'embed_kernel' in 'start_kernel's docstring...
Philippe Blain -
Show More
@@ -1,156 +1,156 b''
1 # PYTHON_ARGCOMPLETE_OK
1 # PYTHON_ARGCOMPLETE_OK
2 """
2 """
3 IPython: tools for interactive and parallel computing in Python.
3 IPython: tools for interactive and parallel computing in Python.
4
4
5 https://ipython.org
5 https://ipython.org
6 """
6 """
7 #-----------------------------------------------------------------------------
7 #-----------------------------------------------------------------------------
8 # Copyright (c) 2008-2011, IPython Development Team.
8 # Copyright (c) 2008-2011, IPython Development Team.
9 # Copyright (c) 2001-2007, Fernando Perez <fernando.perez@colorado.edu>
9 # Copyright (c) 2001-2007, Fernando Perez <fernando.perez@colorado.edu>
10 # Copyright (c) 2001, Janko Hauser <jhauser@zscout.de>
10 # Copyright (c) 2001, Janko Hauser <jhauser@zscout.de>
11 # Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>
11 # Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>
12 #
12 #
13 # Distributed under the terms of the Modified BSD License.
13 # Distributed under the terms of the Modified BSD License.
14 #
14 #
15 # The full license is in the file COPYING.txt, distributed with this software.
15 # The full license is in the file COPYING.txt, distributed with this software.
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17
17
18 #-----------------------------------------------------------------------------
18 #-----------------------------------------------------------------------------
19 # Imports
19 # Imports
20 #-----------------------------------------------------------------------------
20 #-----------------------------------------------------------------------------
21
21
22 import sys
22 import sys
23
23
24 #-----------------------------------------------------------------------------
24 #-----------------------------------------------------------------------------
25 # Setup everything
25 # Setup everything
26 #-----------------------------------------------------------------------------
26 #-----------------------------------------------------------------------------
27
27
28 # Don't forget to also update setup.py when this changes!
28 # Don't forget to also update setup.py when this changes!
29 if sys.version_info < (3, 8):
29 if sys.version_info < (3, 8):
30 raise ImportError(
30 raise ImportError(
31 """
31 """
32 IPython 8+ supports Python 3.8 and above, following NEP 29.
32 IPython 8+ supports Python 3.8 and above, following NEP 29.
33 When using Python 2.7, please install IPython 5.x LTS Long Term Support version.
33 When using Python 2.7, please install IPython 5.x LTS Long Term Support version.
34 Python 3.3 and 3.4 were supported up to IPython 6.x.
34 Python 3.3 and 3.4 were supported up to IPython 6.x.
35 Python 3.5 was supported with IPython 7.0 to 7.9.
35 Python 3.5 was supported with IPython 7.0 to 7.9.
36 Python 3.6 was supported with IPython up to 7.16.
36 Python 3.6 was supported with IPython up to 7.16.
37 Python 3.7 was still supported with the 7.x branch.
37 Python 3.7 was still supported with the 7.x branch.
38
38
39 See IPython `README.rst` file for more information:
39 See IPython `README.rst` file for more information:
40
40
41 https://github.com/ipython/ipython/blob/main/README.rst
41 https://github.com/ipython/ipython/blob/main/README.rst
42
42
43 """
43 """
44 )
44 )
45
45
46 #-----------------------------------------------------------------------------
46 #-----------------------------------------------------------------------------
47 # Setup the top level names
47 # Setup the top level names
48 #-----------------------------------------------------------------------------
48 #-----------------------------------------------------------------------------
49
49
50 from .core.getipython import get_ipython
50 from .core.getipython import get_ipython
51 from .core import release
51 from .core import release
52 from .core.application import Application
52 from .core.application import Application
53 from .terminal.embed import embed
53 from .terminal.embed import embed
54
54
55 from .core.interactiveshell import InteractiveShell
55 from .core.interactiveshell import InteractiveShell
56 from .utils.sysinfo import sys_info
56 from .utils.sysinfo import sys_info
57 from .utils.frame import extract_module_locals
57 from .utils.frame import extract_module_locals
58
58
59 # Release data
59 # Release data
60 __author__ = '%s <%s>' % (release.author, release.author_email)
60 __author__ = '%s <%s>' % (release.author, release.author_email)
61 __license__ = release.license
61 __license__ = release.license
62 __version__ = release.version
62 __version__ = release.version
63 version_info = release.version_info
63 version_info = release.version_info
64 # list of CVEs that should have been patched in this release.
64 # list of CVEs that should have been patched in this release.
65 # this is informational and should not be relied upon.
65 # this is informational and should not be relied upon.
66 __patched_cves__ = {"CVE-2022-21699", "CVE-2023-24816"}
66 __patched_cves__ = {"CVE-2022-21699", "CVE-2023-24816"}
67
67
68
68
69 def embed_kernel(module=None, local_ns=None, **kwargs):
69 def embed_kernel(module=None, local_ns=None, **kwargs):
70 """Embed and start an IPython kernel in a given scope.
70 """Embed and start an IPython kernel in a given scope.
71
71
72 If you don't want the kernel to initialize the namespace
72 If you don't want the kernel to initialize the namespace
73 from the scope of the surrounding function,
73 from the scope of the surrounding function,
74 and/or you want to load full IPython configuration,
74 and/or you want to load full IPython configuration,
75 you probably want `IPython.start_kernel()` instead.
75 you probably want `IPython.start_kernel()` instead.
76
76
77 Parameters
77 Parameters
78 ----------
78 ----------
79 module : types.ModuleType, optional
79 module : types.ModuleType, optional
80 The module to load into IPython globals (default: caller)
80 The module to load into IPython globals (default: caller)
81 local_ns : dict, optional
81 local_ns : dict, optional
82 The namespace to load into IPython user namespace (default: caller)
82 The namespace to load into IPython user namespace (default: caller)
83 **kwargs : various, optional
83 **kwargs : various, optional
84 Further keyword args are relayed to the IPKernelApp constructor,
84 Further keyword args are relayed to the IPKernelApp constructor,
85 allowing configuration of the Kernel. Will only have an effect
85 allowing configuration of the Kernel. Will only have an effect
86 on the first embed_kernel call for a given process.
86 on the first embed_kernel call for a given process.
87 """
87 """
88
88
89 (caller_module, caller_locals) = extract_module_locals(1)
89 (caller_module, caller_locals) = extract_module_locals(1)
90 if module is None:
90 if module is None:
91 module = caller_module
91 module = caller_module
92 if local_ns is None:
92 if local_ns is None:
93 local_ns = caller_locals
93 local_ns = caller_locals
94
94
95 # Only import .zmq when we really need it
95 # Only import .zmq when we really need it
96 from ipykernel.embed import embed_kernel as real_embed_kernel
96 from ipykernel.embed import embed_kernel as real_embed_kernel
97 real_embed_kernel(module=module, local_ns=local_ns, **kwargs)
97 real_embed_kernel(module=module, local_ns=local_ns, **kwargs)
98
98
99 def start_ipython(argv=None, **kwargs):
99 def start_ipython(argv=None, **kwargs):
100 """Launch a normal IPython instance (as opposed to embedded)
100 """Launch a normal IPython instance (as opposed to embedded)
101
101
102 `IPython.embed()` puts a shell in a particular calling scope,
102 `IPython.embed()` puts a shell in a particular calling scope,
103 such as a function or method for debugging purposes,
103 such as a function or method for debugging purposes,
104 which is often not desirable.
104 which is often not desirable.
105
105
106 `start_ipython()` does full, regular IPython initialization,
106 `start_ipython()` does full, regular IPython initialization,
107 including loading startup files, configuration, etc.
107 including loading startup files, configuration, etc.
108 much of which is skipped by `embed()`.
108 much of which is skipped by `embed()`.
109
109
110 This is a public API method, and will survive implementation changes.
110 This is a public API method, and will survive implementation changes.
111
111
112 Parameters
112 Parameters
113 ----------
113 ----------
114 argv : list or None, optional
114 argv : list or None, optional
115 If unspecified or None, IPython will parse command-line options from sys.argv.
115 If unspecified or None, IPython will parse command-line options from sys.argv.
116 To prevent any command-line parsing, pass an empty list: `argv=[]`.
116 To prevent any command-line parsing, pass an empty list: `argv=[]`.
117 user_ns : dict, optional
117 user_ns : dict, optional
118 specify this dictionary to initialize the IPython user namespace with particular values.
118 specify this dictionary to initialize the IPython user namespace with particular values.
119 **kwargs : various, optional
119 **kwargs : various, optional
120 Any other kwargs will be passed to the Application constructor,
120 Any other kwargs will be passed to the Application constructor,
121 such as `config`.
121 such as `config`.
122 """
122 """
123 from IPython.terminal.ipapp import launch_new_instance
123 from IPython.terminal.ipapp import launch_new_instance
124 return launch_new_instance(argv=argv, **kwargs)
124 return launch_new_instance(argv=argv, **kwargs)
125
125
126 def start_kernel(argv=None, **kwargs):
126 def start_kernel(argv=None, **kwargs):
127 """Launch a normal IPython kernel instance (as opposed to embedded)
127 """Launch a normal IPython kernel instance (as opposed to embedded)
128
128
129 `IPython.embed_kernel()` puts a shell in a particular calling scope,
129 `IPython.embed_kernel()` puts a shell in a particular calling scope,
130 such as a function or method for debugging purposes,
130 such as a function or method for debugging purposes,
131 which is often not desirable.
131 which is often not desirable.
132
132
133 `start_kernel()` does full, regular IPython initialization,
133 `start_kernel()` does full, regular IPython initialization,
134 including loading startup files, configuration, etc.
134 including loading startup files, configuration, etc.
135 much of which is skipped by `embed()`.
135 much of which is skipped by `embed_kernel()`.
136
136
137 Parameters
137 Parameters
138 ----------
138 ----------
139 argv : list or None, optional
139 argv : list or None, optional
140 If unspecified or None, IPython will parse command-line options from sys.argv.
140 If unspecified or None, IPython will parse command-line options from sys.argv.
141 To prevent any command-line parsing, pass an empty list: `argv=[]`.
141 To prevent any command-line parsing, pass an empty list: `argv=[]`.
142 user_ns : dict, optional
142 user_ns : dict, optional
143 specify this dictionary to initialize the IPython user namespace with particular values.
143 specify this dictionary to initialize the IPython user namespace with particular values.
144 **kwargs : various, optional
144 **kwargs : various, optional
145 Any other kwargs will be passed to the Application constructor,
145 Any other kwargs will be passed to the Application constructor,
146 such as `config`.
146 such as `config`.
147 """
147 """
148 import warnings
148 import warnings
149
149
150 warnings.warn(
150 warnings.warn(
151 "start_kernel is deprecated since IPython 8.0, use from `ipykernel.kernelapp.launch_new_instance`",
151 "start_kernel is deprecated since IPython 8.0, use from `ipykernel.kernelapp.launch_new_instance`",
152 DeprecationWarning,
152 DeprecationWarning,
153 stacklevel=2,
153 stacklevel=2,
154 )
154 )
155 from ipykernel.kernelapp import launch_new_instance
155 from ipykernel.kernelapp import launch_new_instance
156 return launch_new_instance(argv=argv, **kwargs)
156 return launch_new_instance(argv=argv, **kwargs)
General Comments 0
You need to be logged in to leave comments. Login now