__main__ — Основная среда кода

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

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

Основная среда кода может быть:

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

  >>> __name__
  '__main__'
  

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

  $ python3 helloworld.py
  Hello, world!
  

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

  $ python3 -m tarfile
  usage: tarfile.py [-h] [-v] (...)
  

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

  $ echo "import this" | python3
  The Zen of Python, by Tim Peters
  
  Beautiful is better than ugly.
  Explicit is better than implicit.
  ...
  

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

  $ python3 -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 (что неявно возвращается, если ваша функция не имеет оператора возврата).

Активно следуя этой конвенции, наш модуль будет иметь такое же поведение при запуске напрямую (т. е. python3 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, такие как упомянутый ниже venv.