`main`——顶级代码环境¶

在 Python 中，特殊名称 __main__ 用于两个重要构造

程序的顶级环境的名称，可以使用 __name__ == '__main__' 表达式进行检查；以及
Python 包中的 __main__.py 文件。

这两种机制都与 Python 模块相关；用户如何与它们交互以及它们如何相互交互。它们将在下面详细解释。如果您是 Python 模块的新手，请参阅教程部分模块以进行介绍。

`name == 'main'`¶

导入 Python 模块或包时，__name__ 设置为模块的名称。通常，这是 Python 文件本身的名称，不带 .py 扩展名

>>> import configparser
>>> configparser.__name__
'configparser'

如果文件是包的一部分，__name__ 还将包括父包的路径

>>> from concurrent.futures import process
>>> process.__name__
'concurrent.futures.process'

但是，如果模块在顶级代码环境中执行，则其 __name__ 设置为字符串 '__main__'。

什么是“顶级代码环境”？¶

__main__ 是运行顶级代码的环境的名称。“顶级代码”是开始运行的第一个用户指定的 Python 模块。它是“顶级”，因为它导入程序所需的所有其他模块。有时“顶级代码”被称为应用程序的入口点。

顶级代码环境可以是

交互式提示符的范围
```
>>> __name__
'__main__'
```
作为文件参数传递给 Python 解释器的 Python 模块
```
$ python helloworld.py
Hello, world!
```
使用 -m 参数传递给 Python 解释器的 Python 模块或包
```
$ python -m tarfile
usage: tarfile.py [-h] [-v] (...)
```

Python 解释器从标准输入中读取的 Python 代码

$ echo "import this" | python
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...

使用 -c 参数传递给 Python 解释器的 Python 代码

$ python -c "import this"
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...

在每种情况下，顶级模块的 __name__ 都设置为 '__main__'。

因此，模块可以通过检查其自己的 __name__ 来发现它是否在顶级环境中运行，这允许在未从 import 语句初始化模块时有条件地执行代码的通用惯用法

if __name__ == '__main__':
    # Execute when the module is not initialized from an import statement.
    ...

另请参阅

有关 __name__ 在所有情况下如何设置的更详细说明，请参阅教程部分模块。

惯用用法¶

某些模块包含仅供脚本使用的代码，例如解析命令行参数或从标准输入中获取数据。如果此类模块是从其他模块导入的，例如对其进行单元测试，则脚本代码也会无意中执行。

这就是使用 if __name__ == '__main__' 代码块派上用场的地方。除非模块在顶级环境中执行，否则此块中的代码不会运行。

在 if __name__ == '__main__' 下方的块中尽可能少地放置语句可以提高代码清晰度和正确性。通常，名为 main 的函数封装程序的主要行为

# echo.py

import shlex
import sys

def echo(phrase: str) -> None:
   """A dummy wrapper around print."""
   # for demonstration purposes, you can imagine that there is some
   # valuable and reusable logic inside this function
   print(phrase)

def main() -> int:
    """Echo the input arguments to standard output"""
    phrase = shlex.join(sys.argv)
    echo(phrase)
    return 0

if __name__ == '__main__':
    sys.exit(main())  # next section explains the use of sys.exit

请注意，如果模块没有将代码封装在 main 函数中，而是直接将其放在 if __name__ == '__main__' 块中，则 phrase 变量将成为整个模块的全局变量。这是容易出错的，因为模块中的其他函数可能会无意中使用全局变量而不是局部名称。一个 main 函数解决了这个问题。

使用 main 函数的另一个好处是 echo 函数本身被隔离并可以在其他地方导入。当导入 echo.py 时，将定义 echo 和 main 函数，但它们都不会被调用，因为 __name__ != '__main__'。

打包注意事项¶

main 函数通常用于通过将它们指定为控制台脚本的入口点来创建命令行工具。这样做时，pip 会将函数调用插入模板脚本中，其中 main 的返回值传递给 sys.exit()。例如

sys.exit(main())

由于对 main 的调用被包装在 sys.exit() 中，因此预期您的函数将返回一些可作为 sys.exit() 输入接受的值；通常，是一个整数或 None（如果您的函数没有返回语句，则会隐式返回）。

通过主动遵循此约定，我们的模块在直接运行（即 python echo.py）时将具有与稍后将其打包为 pip 可安装包中的控制台脚本入口点时的相同行为。

特别是，请小心从 main 函数返回字符串。 sys.exit() 会将字符串参数解释为失败消息，因此您的程序的退出代码将为 1，表示失败，并且该字符串将被写入 sys.stderr。前面的 echo.py 示例举例说明了如何使用 sys.exit(main()) 约定。

另请参阅

Python 打包用户指南包含有关如何使用现代工具分发和安装 Python 包的教程和参考。

`main.py` 在 Python 包中¶

如果您不熟悉 Python 包，请参阅教程的包部分。最常见的是， __main__.py 文件用于为包提供命令行界面。考虑以下假设包“bandclass”

bandclass
  ├── __init__.py
  ├── __main__.py
  └── student.py

当使用 -m 标志直接从命令行调用包本身时，将执行 __main__.py。例如

$ python -m bandclass

此命令将导致 __main__.py 运行。您如何利用此机制将取决于您编写的包的性质，但在这种假设情况下，允许教师搜索学生可能是有意义的

# bandclass/__main__.py

import sys
from .student import search_students

student_name = sys.argv[1] if len(sys.argv) >= 2 else ''
print(f'Found student: {search_students(student_name)}')

请注意，from .student import search_students 是相对导入的一个示例。在包中引用模块时，可以使用这种导入样式。有关更多详细信息，请参阅教程的包内引用部分中的模块。

惯用用法¶

__main__.py 的内容通常不会用 if __name__ == '__main__' 块进行隔离。相反，这些文件保持简洁，并导入函数以从其他模块执行。然后，可以轻松地对这些其他模块进行单元测试，并且可以正确地重复使用它们。

如果使用，if __name__ == '__main__' 块仍然可以按预期的方式对包中的 __main__.py 文件工作，因为如果导入，其 __name__ 属性将包括包的路径

>>> import asyncio.__main__
>>> asyncio.__main__.__name__
'asyncio.__main__'

但这对 .zip 文件根目录中的 __main__.py 文件不起作用。因此，为了保持一致性，首选一个没有 __name__ 检查的最小 __main__.py。

另请参阅

请参阅venv，了解标准库中带有最小 __main__.py 的包的示例。它不包含 if __name__ == '__main__' 块。您可以使用 python -m venv [directory] 调用它。

请参阅runpy，以了解解释器可执行文件的 -m 标志的更多详细信息。

请参阅 zipapp，了解如何运行打包为 .zip 文件的应用程序。在这种情况下，Python 会在存档的根目录中查找 __main__.py 文件。

`import main`¶

无论使用哪个模块启动 Python 程序，在同一程序中运行的其他模块都可以通过导入 __main__ 模块来导入顶级环境的作用域（命名空间）。这不会导入 __main__.py 文件，而是导入收到特殊名称 '__main__' 的任何模块。

这是一个使用 __main__ 命名空间的示例模块

# namely.py

import __main__

def did_user_define_their_name():
    return 'my_name' in dir(__main__)

def print_user_name():
    if not did_user_define_their_name():
        raise ValueError('Define the variable `my_name`!')

    if '__file__' in dir(__main__):
        print(__main__.my_name, "found in file", __main__.__file__)
    else:
        print(__main__.my_name)

此模块的示例用法如下

# start.py

import sys

from namely import print_user_name

# my_name = "Dinsdale"

def main():
    try:
        print_user_name()
    except ValueError as ve:
        return str(ve)

if __name__ == "__main__":
    sys.exit(main())

现在，如果我们启动程序，结果将如下所示

$ python start.py
Define the variable `my_name`!

程序的退出代码将为 1，表示错误。取消对带有 my_name = "Dinsdale" 的行的注释将修复程序，现在它将退出，状态代码为 0，表示成功

$ python start.py
Dinsdale found in file /path/to/start.py

请注意，导入 __main__ 不会导致意外运行 if __name__ == "__main__" 块中放置的用于脚本使用的顶级代码的任何问题，该代码位于 start 模块中。这是为什么？

Python 在解释器启动时在 sys.modules 中插入一个空的 __main__ 模块，并通过运行顶级代码填充它。在我们的示例中，这是 start 模块，它逐行运行并导入 namely。反过来，namely 导入 __main__（实际上是 start）。这是一个导入循环！幸运的是，由于部分填充的 __main__ 模块存在于 sys.modules 中，Python 将其传递给 namely。有关其工作原理的详细信息，请参阅导入系统参考中的 __main__ 的特殊注意事项。

Python REPL 是“顶级环境”的另一个示例，因此在 REPL 中定义的任何内容都将成为 __main__ 作用域的一部分

>>> import namely
>>> namely.did_user_define_their_name()
False
>>> namely.print_user_name()
Traceback (most recent call last):
...
ValueError: Define the variable `my_name`!
>>> my_name = 'Jabberwocky'
>>> namely.did_user_define_their_name()
True
>>> namely.print_user_name()
Jabberwocky

请注意，在这种情况下，__main__ 作用域不包含 __file__ 属性，因为它具有交互性。

在 pdb 和 rlcompleter 的实现中使用了 __main__ 作用域。

`main`——顶级代码环境¶

`name == 'main'`¶

什么是“顶级代码环境”？¶

惯用用法¶

打包注意事项¶

`main.py` 在 Python 包中¶

惯用用法¶

`import main`¶

目录

上一主题

下一主题

此页

__main__——顶级代码环境¶

__name__ == '__main__'¶

什么是“顶级代码环境”？¶

惯用用法¶

打包注意事项¶

__main__.py 在 Python 包中¶

惯用用法¶

import __main__¶

`main`——顶级代码环境¶

`name == 'main'`¶

`main.py` 在 Python 包中¶

`import main`¶