Debian Codegraph @

Doc/library/__main__.rst

raw
1 :mod:`!__main__` --- Top-level code environment
2 ===============================================
3
4 .. module:: __main__
5 :synopsis: The environment where top-level code is run. Covers command-line
6 interfaces, import-time behavior, and ``__name__ == '__main__'``.
7
8 --------------
9
10 In Python, the special name ``__main__`` is used for two important constructs:
11
12 1. the name of the top-level environment of the program, which can be
13 checked using the ``__name__ == '__main__'`` expression; and
14 2. the ``__main__.py`` file in Python packages.
15
16 Both of these mechanisms are related to Python modules; how users interact with
17 them and how they interact with each other. They are explained in detail
18 below. If you're new to Python modules, see the tutorial section
19 :ref:`tut-modules` for an introduction.
20
21
22 .. _name_equals_main:
23
24 ``__name__ == '__main__'``
25 ---------------------------
26
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
29 ``.py`` extension::
30
31 >>> import configparser
32 >>> configparser.__name__
33 'configparser'
34
35 If the file is part of a package, ``__name__`` will also include the parent
36 package's path::
37
38 >>> from concurrent.futures import process
39 >>> process.__name__
40 'concurrent.futures.process'
41
42 However, if the module is executed in the top-level code environment,
43 its ``__name__`` is set to the string ``'__main__'``.
44
45 What is the "top-level code environment"?
46 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
47
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.
52
53 The top-level code environment can be:
54
55 * the scope of an interactive prompt::
56
57 >>> __name__
58 '__main__'
59
60 * the Python module passed to the Python interpreter as a file argument:
61
62 .. code-block:: shell-session
63
64 $ python helloworld.py
65 Hello, world!
66
67 * the Python module or package passed to the Python interpreter with the
68 :option:`-m` argument:
69
70 .. code-block:: shell-session
71
72 $ python -m tarfile
73 usage: tarfile.py [-h] [-v] (...)
74
75 * Python code read by the Python interpreter from standard input:
76
77 .. code-block:: shell-session
78
79 $ echo "import this" | python
80 The Zen of Python, by Tim Peters
81
82 Beautiful is better than ugly.
83 Explicit is better than implicit.
84 ...
85
86 * Python code passed to the Python interpreter with the :option:`-c` argument:
87
88 .. code-block:: shell-session
89
90 $ python -c "import this"
91 The Zen of Python, by Tim Peters
92
93 Beautiful is better than ugly.
94 Explicit is better than implicit.
95 ...
96
97 In each of these situations, the top-level module's ``__name__`` is set to
98 ``'__main__'``.
99
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::
104
105 if __name__ == '__main__':
106 # Execute when the module is not initialized from an import statement.
107 ...
108
109 .. seealso::
110
111 For a more detailed look at how ``__name__`` is set in all situations, see
112 the tutorial section :ref:`tut-modules`.
113
114
115 Idiomatic Usage
116 ^^^^^^^^^^^^^^^
117
118 Some modules contain code that is intended for script use only, like parsing
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
121 it, the script code would unintentionally execute as well.
122
123 This is where using the ``if __name__ == '__main__'`` code block comes in
124 handy. Code within this block won't run unless the module is executed in the
125 top-level environment.
126
127 Putting as few statements as possible in the block below ``if __name__ ==
128 '__main__'`` can improve code clarity and correctness. Most often, a function
129 named ``main`` encapsulates the program's primary behavior::
130
131 # echo.py
132
133 import shlex
134 import sys
135
136 def echo(phrase: str) -> None:
137 """A dummy wrapper around print."""
138 # for demonstration purposes, you can imagine that there is some
139 # valuable and reusable logic inside this function
140 print(phrase)
141
142 def main() -> int:
143 """Echo the input arguments to standard output"""
144 phrase = shlex.join(sys.argv)
145 echo(phrase)
146 return 0
147
148 if __name__ == '__main__':
149 sys.exit(main()) # next section explains the use of sys.exit
150
151 Note that if the module didn't encapsulate code inside the ``main`` function
152 but instead put it directly within the ``if __name__ == '__main__'`` block,
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
155 the global variable instead of a local name. A ``main`` function solves this
156 problem.
157
158 Using a ``main`` function has the added benefit of the ``echo`` function itself
159 being isolated and importable elsewhere. When ``echo.py`` is imported, the
160 ``echo`` and ``main`` functions will be defined, but neither of them will be
161 called, because ``__name__ != '__main__'``.
162
163
164 Packaging Considerations
165 ^^^^^^^^^^^^^^^^^^^^^^^^
166
167 ``main`` functions are often used to create command-line tools by specifying
168 them as entry points for console scripts. When this is done,
169 `pip <https://pip.pypa.io/>`_ inserts the function call into a template script,
170 where the return value of ``main`` is passed into :func:`sys.exit`.
171 For example::
172
173 sys.exit(main())
174
175 Since the call to ``main`` is wrapped in :func:`sys.exit`, the expectation is
176 that your function will return some value acceptable as an input to
177 :func:`sys.exit`; typically, an integer or ``None`` (which is implicitly
178 returned if your function does not have a return statement).
179
180 By proactively following this convention ourselves, our module will have the
181 same behavior when run directly (i.e. ``python echo.py``) as it will have if
182 we later package it as a console script entry-point in a pip-installable
183 package.
184
185 In particular, be careful about returning strings from your ``main`` function.
186 :func:`sys.exit` will interpret a string argument as a failure message, so
187 your program will have an exit code of ``1``, indicating failure, and the
188 string will be written to :data:`sys.stderr`. The ``echo.py`` example from
189 earlier exemplifies using the ``sys.exit(main())`` convention.
190
191 .. seealso::
192
193 `Python Packaging User Guide <https://packaging.python.org/>`_
194 contains a collection of tutorials and references on how to distribute and
195 install Python packages with modern tools.
196
197
198 ``__main__.py`` in Python Packages
199 ----------------------------------
200
201 If you are not familiar with Python packages, see section :ref:`tut-packages`
202 of the tutorial. Most commonly, the ``__main__.py`` file is used to provide
203 a command-line interface for a package. Consider the following hypothetical
204 package, "bandclass":
205
206 .. code-block:: text
207
208 bandclass
209 ├── __init__.py
210 ├── __main__.py
211 └── student.py
212
213 ``__main__.py`` will be executed when the package itself is invoked
214 directly from the command line using the :option:`-m` flag. For example:
215
216 .. code-block:: shell-session
217
218 $ python -m bandclass
219
220 This command will cause ``__main__.py`` to run. How you utilize this mechanism
221 will depend on the nature of the package you are writing, but in this
222 hypothetical case, it might make sense to allow the teacher to search for
223 students::
224
225 # bandclass/__main__.py
226
227 import sys
228 from .student import search_students
229
230 student_name = sys.argv[1] if len(sys.argv) >= 2 else ''
231 print(f'Found student: {search_students(student_name)}')
232
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.
237
238 Idiomatic Usage
239 ^^^^^^^^^^^^^^^
240
241 The content of ``__main__.py`` typically isn't fenced with an
242 ``if __name__ == '__main__'`` block. Instead, those files are kept
243 short and import functions to execute from other modules. Those other modules can then be
244 easily unit-tested and are properly reusable.
245
246 If used, an ``if __name__ == '__main__'`` block will still work as expected
247 for a ``__main__.py`` file within a package, because its ``__name__``
248 attribute will include the package's path if imported::
249
250 >>> import asyncio.__main__
251 >>> asyncio.__main__.__name__
252 'asyncio.__main__'
253
254 This won't work for ``__main__.py`` files in the root directory of a
255 ``.zip`` file though. Hence, for consistency, a minimal ``__main__.py``
256 without a ``__name__`` check is preferred.
257
258 .. seealso::
259
260 See :mod:`venv` for an example of a package with a minimal ``__main__.py``
261 in the standard library. It doesn't contain a ``if __name__ == '__main__'``
262 block. You can invoke it with ``python -m venv [directory]``.
263
264 See :mod:`runpy` for more details on the :option:`-m` flag to the
265 interpreter executable.
266
267 See :mod:`zipapp` for how to run applications packaged as *.zip* files. In
268 this case Python looks for a ``__main__.py`` file in the root directory of
269 the archive.
270
271
272
273 ``import __main__``
274 -------------------
275
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
280 name ``'__main__'``.
281
282 Here is an example module that consumes the ``__main__`` namespace::
283
284 # namely.py
285
286 import __main__
287
288 def did_user_define_their_name():
289 return 'my_name' in dir(__main__)
290
291 def print_user_name():
292 if not did_user_define_their_name():
293 raise ValueError('Define the variable `my_name`!')
294
295 print(__main__.my_name)
296
297 Example usage of this module could be as follows::
298
299 # start.py
300
301 import sys
302
303 from namely import print_user_name
304
305 # my_name = "Dinsdale"
306
307 def main():
308 try:
309 print_user_name()
310 except ValueError as ve:
311 return str(ve)
312
313 if __name__ == "__main__":
314 sys.exit(main())
315
316 Now, if we started our program, the result would look like this:
317
318 .. code-block:: shell-session
319
320 $ python start.py
321 Define the variable `my_name`!
322
323 The exit code of the program would be 1, indicating an error. Uncommenting the
324 line with ``my_name = "Dinsdale"`` fixes the program and now it exits with
325 status code 0, indicating success:
326
327 .. code-block:: shell-session
328
329 $ python start.py
330 Dinsdale
331
332 Note that importing ``__main__`` doesn't cause any issues with unintentionally
333 running top-level code meant for script use which is put in the
334 ``if __name__ == "__main__"`` block of the ``start`` module. Why does this work?
335
336 Python inserts an empty ``__main__`` module in :data:`sys.modules` at
337 interpreter startup, and populates it by running top-level code. In our example
338 this is the ``start`` module which runs line by line and imports ``namely``.
339 In turn, ``namely`` imports ``__main__`` (which is really ``start``). That's an
340 import cycle! Fortunately, since the partially populated ``__main__``
341 module is present in :data:`sys.modules`, Python passes that to ``namely``.
342 See :ref:`Special considerations for __main__ <import-dunder-main>` in the
343 import system's reference for details on how this works.
344
345 The Python REPL is another example of a "top-level environment", so anything
346 defined in the REPL becomes part of the ``__main__`` scope::
347
348 >>> import namely
349 >>> namely.did_user_define_their_name()
350 False
351 >>> namely.print_user_name()
352 Traceback (most recent call last):
353 ...
354 ValueError: Define the variable `my_name`!
355 >>> my_name = 'Jabberwocky'
356 >>> namely.did_user_define_their_name()
357 True
358 >>> namely.print_user_name()
359 Jabberwocky
360
361 The ``__main__`` scope is used in the implementation of :mod:`pdb` and
362 :mod:`rlcompleter`.