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

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