Lines Matching +full:import +full:- +full:module
1 :mod:`__main__` --- Top-level code environment
4 .. module:: __main__
5 :synopsis: The environment where top-level code is run. Covers command-line
6 interfaces, import-time behavior, and ``__name__ == '__main__'``.
8 --------------
12 1. the name of the top-level environment of the program, which can be
19 :ref:`tut-modules` for an introduction.
25 ---------------------------
27 When a Python module or package is imported, ``__name__`` is set to the
28 module's name. Usually, this is the name of the Python file itself without the
31 >>> import configparser
38 >>> from concurrent.futures import process
42 However, if the module is executed in the top-level code environment,
45 What is the "top-level code environment"?
48 ``__main__`` is the name of the environment where top-level code is run.
49 "Top-level code" is the first user-specified Python module that starts running.
50 It's "top-level" because it imports all other modules that the program needs.
51 Sometimes "top-level code" is called an *entry point* to the application.
53 The top-level code environment can be:
60 * the Python module passed to the Python interpreter as a file argument:
62 .. code-block:: shell-session
67 * the Python module or package passed to the Python interpreter with the
68 :option:`-m` argument:
70 .. code-block:: shell-session
72 $ python3 -m tarfile
73 usage: tarfile.py [-h] [-v] (...)
77 .. code-block:: shell-session
79 $ echo "import this" | python3
86 * Python code passed to the Python interpreter with the :option:`-c` argument:
88 .. code-block:: shell-session
90 $ python3 -c "import this"
97 In each of these situations, the top-level module's ``__name__`` is set to
100 As a result, a module can discover whether or not it is running in the
101 top-level environment by checking its own ``__name__``, which allows a common
102 idiom for conditionally executing code when the module is not initialized from
103 an import statement::
106 # Execute when the module is not initialized from an import statement.
112 the tutorial section :ref:`tut-modules`.
119 command-line arguments or fetching data from standard input. If a module
120 like this was imported from a different module, for example to unit test
124 handy. Code within this block won't run unless the module is executed in the
125 top-level environment.
133 import shlex
134 import sys
136 def echo(phrase: str) -> None:
142 def main() -> int:
151 Note that if the module didn't encapsulate code inside the ``main`` function
153 the ``phrase`` variable would be global to the entire module. This is
154 error-prone as other functions within the module could be unintentionally using
167 ``main`` functions are often used to create command-line tools by specifying
180 By proactively following this convention ourselves, our module will have the
182 we later package it as a console script entry-point in a pip-installable
199 ----------------------------------
201 If you are not familiar with Python packages, see section :ref:`tut-packages`
203 a command-line interface for a package. Consider the following hypothetical
206 .. code-block:: text
214 directly from the command line using the :option:`-m` flag. For example:
216 .. code-block:: shell-session
218 $ python3 -m bandclass
227 import sys
228 from .student import search_students
233 Note that ``from .student import search_students`` is an example of a relative
234 import. This import style can be used when referencing modules within a
235 package. For more details, see :ref:`intra-package-references` in the
236 :ref:`tut-modules` section of the tutorial.
244 easily unit-tested and are properly reusable.
250 >>> import asyncio.__main__
262 block. You can invoke it with ``python -m venv [directory]``.
264 See :mod:`runpy` for more details on the :option:`-m` flag to the
273 ``import __main__``
274 -------------------
276 Regardless of which module a Python program was started with, other modules
277 running within that same program can import the top-level environment's scope
278 (:term:`namespace`) by importing the ``__main__`` module. This doesn't import
279 a ``__main__.py`` file but rather whichever module that received the special
282 Here is an example module that consumes the ``__main__`` namespace::
286 import __main__
300 Example usage of this module could be as follows::
304 import sys
306 from namely import print_user_name
321 .. code-block:: shell-session
330 .. code-block:: shell-session
336 running top-level code meant for script use which is put in the
337 ``if __name__ == "__main__"`` block of the ``start`` module. Why does this work?
339 Python inserts an empty ``__main__`` module in :attr:`sys.modules` at
340 interpreter startup, and populates it by running top-level code. In our example
341 this is the ``start`` module which runs line by line and imports ``namely``.
343 import cycle! Fortunately, since the partially populated ``__main__``
344 module is present in :attr:`sys.modules`, Python passes that to ``namely``.
345 See :ref:`Special considerations for __main__ <import-dunder-main>` in the
346 import system's reference for details on how this works.
348 The Python REPL is another example of a "top-level environment", so anything
351 >>> import namely