__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__, что позволяет использовать общую идиому для условного выполнения кода, когда модуль не инициализирован с помощью инструкции import:

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, упомянутые ниже.