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