__main__ – Среда кода верхнего уровня¶__main__ – Top-level code environment

Что такое «среда кода верхнего уровня»?¶What is the “top-level code environment”?

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

Идиоматическое использование¶Idiomatic Usage

Некоторые модули содержат код, предназначенный только для использования в скриптах, например разбор аргументов командной строки или получение данных из стандартного ввода. Если такой модуль импортируется из другого модуля, например для модульного тестирования, код скрипта также непреднамеренно выполнится.

Здесь пригождается использование блока кода if __name__ == '__main__'. Код внутри этого блока не будет выполняться, пока модуль не будет запущен в среде верхнего уровня.

Размещение как можно меньшего количества операторов в блоке ниже if __name___ == '__main__' может улучшить ясность и корректность кода. Чаще всего функция с именем main инкапсулирует основное поведение программы:

# echo.py

import shlex
import sys

def echo(phrase: str) -> None:
   """Пустая обёртка вокруг print."""
   # для целей демонстрации можно представить, что существует некоторая
   # ценная и повторно используемая логика внутри этой функции
   print(phrase)

def main() -> int:
    """Выводит входные аргументы в стандартный вывод"""
    phrase = shlex.join(sys.argv)
    echo(phrase)
    return 0

if __name__ == '__main__':
    sys.exit(main())  # в следующем разделе объясняется использование sys.exit

Обратите внимание: если бы модуль не инкапсулировал код внутри функции main, а поместил бы его непосредственно в блок if __name__ == '__main__', переменная phrase была бы глобальной для всего модуля. Это чревато ошибками, так как другие функции в модуле могли бы случайно использовать глобальную переменную вместо локального имени. Функция main решает эту проблему.

Использование функции main даёт дополнительное преимущество: сама функция echo изолируется и может быть импортирована в другом месте. При импорте echo.py функции echo и main будут определены, но ни одна из них не будет вызвана, потому что __name__ != '__main__'.

Особенности упаковки¶Packaging Considerations

Функции 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()).

Идиоматическое использование¶Idiomatic Usage

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