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

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