1"""runpy.py - locating and running Python code using the module namespace
2
3Provides support for locating and running Python scripts using the Python
4module namespace instead of the native filesystem.
5
6This allows Python code to play nicely with non-filesystem based PEP 302
7importers when locating support scripts as well as when importing modules.
8"""
9# Written by Nick Coghlan <ncoghlan at gmail.com>
10#    to implement PEP 338 (Executing Modules as Scripts)
11
12
13import sys
14import importlib.machinery # importlib first so we can test #15386 via -m
15import importlib.util
16import io
17import types
18import os
19from pkgutil import read_code, get_importer
20
21__all__ = [
22    "run_module", "run_path",
23]
24
25class _TempModule(object):
26    """Temporarily replace a module in sys.modules with an empty namespace"""
27    def __init__(self, mod_name):
28        self.mod_name = mod_name
29        self.module = types.ModuleType(mod_name)
30        self._saved_module = []
31
32    def __enter__(self):
33        mod_name = self.mod_name
34        try:
35            self._saved_module.append(sys.modules[mod_name])
36        except KeyError:
37            pass
38        sys.modules[mod_name] = self.module
39        return self
40
41    def __exit__(self, *args):
42        if self._saved_module:
43            sys.modules[self.mod_name] = self._saved_module[0]
44        else:
45            del sys.modules[self.mod_name]
46        self._saved_module = []
47
48class _ModifiedArgv0(object):
49    def __init__(self, value):
50        self.value = value
51        self._saved_value = self._sentinel = object()
52
53    def __enter__(self):
54        if self._saved_value is not self._sentinel:
55            raise RuntimeError("Already preserving saved value")
56        self._saved_value = sys.argv[0]
57        sys.argv[0] = self.value
58
59    def __exit__(self, *args):
60        self.value = self._sentinel
61        sys.argv[0] = self._saved_value
62
63# TODO: Replace these helpers with importlib._bootstrap_external functions.
64def _run_code(code, run_globals, init_globals=None,
65              mod_name=None, mod_spec=None,
66              pkg_name=None, script_name=None):
67    """Helper to run code in nominated namespace"""
68    if init_globals is not None:
69        run_globals.update(init_globals)
70    if mod_spec is None:
71        loader = None
72        fname = script_name
73        cached = None
74    else:
75        loader = mod_spec.loader
76        fname = mod_spec.origin
77        cached = mod_spec.cached
78        if pkg_name is None:
79            pkg_name = mod_spec.parent
80    run_globals.update(__name__ = mod_name,
81                       __file__ = fname,
82                       __cached__ = cached,
83                       __doc__ = None,
84                       __loader__ = loader,
85                       __package__ = pkg_name,
86                       __spec__ = mod_spec)
87    exec(code, run_globals)
88    return run_globals
89
90def _run_module_code(code, init_globals=None,
91                    mod_name=None, mod_spec=None,
92                    pkg_name=None, script_name=None):
93    """Helper to run code in new namespace with sys modified"""
94    fname = script_name if mod_spec is None else mod_spec.origin
95    with _TempModule(mod_name) as temp_module, _ModifiedArgv0(fname):
96        mod_globals = temp_module.module.__dict__
97        _run_code(code, mod_globals, init_globals,
98                  mod_name, mod_spec, pkg_name, script_name)
99    # Copy the globals of the temporary module, as they
100    # may be cleared when the temporary module goes away
101    return mod_globals.copy()
102
103# Helper to get the full name, spec and code for a module
104def _get_module_details(mod_name, error=ImportError):
105    if mod_name.startswith("."):
106        raise error("Relative module names not supported")
107    pkg_name, _, _ = mod_name.rpartition(".")
108    if pkg_name:
109        # Try importing the parent to avoid catching initialization errors
110        try:
111            __import__(pkg_name)
112        except ImportError as e:
113            # If the parent or higher ancestor package is missing, let the
114            # error be raised by find_spec() below and then be caught. But do
115            # not allow other errors to be caught.
116            if e.name is None or (e.name != pkg_name and
117                    not pkg_name.startswith(e.name + ".")):
118                raise
119        # Warn if the module has already been imported under its normal name
120        existing = sys.modules.get(mod_name)
121        if existing is not None and not hasattr(existing, "__path__"):
122            from warnings import warn
123            msg = "{mod_name!r} found in sys.modules after import of " \
124                "package {pkg_name!r}, but prior to execution of " \
125                "{mod_name!r}; this may result in unpredictable " \
126                "behaviour".format(mod_name=mod_name, pkg_name=pkg_name)
127            warn(RuntimeWarning(msg))
128
129    try:
130        spec = importlib.util.find_spec(mod_name)
131    except (ImportError, AttributeError, TypeError, ValueError) as ex:
132        # This hack fixes an impedance mismatch between pkgutil and
133        # importlib, where the latter raises other errors for cases where
134        # pkgutil previously raised ImportError
135        msg = "Error while finding module specification for {!r} ({}: {})"
136        if mod_name.endswith(".py"):
137            msg += (f". Try using '{mod_name[:-3]}' instead of "
138                    f"'{mod_name}' as the module name.")
139        raise error(msg.format(mod_name, type(ex).__name__, ex)) from ex
140    if spec is None:
141        raise error("No module named %s" % mod_name)
142    if spec.submodule_search_locations is not None:
143        if mod_name == "__main__" or mod_name.endswith(".__main__"):
144            raise error("Cannot use package as __main__ module")
145        try:
146            pkg_main_name = mod_name + ".__main__"
147            return _get_module_details(pkg_main_name, error)
148        except error as e:
149            if mod_name not in sys.modules:
150                raise  # No module loaded; being a package is irrelevant
151            raise error(("%s; %r is a package and cannot " +
152                               "be directly executed") %(e, mod_name))
153    loader = spec.loader
154    if loader is None:
155        raise error("%r is a namespace package and cannot be executed"
156                                                                 % mod_name)
157    try:
158        code = loader.get_code(mod_name)
159    except ImportError as e:
160        raise error(format(e)) from e
161    if code is None:
162        raise error("No code object available for %s" % mod_name)
163    return mod_name, spec, code
164
165class _Error(Exception):
166    """Error that _run_module_as_main() should report without a traceback"""
167
168# XXX ncoghlan: Should this be documented and made public?
169# (Current thoughts: don't repeat the mistake that lead to its
170# creation when run_module() no longer met the needs of
171# mainmodule.c, but couldn't be changed because it was public)
172def _run_module_as_main(mod_name, alter_argv=True):
173    """Runs the designated module in the __main__ namespace
174
175       Note that the executed module will have full access to the
176       __main__ namespace. If this is not desirable, the run_module()
177       function should be used to run the module code in a fresh namespace.
178
179       At the very least, these variables in __main__ will be overwritten:
180           __name__
181           __file__
182           __cached__
183           __loader__
184           __package__
185    """
186    try:
187        if alter_argv or mod_name != "__main__": # i.e. -m switch
188            mod_name, mod_spec, code = _get_module_details(mod_name, _Error)
189        else:          # i.e. directory or zipfile execution
190            mod_name, mod_spec, code = _get_main_module_details(_Error)
191    except _Error as exc:
192        msg = "%s: %s" % (sys.executable, exc)
193        sys.exit(msg)
194    main_globals = sys.modules["__main__"].__dict__
195    if alter_argv:
196        sys.argv[0] = mod_spec.origin
197    return _run_code(code, main_globals, None,
198                     "__main__", mod_spec)
199
200def run_module(mod_name, init_globals=None,
201               run_name=None, alter_sys=False):
202    """Execute a module's code without importing it
203
204       Returns the resulting top level namespace dictionary
205    """
206    mod_name, mod_spec, code = _get_module_details(mod_name)
207    if run_name is None:
208        run_name = mod_name
209    if alter_sys:
210        return _run_module_code(code, init_globals, run_name, mod_spec)
211    else:
212        # Leave the sys module alone
213        return _run_code(code, {}, init_globals, run_name, mod_spec)
214
215def _get_main_module_details(error=ImportError):
216    # Helper that gives a nicer error message when attempting to
217    # execute a zipfile or directory by invoking __main__.py
218    # Also moves the standard __main__ out of the way so that the
219    # preexisting __loader__ entry doesn't cause issues
220    main_name = "__main__"
221    saved_main = sys.modules[main_name]
222    del sys.modules[main_name]
223    try:
224        return _get_module_details(main_name)
225    except ImportError as exc:
226        if main_name in str(exc):
227            raise error("can't find %r module in %r" %
228                              (main_name, sys.path[0])) from exc
229        raise
230    finally:
231        sys.modules[main_name] = saved_main
232
233
234def _get_code_from_file(run_name, fname):
235    # Check for a compiled file first
236    decoded_path = os.path.abspath(os.fsdecode(fname))
237    with io.open_code(decoded_path) as f:
238        code = read_code(f)
239    if code is None:
240        # That didn't work, so try it as normal source code
241        with io.open_code(decoded_path) as f:
242            code = compile(f.read(), fname, 'exec')
243    return code, fname
244
245def run_path(path_name, init_globals=None, run_name=None):
246    """Execute code located at the specified filesystem location
247
248       Returns the resulting top level namespace dictionary
249
250       The file path may refer directly to a Python script (i.e.
251       one that could be directly executed with execfile) or else
252       it may refer to a zipfile or directory containing a top
253       level __main__.py script.
254    """
255    if run_name is None:
256        run_name = "<run_path>"
257    pkg_name = run_name.rpartition(".")[0]
258    importer = get_importer(path_name)
259    # Trying to avoid importing imp so as to not consume the deprecation warning.
260    is_NullImporter = False
261    if type(importer).__module__ == 'imp':
262        if type(importer).__name__ == 'NullImporter':
263            is_NullImporter = True
264    if isinstance(importer, type(None)) or is_NullImporter:
265        # Not a valid sys.path entry, so run the code directly
266        # execfile() doesn't help as we want to allow compiled files
267        code, fname = _get_code_from_file(run_name, path_name)
268        return _run_module_code(code, init_globals, run_name,
269                                pkg_name=pkg_name, script_name=fname)
270    else:
271        # Finder is defined for path, so add it to
272        # the start of sys.path
273        sys.path.insert(0, path_name)
274        try:
275            # Here's where things are a little different from the run_module
276            # case. There, we only had to replace the module in sys while the
277            # code was running and doing so was somewhat optional. Here, we
278            # have no choice and we have to remove it even while we read the
279            # code. If we don't do this, a __loader__ attribute in the
280            # existing __main__ module may prevent location of the new module.
281            mod_name, mod_spec, code = _get_main_module_details()
282            with _TempModule(run_name) as temp_module, \
283                 _ModifiedArgv0(path_name):
284                mod_globals = temp_module.module.__dict__
285                return _run_code(code, mod_globals, init_globals,
286                                    run_name, mod_spec, pkg_name).copy()
287        finally:
288            try:
289                sys.path.remove(path_name)
290            except ValueError:
291                pass
292
293
294if __name__ == "__main__":
295    # Run the module specified as the next command line argument
296    if len(sys.argv) < 2:
297        print("No module specified for execution", file=sys.stderr)
298    else:
299        del sys.argv[0] # Make the requested module sys.argv[0]
300        _run_module_as_main(sys.argv[0])
301