__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__'. Вместо этого такие файлы оставляют короткими и импортируют из них функции, выполняемые в других модулях. Эти другие модули можно легко покрыть модульными тестами, и их удобно повторно использовать.

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

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

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