Lines Matching +full:is +full:- +full:module
1 :mod:`runpy` --- Locating and executing Python modules
4 .. module:: runpy
11 --------------
13 The :mod:`runpy` module is used to locate and run Python modules without
14 importing them first. Its main use is to implement the :option:`-m` command
15 line switch that allows scripts to be located using the Python module
18 Note that this is *not* a sandbox module - all code is executed in the
24 If that limitation is not acceptable for a given use case, :mod:`importlib`
25 is likely to be a more suitable choice than this module.
27 The :mod:`runpy` module provides two functions:
33 pair: module; __main__
35 Execute the code of the specified module and return the resulting module
36 globals dictionary. The module's code is first located using the standard
38 fresh module namespace.
40 The *mod_name* argument should be an absolute module name.
41 If the module name refers to a package rather than a normal
42 module, then that package is imported and the ``__main__`` submodule within
43 that package is then executed and the resulting module globals dictionary
46 The optional dictionary argument *init_globals* may be used to pre-populate
47 the module's globals dictionary before the code is executed. The supplied
54 dictionary before the module code is executed (Note that this is a
55 minimal set of variables - other variables may be set implicitly as an
58 ``__name__`` is set to *run_name* if this optional argument is not
59 :const:`None`, to ``mod_name + '.__main__'`` if the named module is a
63 module (that is, ``__spec__.name`` will always be *mod_name* or
67 :ref:`set as normal <import-mod-attrs>` based on the module spec.
69 If the argument *alter_sys* is supplied and evaluates to :const:`True`,
70 then ``sys.argv[0]`` is updated with the value of ``__file__`` and
71 ``sys.modules[__name__]`` is updated with a temporary module object for the
72 module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]``
75 Note that this manipulation of :mod:`sys` is not thread-safe. Other threads
76 may see the partially initialised module, as well as the altered list of
77 arguments. It is recommended that the :mod:`sys` module be left alone when
81 The :option:`-m` option offering equivalent functionality from the
91 Updated to take advantage of the module spec feature added by
93 run this way, as well as ensuring the real module name is always
99 pair: module; __main__
102 module globals dictionary. As with a script name supplied to the CPython
105 module (e.g. a zipfile containing a top-level ``__main__.py`` file).
107 For a simple script, the specified code is simply executed in a fresh
108 module namespace. For a valid sys.path entry (typically a zipfile or
109 directory), the entry is first added to the beginning of ``sys.path``. The
110 function then looks for and executes a :mod:`__main__` module using the
111 updated path. Note that there is no special protection against invoking
113 there is no such module at the specified location.
115 The optional dictionary argument *init_globals* may be used to pre-populate
116 the module's globals dictionary before the code is executed. The supplied
123 dictionary before the module code is executed (Note that this is a
124 minimal set of variables - other variables may be set implicitly as an
127 ``__name__`` is set to *run_name* if this optional argument is not
135 If the supplied path is a reference to a valid sys.path entry, then
137 module (that is, ``__spec__.name`` will always be ``__main__``).
139 :ref:`set as normal <import-mod-attrs>` based on the module spec.
141 A number of alterations are also made to the :mod:`sys` module. Firstly,
142 ``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated
143 with the value of ``path_name`` and ``sys.modules[__name__]`` is updated
144 with a temporary module object for the module being executed. All
150 allowing the execution of sys.path entries. As the thread-safety
155 :ref:`using-on-interface-options` for equivalent functionality on the
161 Updated to take advantage of the module spec feature added by
163 case where ``__main__`` is imported from a valid sys.path entry rather
168 :pep:`338` -- Executing modules as scripts
171 :pep:`366` -- Main module explicit relative imports
174 :pep:`451` -- A ModuleSpec Type for the Import System
177 :ref:`using-on-general` - CPython command line details