1. Командная строка и окружение¶Command line and environment

1.1. Командная строка¶Command line

При запуске Python можно указать любые из этих опций:

python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]

Наиболее распространённый вариант использования – это простой запуск скрипта:

python myscript.py

1.2. Переменные окружения¶Environment variables

Эти переменные окружения влияют на поведение Python, они обрабатываются до параметров командной строки, кроме -E или -I. Принято, что параметры командной строки переопределяют переменные окружения в случае конфликта.

PYTHONHOME¶

Изменяет расположение стандартных библиотек Python. По умолчанию библиотеки ищутся в prefix/lib/pythonversion и exec_prefix/lib/pythonversion, где prefix и exec_prefix – это каталоги, зависящие от установки; оба по умолчанию имеют значение /usr/local.

Когда PYTHONHOME установлен в один каталог, его значение заменяет оба prefix и exec_prefix. Чтобы указать для них разные значения, установите PYTHONHOME в prefix:exec_prefix.

PYTHONPATH¶

Дополняет путь поиска модулей по умолчанию. Формат такой же, как у PATH оболочки: один или несколько путей к каталогам, разделённых os.pathsep (например, двоеточиями в Unix или точкой с запятой в Windows). Несуществующие каталоги игнорируются без предупреждения.

В дополнение к обычным каталогам, отдельные записи PYTHONPATH могут ссылаться на zip-файлы, содержащие чистые модули Python (в исходной или скомпилированной форме). Модули расширений не могут быть импортированы из zip-файлов.

Путь поиска по умолчанию зависит от установки, но обычно начинается с prefix/lib/pythonversion (см. PYTHONHOME выше). Он всегда добавляется к PYTHONPATH.

Дополнительный каталог будет вставлен в путь поиска перед PYTHONPATH, как описано выше в разделе Параметры интерфейса. Путь поиска можно изменять из программы Python как переменную sys.path.

PYTHONPLATLIBDIR¶

Если эта переменная установлена в непустую строку, она переопределяет значение sys.platlibdir.

Новое в версии 3.9.

PYTHONSTARTUP¶

Если это имя читаемого файла, команды Python из этого файла выполняются перед отображением первого приглашения в интерактивном режиме. Файл выполняется в том же пространстве имён, что и интерактивные команды, поэтому определённые или импортированные в нём объекты могут использоваться без уточнения в интерактивном сеансе. Также в этом файле можно изменить приглашения sys.ps1 и sys.ps2 и хук sys.__interactivehook__.

Вызывает событие аудита cpython.run_startup с именем файла в качестве аргумента при вызове во время запуска.

PYTHONOPTIMIZE¶

Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -O. Если установлено целое число, это эквивалентно указанию -O несколько раз.

PYTHONBREAKPOINT¶

Если эта переменная установлена, она задаёт вызываемый объект в нотации с точками. Модуль, содержащий вызываемый объект, будет импортирован, а затем вызываемый объект будет запущен реализацией по умолчанию sys.breakpointhook(), которая сама вызывается встроенной breakpoint(). Если не установлена или установлена в пустую строку, это эквивалентно значению "pdb.set_trace". Установка в строку "0" заставляет реализацию по умолчанию sys.breakpointhook() ничего не делать и немедленно вернуться.

Добавлено в версии 3.7.

PYTHONDEBUG¶

Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -d. Если установлено целое число, это эквивалентно указанию -d несколько раз.

PYTHONOLDPARSER¶

Если установлено в непустую строку, включает традиционный синтаксический анализатор LL(1).

См. также параметр -X oldparser и PEP 617.

Устарело с версии 3.9, будет удалено в версии 3.10.

PYTHONINSPECT¶

Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -i.

Эта переменная также может быть изменена кодом Python с помощью os.environ, чтобы принудительно включить режим инспектирования при завершении программы.

Возбуждает событие аудита cpython.run_stdin без аргументов.

Изменено в версии 3.9.20: (также 3.8.20) Порождает события аудита.

PYTHONUNBUFFERED¶

Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -u.

PYTHONVERBOSE¶

Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -v. Если установлено целое число, это эквивалентно указанию -v несколько раз.

PYTHONCASEOK¶

Если эта переменная установлена, Python игнорирует регистр в операторах import. Это работает только в Windows и macOS.

PYTHONDONTWRITEBYTECODE¶

Если эта переменная установлена в непустую строку, Python не будет пытаться записывать файлы .pyc при импорте исходных модулей. Это эквивалентно указанию опции -B.

PYTHONPYCACHEPREFIX¶

Если эта переменная установлена, Python будет записывать файлы .pyc в зеркальное дерево каталогов по указанному пути, вместо каталогов __pycache__ внутри исходного дерева. Это эквивалентно указанию опции -X pycache_prefix=PATH.

Новое в версии 3.8.

PYTHONHASHSEED¶

Если эта переменная не установлена или установлена в random, используется случайное значение для инициализации хешей объектов str и bytes.

Если PYTHONHASHSEED установлено в целое число, оно используется как фиксированное начальное значение для генерации hash() для типов, охваченных рандомизацией хешей.

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

Целое число должно быть десятичным числом в диапазоне [0, 4294967295]. Указание значения 0 отключит рандомизацию хешей.

Новое в версии 3.2.3.

PYTHONINTMAXSTRDIGITS¶

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

Новое в версии 3.9.14.

PYTHONIOENCODING¶

Если эта переменная установлена до запуска интерпретатора, она переопределяет кодировку, используемую для stdin/stdout/stderr, в синтаксисе encodingname:errorhandler. Обе части encodingname и :errorhandler необязательны и имеют то же значение, что и в str.encode().

Для stderr часть :errorhandler игнорируется; обработчик всегда будет 'backslashreplace'.

Изменено в версии 3.4: Часть encodingname теперь необязательна.

Изменено в версии 3.6: В Windows кодировка, указанная этой переменной, игнорируется для интерактивных буферов консоли, если также не указана PYTHONLEGACYWINDOWSSTDIO. Файлы и каналы, перенаправленные через стандартные потоки, не затрагиваются.

PYTHONNOUSERSITE¶

Если эта переменная установлена, Python не будет добавлять user site-packages directory в sys.path.

См. также

PEP 370 – Каталог site-packages для каждого пользователя

PYTHONUSERBASE¶

Определяет user base directory, который используется для вычисления пути user site-packages directory и путей установки Distutils для python setup.py install --user.

См. также

PEP 370 – Каталог site-packages для каждого пользователя

PYTHONEXECUTABLE¶

Если эта переменная окружения установлена, sys.argv[0] будет установлено в её значение вместо значения, полученного через C runtime. Работает только на macOS.

PYTHONWARNINGS¶

Это эквивалентно опции -W. Если установлено в строку, разделённую запятыми, это эквивалентно многократному указанию -W, при этом фильтры, находящиеся позже в списке, имеют приоритет над теми, что раньше.

Простейшие настройки применяют определённое действие безусловно ко всем предупреждениям, выдаваемым процессом (даже к тем, которые в противном случае игнорируются по умолчанию):

PYTHONWARNINGS=default  # Предупреждать один раз на место вызова
PYTHONWARNINGS=error    # Преобразовывать в исключения
PYTHONWARNINGS=always   # Предупреждать каждый раз
PYTHONWARNINGS=module   # Предупреждать один раз на вызывающий модуль
PYTHONWARNINGS=once     # Предупреждать один раз на процесс Python
PYTHONWARNINGS=ignore   # Никогда не предупреждать

См. Фильтр предупреждений и Описание фильтров предупреждений для получения дополнительных сведений.

PYTHONFAULTHANDLER¶

Если эта переменная окружения установлена в непустую строку, faulthandler.enable() вызывается при запуске: устанавливается обработчик сигналов SIGSEGV, SIGFPE, SIGABRT, SIGBUS и SIGILL для дампа обратной трассировки Python. Это эквивалентно параметру -X faulthandler.

Новое в версии 3.3.

PYTHONTRACEMALLOC¶

Если эта переменная окружения установлена в непустую строку, начинается трассировка выделений памяти Python с помощью модуля tracemalloc. Значение переменной – максимальное количество кадров, сохраняемых в обратной трассировке. Например, PYTHONTRACEMALLOC=1 сохраняет только самый последний кадр. Дополнительную информацию см. в tracemalloc.start().

Новое в версии 3.4.

PYTHONPROFILEIMPORTTIME¶

Если эта переменная окружения установлена в непустую строку, Python будет показывать, сколько времени занимает каждый импорт. Это в точности эквивалентно указанию -X importtime в командной строке.

Добавлено в версии 3.7.

PYTHONASYNCIODEBUG¶

Если эта переменная окружения установлена в непустую строку, включает режим отладки модуля asyncio.

Новое в версии 3.4.

PYTHONMALLOC¶

Устанавливает аллокаторы памяти Python и/или добавляет отладочные хуки.

Устанавливает семейство аллокаторов памяти, используемых Python:

• default: использовать аллокаторы памяти по умолчанию.

• malloc: использовать функцию malloc() библиотеки C для всех областей (PYMEM_DOMAIN_RAW, PYMEM_DOMAIN_MEM, PYMEM_DOMAIN_OBJ).

• pymalloc: использовать аллокатор pymalloc для областей PYMEM_DOMAIN_MEM и PYMEM_DOMAIN_OBJ, а функцию malloc() – для области PYMEM_DOMAIN_RAW.

Установить отладочные перехватчики:

• debug: установить отладочные хуки поверх аллокаторов памяти по умолчанию.

• malloc_debug: то же, что malloc, но также устанавливает отладочные хуки.

• pymalloc_debug: то же, что pymalloc, но также устанавливает отладочные хуки.

См. стандартные распределители памяти и функцию PyMem_SetupDebugHooks() (установка отладочных перехватчиков на распределители памяти Python).

Изменено в версии 3.7: Добавлен аллокатор "default".

Новое в версии 3.6.

PYTHONMALLOCSTATS¶

Если установлена в непустую строку, Python будет выводить статистику аллокатора памяти pymalloc каждый раз, когда создаётся новая арена объекта pymalloc, а также при завершении работы.

Эта переменная игнорируется, если переменная окружения PYTHONMALLOC используется для принудительного выбора аллокатора malloc() из библиотеки C, или если Python скомпилирован без поддержки pymalloc.

Изменено в версии 3.6: Теперь эту переменную можно также использовать в Python, скомпилированном в режиме релиза. Теперь она не действует, если установлена в пустую строку.

PYTHONLEGACYWINDOWSFSENCODING¶

Если установлено в непустую строку, кодировка файловой системы по умолчанию и режим обработки ошибок вернутся к значениям до версии 3.6: 'mbcs' и 'replace' соответственно. В противном случае используются новые значения по умолчанию: 'utf-8' и 'surrogatepass'.

Это также можно включить во время выполнения с помощью sys._enablelegacywindowsfsencoding().

Доступность: Windows.

Новое в версии 3.6: Подробности см. в PEP 529.

PYTHONLEGACYWINDOWSSTDIO¶

Если задана непустая строка, не использует новые средства чтения и записи консоли. Это означает, что символы Unicode будут кодироваться в соответствии с активной кодовой страницей консоли, а не с помощью utf-8.

Эта переменная игнорируется, если стандартные потоки перенаправлены (в файлы или каналы), а не ссылаются на буферы консоли.

Доступность: Windows.

Новое в версии 3.6.

PYTHONCOERCECLOCALE¶

Если установлена в значение 0, заставляет главное приложение командной строки Python пропустить принудительное преобразование устаревших локалей C и POSIX на основе ASCII в более современную альтернативу на основе UTF-8.

Если эта переменная не установлена (или установлена в значение, отличное от 0), переменная окружения LC_ALL для переопределения локали также не установлена, и текущая локаль для категории LC_CTYPE сообщается как локаль по умолчанию C или явно основанная на ASCII локаль POSIX, то CLI Python попытается настроить следующие локали для категории LC_CTYPE в указанном порядке перед загрузкой среды выполнения интерпретатора:

• C.UTF-8

• C.utf8

• UTF-8

Если установка одной из этих категорий локали проходит успешно, то переменная окружения LC_CTYPE также будет соответствующим образом установлена в окружении текущего процесса до инициализации среды выполнения Python. Это гарантирует, что помимо того, что обновленная настройка видна как самому интерпретатору, так и другим компонентам, учитывающим локаль, работающим в том же процессе (например, библиотеке GNU readline), она также будет видна в подпроцессах (независимо от того, выполняют ли эти процессы интерпретатор Python или нет), а также в операциях, которые запрашивают окружение, а не текущую локаль C (таких как собственная функция locale.getdefaultlocale() в Python).

Настройка одной из этих локалей (явно или через неявное принуждение локали) автоматически включает обработчик ошибок surrogateescape для sys.stdin и sys.stdout (sys.stderr продолжает использовать backslashreplace, как и в любой другой локали). Это поведение обработки потоков можно переопределить, используя PYTHONIOENCODING, как обычно.

В целях отладки установка PYTHONCOERCECLOCALE=warn приведет к тому, что Python будет выводить предупреждающие сообщения в stderr, если либо сработает принуждение локали, либо если локаль, которая должна была бы вызвать принуждение, все еще активна при инициализации среды выполнения Python.

Также обратите внимание, что даже если принуждение локали отключено или не удается найти подходящую целевую локаль, PYTHONUTF8 все равно будет активирован по умолчанию в устаревших локалях на основе ASCII. Обе функции должны быть отключены, чтобы заставить интерпретатор использовать ASCII вместо UTF-8 для системных интерфейсов.

Доступность: *nix.

Новое в версии 3.7: См. PEP 538 для подробностей.

PYTHONDEVMODE¶

Если эта переменная окружения установлена в непустую строку, включается режим разработки Python, вводящий дополнительные проверки во время выполнения, которые слишком дороги для включения по умолчанию.

Добавлено в версии 3.7.

PYTHONUTF8¶

Если установлено в 1, включает режим UTF-8 интерпретатора, при котором UTF-8 используется в качестве кодировки текста для системных интерфейсов, независимо от текущей локали.

Это означает, что:

• sys.getfilesystemencoding() возвращает 'UTF-8' (кодировка локали игнорируется).

• locale.getpreferredencoding() возвращает 'UTF-8' (кодировка локали игнорируется, а параметр do_setlocale функции не действует).

• sys.stdin, sys.stdout и sys.stderr все используют UTF-8 в качестве текстовой кодировки, при этом surrogateescape обработчик ошибок включён для sys.stdin и sys.stdout (sys.stderr продолжает использовать backslashreplace, как и в режиме по умолчанию с учётом локали)

Вследствие изменений в этих низкоуровневых API другие высокоуровневые API также демонстрируют другое поведение по умолчанию:

• Аргументы командной строки, переменные окружения и имена файлов декодируются в текст с использованием кодировки UTF-8.

• os.fsdecode() и os.fsencode() используют кодировку UTF-8.

• open(), io.open() и codecs.open() по умолчанию используют кодировку UTF-8. Однако по умолчанию они также используют строгий обработчик ошибок, так что попытка открыть двоичный файл в текстовом режиме, скорее всего, вызовет исключение, а не вернёт бессмысленные данные.

Обратите внимание: настройки стандартных потоков в режиме UTF-8 могут быть переопределены с помощью PYTHONIOENCODING (как и в режиме по умолчанию с учётом локали).

Если установлено в 0, интерпретатор работает в режиме, зависящем от локали по умолчанию.

Установка любой другой непустой строки вызывает ошибку при инициализации интерпретатора.

Если эта переменная окружения не установлена вовсе, интерпретатор по умолчанию использует текущие настройки локали, если только текущая локаль не определена как устаревшая ASCII-ориентированная локаль (как описано для PYTHONCOERCECLOCALE), и принудительное изменение локали либо отключено, либо не удаётся. В таких устаревших локалях интерпретатор по умолчанию включает режим UTF-8, если явно не указано иное.

Также доступен как параметр -X utf8.

Новое в версии 3.7: См. PEP 540 для получения дополнительных сведений.