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

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.

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.

PYTHONINSPECT

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

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

PYTHONUNBUFFERED

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

PYTHONVERBOSE

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

PYTHONCASEOK

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

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.8.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. Работает только на Mac OS X.

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 пропустить принудительное преобразование устаревших локали C и POSIX на основе ASCII в более функциональную альтернативу на основе 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

Если эта переменная окружения установлена в строку отличную от пустой, включите режим разработки CPython. См. опцию -X dev.

Новое в версии 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. Однако они по-прежнему используют обработчик ошибок strict по умолчанию, поэтому попытка открыть двоичный файл в текстовом режиме, скорее всего, вызовет исключение, а не произведёт бессмысленные данные.

Обратите внимание, что стандартные параметры потоков в режиме UTF-8 можно переопределить с помощью PYTHONIOENCODING (точно так же, как и в режиме распознавания локали по умолчанию).

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

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

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

Также доступно как опция -X utf8.

Новое в версии 3.7: См. PEP 540 для получения более подробной информации.