Debian Codegraph @

Lib/concurrent/interpreters/__init__.py

raw
1 """Subinterpreters High Level Module."""
2
3 import threading
4 import weakref
5 import _interpreters
6
7 # aliases:
8 from _interpreters import (
9 InterpreterError, InterpreterNotFoundError, NotShareableError,
10 is_shareable,
11 )
12 from ._queues import (
13 create as create_queue,
14 Queue, QueueEmpty, QueueFull,
15 )
16
17
18 __all__ = [
19 'get_current', 'get_main', 'create', 'list_all', 'is_shareable',
20 'Interpreter',
21 'InterpreterError', 'InterpreterNotFoundError', 'ExecutionFailed',
22 'NotShareableError',
23 'create_queue', 'Queue', 'QueueEmpty', 'QueueFull',
24 ]
25
26
27 _EXEC_FAILURE_STR = """
28 {superstr}
29
30 Uncaught in the interpreter:
31
32 {formatted}
33 """.strip()
34
35 class ExecutionFailed(InterpreterError):
36 """An unhandled exception happened during execution.
37
38 This is raised from Interpreter.exec() and Interpreter.call().
39 """
40
41 def __init__(self, excinfo):
42 msg = excinfo.formatted
43 if not msg:
44 if excinfo.type and excinfo.msg:
45 msg = f'{excinfo.type.__name__}: {excinfo.msg}'
46 else:
47 msg = excinfo.type.__name__ or excinfo.msg
48 super().__init__(msg)
49 self.excinfo = excinfo
50
51 def __str__(self):
52 try:
53 formatted = self.excinfo.errdisplay
54 except Exception:
55 return super().__str__()
56 else:
57 return _EXEC_FAILURE_STR.format(
58 superstr=super().__str__(),
59 formatted=formatted,
60 )
61
62
63 def create():
64 """Return a new (idle) Python interpreter."""
65 id = _interpreters.create(reqrefs=True)
66 return Interpreter(id, _ownsref=True)
67
68
69 def list_all():
70 """Return all existing interpreters."""
71 return [Interpreter(id, _whence=whence)
72 for id, whence in _interpreters.list_all(require_ready=True)]
73
74
75 def get_current():
76 """Return the currently running interpreter."""
77 id, whence = _interpreters.get_current()
78 return Interpreter(id, _whence=whence)
79
80
81 def get_main():
82 """Return the main interpreter."""
83 id, whence = _interpreters.get_main()
84 assert whence == _interpreters.WHENCE_RUNTIME, repr(whence)
85 return Interpreter(id, _whence=whence)
86
87
88 _known = weakref.WeakValueDictionary()
89
90 class Interpreter:
91 """A single Python interpreter.
92
93 Attributes:
94
95 "id" - the unique process-global ID number for the interpreter
96 "whence" - indicates where the interpreter was created
97
98 If the interpreter wasn't created by this module
99 then any method that modifies the interpreter will fail,
100 i.e. .close(), .prepare_main(), .exec(), and .call()
101 """
102
103 _WHENCE_TO_STR = {
104 _interpreters.WHENCE_UNKNOWN: 'unknown',
105 _interpreters.WHENCE_RUNTIME: 'runtime init',
106 _interpreters.WHENCE_LEGACY_CAPI: 'legacy C-API',
107 _interpreters.WHENCE_CAPI: 'C-API',
108 _interpreters.WHENCE_XI: 'cross-interpreter C-API',
109 _interpreters.WHENCE_STDLIB: '_interpreters module',
110 }
111
112 def __new__(cls, id, /, _whence=None, _ownsref=None):
113 # There is only one instance for any given ID.
114 if not isinstance(id, int):
115 raise TypeError(f'id must be an int, got {id!r}')
116 id = int(id)
117 if _whence is None:
118 if _ownsref:
119 _whence = _interpreters.WHENCE_STDLIB
120 else:
121 _whence = _interpreters.whence(id)
122 assert _whence in cls._WHENCE_TO_STR, repr(_whence)
123 if _ownsref is None:
124 _ownsref = (_whence == _interpreters.WHENCE_STDLIB)
125 try:
126 self = _known[id]
127 assert hasattr(self, '_ownsref')
128 except KeyError:
129 self = super().__new__(cls)
130 _known[id] = self
131 self._id = id
132 self._whence = _whence
133 self._ownsref = _ownsref
134 if _ownsref:
135 # This may raise InterpreterNotFoundError:
136 _interpreters.incref(id)
137 return self
138
139 def __repr__(self):
140 return f'{type(self).__name__}({self.id})'
141
142 def __hash__(self):
143 return hash(self._id)
144
145 def __del__(self):
146 self._decref()
147
148 # for pickling:
149 def __reduce__(self):
150 return (type(self), (self._id,))
151
152 # gh-135729: Globals might be destroyed by the time this is called, so we
153 # need to keep references ourself
154 def _decref(self, *,
155 InterpreterNotFoundError=InterpreterNotFoundError,
156 _interp_decref=_interpreters.decref,
157 ):
158 if not self._ownsref:
159 return
160 self._ownsref = False
161 try:
162 _interp_decref(self._id)
163 except InterpreterNotFoundError:
164 pass
165
166 @property
167 def id(self):
168 return self._id
169
170 @property
171 def whence(self):
172 return self._WHENCE_TO_STR[self._whence]
173
174 def is_running(self):
175 """Return whether or not the identified interpreter is running."""
176 return _interpreters.is_running(self._id)
177
178 # Everything past here is available only to interpreters created by
179 # interpreters.create().
180
181 def close(self):
182 """Finalize and destroy the interpreter.
183
184 Attempting to destroy the current interpreter results
185 in an InterpreterError.
186 """
187 return _interpreters.destroy(self._id, restrict=True)
188
189 def prepare_main(self, ns=None, /, **kwargs):
190 """Bind the given values into the interpreter's __main__.
191
192 The values must be shareable.
193 """
194 ns = dict(ns, **kwargs) if ns is not None else kwargs
195 _interpreters.set___main___attrs(self._id, ns, restrict=True)
196
197 def exec(self, code, /):
198 """Run the given source code in the interpreter.
199
200 This is essentially the same as calling the builtin "exec"
201 with this interpreter, using the __dict__ of its __main__
202 module as both globals and locals.
203
204 There is no return value.
205
206 If the code raises an unhandled exception then an ExecutionFailed
207 exception is raised, which summarizes the unhandled exception.
208 The actual exception is discarded because objects cannot be
209 shared between interpreters.
210
211 This blocks the current Python thread until done. During
212 that time, the previous interpreter is allowed to run
213 in other threads.
214 """
215 excinfo = _interpreters.exec(self._id, code, restrict=True)
216 if excinfo is not None:
217 raise ExecutionFailed(excinfo)
218
219 def _call(self, callable, args, kwargs):
220 res, excinfo = _interpreters.call(self._id, callable, args, kwargs, restrict=True)
221 if excinfo is not None:
222 raise ExecutionFailed(excinfo)
223 return res
224
225 def call(self, callable, /, *args, **kwargs):
226 """Call the object in the interpreter with given args/kwargs.
227
228 Nearly all callables, args, kwargs, and return values are
229 supported. All "shareable" objects are supported, as are
230 "stateless" functions (meaning non-closures that do not use
231 any globals). This method will fall back to pickle.
232
233 If the callable raises an exception then the error display
234 (including full traceback) is sent back between the interpreters
235 and an ExecutionFailed exception is raised, much like what
236 happens with Interpreter.exec().
237 """
238 return self._call(callable, args, kwargs)
239
240 def call_in_thread(self, callable, /, *args, **kwargs):
241 """Return a new thread that calls the object in the interpreter.
242
243 The return value and any raised exception are discarded.
244 """
245 t = threading.Thread(target=self._call, args=(callable, args, kwargs))
246 t.start()
247 return t