Командная строка и среда

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

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

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

Наиболее распространённым случаем является, конечно, простой вызов скрипта:

python myscript.py

1.2. Переменные среды

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

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  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn

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

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 пропустить принудительное преобразование устаревших ASCII-базовых локалей C и POSIX к более мощному варианту на основе UTF-8.

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

• C.UTF-8
• C.utf8
• UTF-8

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

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