__main__ — Окружение кода верхнего уровня

Что такое «среда кода верхнего уровня»?

__main__ — это имя среды, в которой выполняется код верхнего уровня. «Код верхнего уровня» — это первый указанный пользователем модуль Python, который начинает выполняться. Он является «верхним уровнем», потому что импортирует все остальные модули, необходимые программе. Иногда «код верхнего уровня» называют точкой входа в приложение.

Среда кода верхнего уровня может быть:

• областью интерактивного приглашения:

  >>> __name__
  '__main__'
  

• модулем Python, переданным интерпретатору Python в качестве аргумента файла:

  $ python helloworld.py
  Hello, world!
  

• модулем или пакетом Python, переданным интерпретатору Python с аргументом -m:

  $ 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.
  ...
  

• код Python, переданный интерпретатору Python с аргументом -c:

  $ python -c "import this"
  The Zen of Python, by Tim Peters
  
  Beautiful is better than ugly.
  Explicit is better than implicit.
  ...
  

В каждом из этих случаев __name__ верхнего уровня модуля устанавливается в значение '__main__'.

В результате модуль может определить, выполняется ли он в среде верхнего уровня, проверив собственное __name__, что позволяет использовать общее выражение для условного выполнения кода, когда модуль не инициализирован из инструкции импорта:

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

Идиоматическое использование

Некоторые модули содержат код, предназначенный только для использования в скриптах, например, для разбора аргументов командной строки или получения данных из стандартного ввода. Если такой модуль был импортирован из другого модуля, например, для модульного тестирования, скриптовый код также будет непреднамеренно выполняться.

Вот где пригождается блок кода 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 (которое подразумевается, если ваша функция не имеет инструкции return).

Активно следуя этой конвенции, наш модуль будет иметь такое же поведение при прямом запуске (т. е. python echo.py) , как и при последующем его упаковке как точки входа скрипта консоли в устанавливаемый с помощью pip пакет.

В частности, будьте внимательны при возвращении строк из вашей функции main. sys.exit() будет интерпретировать строковый аргумент как сообщение об ошибке, поэтому ваша программа получит код выхода 1, указывающий на ошибку, а строка будет выведена в sys.stderr. Пример echo.py из предыдущего примера демонстрирует использование конвенции sys.exit(main()).

Идиоматическое использование

Содержание файла __main__.py обычно не заключено в блок if __name__ == '__main__'. Вместо этого эти файлы сохраняются короткими и импортируют функции для выполнения из других модулей. Эти другие модули могут быть легко протестированы и повторно использованы.

Если используется, блок if __name__ == '__main__' по-прежнему будет работать как ожидалось для файла __main__.py в рамках пакета, потому что его атрибут __name__ будет включать путь к пакету при импорте:

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

Однако это не будет работать для файлов __main__.py в корневой директории файла .zip. Поэтому для согласованности предпочтительнее минимальный файл __main__.py без проверки __name__.