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