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

1.1.1. Параметры интерфейса

Интерфейс интерпретатора похож на интерфейс оболочки UNIX, но предоставляет несколько дополнительных способов вызова:

• При запуске со стандартным вводом, подключённым к устройству tty, интерпретатор запрашивает команды и выполняет их до считывания EOF (символа конца файла, который можно ввести с помощью Ctrl-D в UNIX или Ctrl-Z, Enter в Windows).
• При запуске с аргументом-именем файла или с файлом в качестве стандартного ввода интерпретатор считывает и выполняет скрипт из этого файла.
• При запуске с аргументом-именем каталога интерпретатор считывает и выполняет скрипт с соответствующим именем из этого каталога.
• При запуске с -c command интерпретатор выполняет инструкции Python, заданные в качестве команды. Здесь команда может содержать несколько инструкций, разделённых символами новой строки. Начальные пробелы в инструкциях Python имеют значение!
• При запуске с -m module-name указанный модуль ищется в пути поиска модулей Python и выполняется как скрипт.

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

Параметр интерфейса завершает список параметров, обрабатываемых интерпретатором; все последующие аргументы попадут в sys.argv — обратите внимание, что первый элемент с индексом ноль (sys.argv[0]) представляет собой строку, указывающую на источник программы.

-c <command>

Выполнить код Python в команде. Команда может состоять из одной или нескольких инструкций, разделённых символами новой строки; начальные пробелы имеют такое же значение, как и в обычном коде модуля.

Если указан этот параметр, первым элементом sys.argv будет "-c", а текущий каталог будет добавлен в начало sys.path (что позволяет импортировать модули из этого каталога как модули верхнего уровня).

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

-m <module-name>

Найти указанный модуль в sys.path и выполнить его содержимое как модуль __main__.

Поскольку аргументом является имя модуля, указывать расширение файла не нужно (.py). Имя модуля должно быть допустимым абсолютным именем модуля Python, однако реализация может не всегда это проверять (например, она может разрешить использовать имя с дефисом).

Также допускаются имена пакетов (в том числе пакетов пространств имён). Если вместо обычного модуля указано имя пакета, интерпретатор выполнит <pkg>.__main__ в качестве главного модуля. Это поведение намеренно сделано похожим на обработку каталогов и ZIP-файлов, передаваемых интерпретатору в качестве аргумента скрипта.

Примечание

Этот параметр нельзя использовать со встроенными модулями и модулями расширений, написанными на C, поскольку у них нет файлов модулей Python. Однако его можно использовать для предварительно скомпилированных модулей, даже если исходный файл недоступен.

Если указан этот параметр, первым элементом sys.argv будет полный путь к файлу модуля (пока файл модуля ищется, первым элементом будет "-m"). Как и при использовании параметра -c, текущий каталог будет добавлен в начало sys.path.

Параметр -I позволяет запустить скрипт в изолированном режиме, при котором sys.path не содержит ни текущего каталога, ни каталога site-packages пользователя. Также игнорируются все переменные окружения PYTHON*.

Многие модули стандартной библиотеки содержат код, который выполняется при запуске модуля в качестве скрипта. Примером служит модуль timeit:

python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details

Вызывает событие аудита cpython.run_module с аргументом module-name.

См. также

runpy.run_module()

Аналогичная функциональность непосредственно доступна в коде Python

PEP 338 — Выполнение модулей в качестве скриптов

Изменено в версии 3.1: Добавлена возможность указывать имя пакета для запуска подмодуля __main__.

Изменено в версии 3.4: Добавлена поддержка пакетов пространств имён

-

Считывать команды из стандартного ввода (sys.stdin). Если стандартный ввод является терминалом, подразумевается -i.

Если указан этот параметр, первым элементом sys.argv будет "-", а текущий каталог будет добавлен в начало sys.path.

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

<script>

Выполнить код Python, содержащийся в скрипте. Он должен быть путём в файловой системе (абсолютным или относительным), указывающим на файл Python, каталог с файлом __main__.py или ZIP-файл с файлом __main__.py.

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

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

Если имя скрипта указывает на каталог или ZIP-файл, имя скрипта добавляется в начало sys.path, а файл __main__.py в этом расположении выполняется как модуль __main__.

Параметр -I позволяет запустить скрипт в изолированном режиме, при котором sys.path не содержит ни каталога скрипта, ни каталога site-packages пользователя. Также игнорируются все переменные окружения PYTHON*.

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

См. также

runpy.run_path()

Аналогичная функциональность непосредственно доступна в коде Python

Если параметр интерфейса не указан, подразумевается -i, sys.argv[0] — пустая строка (""), а текущий каталог добавляется в начало sys.path. Кроме того, если это поддерживается платформой, автоматически включаются автодополнение по клавише Tab и редактирование истории (см. раздел Настройка Readline).

1.1.2. Общие параметры

-?

-h

--help

Вывести краткое описание всех параметров командной строки и соответствующих переменных окружения и завершить работу.

--help-env

Вывести краткое описание переменных окружения, относящихся к Python, и завершить работу.

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

--help-xoptions

Вывести описание зависящих от реализации параметров -X и завершить работу.

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

--help-all

Вывести полную справочную информацию и завершить работу.

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

-V

--version

Вывести номер версии Python и завершить работу. Пример вывода:

Python 3.8.0b2+

Если указать параметр дважды, будет выведена дополнительная информация о сборке, например:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

Добавлено в версии 3.6: Параметр -VV.

1.1.3. Прочие параметры

-b

Выдавать предупреждение при преобразовании bytes или bytearray в str без указания кодировки, а также при сравнении bytes или bytearray с str или bytes с int. Если параметр указан дважды, выдавать ошибку (-bb).

Изменено в версии 3.5: Также влияет на сравнение bytes с int.

-B

Если указан, Python не будет пытаться записывать файлы .pyc при импорте исходных модулей. См. также PYTHONDONTWRITEBYTECODE.

--check-hash-based-pycs default|always|never

Управлять поведением проверки файлов .pyc на основе хеша. См. Проверка актуальности кэшированного байт-кода. Если задано значение default, проверяемые и непроверяемые файлы кэша байт-кода на основе хеша проверяются согласно их семантике по умолчанию. Если задано значение always, все файлы .pyc на основе хеша, как проверяемые, так и непроверяемые, проверяются на соответствие соответствующему исходному файлу. Если задано значение never, файлы .pyc на основе хеша не проверяются на соответствие соответствующим исходным файлам.

Семантика файлов .pyc на основе временных меток этим параметром не меняется.

-d

Включить вывод отладочной информации парсера (только для экспертов). См. также переменную среды PYTHONDEBUG.

Для этого параметра требуется отладочная сборка Python; в противном случае он игнорируется.

-E

Игнорировать все переменные среды PYTHON*, например PYTHONPATH и PYTHONHOME, если они заданы.

См. также параметры -P и -I (изолированный режим).

-i

Если скрипт передан первым аргументом или используется параметр -c, перейти в интерактивный режим после выполнения скрипта или команды, даже если sys.stdin не является терминалом. Файл PYTHONSTARTUP не считывается.

Это может быть полезно для просмотра глобальных переменных или трассировки стека, если в скрипте возникает исключение. См. также PYTHONINSPECT.

-I

Запустить Python в изолированном режиме. При этом также включаются параметры -E, -P и -s.

В изолированном режиме sys.path не содержит ни каталог скрипта, ни каталог пользовательских пакетов сайта. Все переменные среды PYTHON* также игнорируются. Для предотвращения внедрения пользователем вредоносного кода могут применяться дополнительные ограничения.

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

-O

Удалить инструкции assert и любой код, выполнение которого зависит от значения __debug__. Изменить имя скомпилированных файлов (байт-кода), добавив .opt-1 перед расширением .pyc (см. PEP 488). См. также PYTHONOPTIMIZE.

Изменено в версии 3.5: Изменены имена файлов .pyc в соответствии с PEP 488.

-OO

Выполнить -O, а также удалить строки документации. Изменить имя скомпилированных файлов (байт-кода), добавив .opt-2 перед расширением .pyc (см. PEP 488).

Изменено в версии 3.5: Изменены имена файлов .pyc в соответствии с PEP 488.

-P

Не добавлять потенциально небезопасный путь в начало sys.path:

• python -m module командная строка: не добавлять в начало текущий рабочий каталог.
• python script.py командная строка: не добавлять в начало каталог скрипта. Если это символическая ссылка, разрешить символические ссылки.
• python -c code и python (REPL): не добавлять в начало пустую строку, которая означает текущий рабочий каталог.

См. также переменную среды PYTHONSAFEPATH и параметры -E и -I (изолированный режим).

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

-q

Не отображать сообщения об авторских правах и версии даже в интерактивном режиме.

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

-R

Включить рандомизацию хешей. Этот параметр действует, только если переменной среды PYTHONHASHSEED присвоено значение 0, поскольку рандомизация хешей включена по умолчанию.

В предыдущих версиях Python этот параметр включал рандомизацию хешей, чтобы значения __hash__() объектов str и bytes «солью» дополнялись непредсказуемым случайным значением. Хотя они остаются неизменными в рамках отдельного процесса Python, их нельзя предсказать при повторных запусках Python.

Рандомизация хешей предназначена для защиты от отказа в обслуживании, вызванного специально подобранными входными данными, использующими наихудшую производительность создания dict со сложностью O(n²). Подробнее см. http://ocert.org/advisories/ocert-2011-003.html.

PYTHONHASHSEED позволяет задать фиксированное значение для секрета начального значения хеша.

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

Изменено в версии 3.7: Параметр больше не игнорируется.

-s

Не добавлять user site-packages directory в sys.path.

См. также PYTHONNOUSERSITE.

См. также

PEP 370 – Каталог пакетов сайта для каждого пользователя

-S

Отключить импорт модуля site и связанные с ним изменения sys.path, зависящие от сайта. Также отключить эти изменения, если модуль site явно импортируется позднее (вызовите site.main(), если хотите запустить их).

-u

Принудительно отключить буферизацию потоков stdout и stderr. Этот параметр не влияет на поток stdin.

См. также PYTHONUNBUFFERED.

Изменено в версии 3.7: Текстовый слой потоков stdout и stderr теперь работает без буферизации.

-v

Выводить сообщение при каждой инициализации модуля с указанием места загрузки (имени файла или встроенного модуля). Если параметр указан дважды (-vv), выводить сообщение для каждого файла, проверяемого при поиске модуля. Также выводить сведения об очистке модулей при завершении.

Изменено в версии 3.10: Модуль site сообщает пути, зависящие от сайта, и обрабатываемые файлы .pth.

См. также PYTHONVERBOSE.

-W arg

Управление предупреждениями. По умолчанию механизм предупреждений Python выводит сообщения на sys.stderr.

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

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wall      # Same as -Walways
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

Названия действий можно сокращать по желанию; интерпретатор сопоставит их соответствующему полному названию. Например, -Wi — то же, что и -Wignore.

Полная форма аргумента:

action:message:category:module:lineno

Пустые поля соответствуют любым значениям; завершающие пустые поля можно опустить. Например, -W ignore::DeprecationWarning игнорирует все предупреждения DeprecationWarning.

Поле action имеет описанное выше значение, но применяется только к предупреждениям, соответствующим остальным полям.

Поле message должно соответствовать всему тексту предупреждения; при сопоставлении регистр не учитывается.

Поле category соответствует категории предупреждения (например, DeprecationWarning). Здесь должно быть указано имя класса; проверяется, является ли фактическая категория предупреждения подклассом заданной категории предупреждения.

Поле module соответствует имени модуля (с полным путём); при сопоставлении учитывается регистр.

Поле lineno соответствует номеру строки; ноль соответствует всем номерам строк и потому эквивалентен отсутствующему номеру строки.

Можно указать несколько параметров -W; если предупреждение соответствует нескольким параметрам, выполняется действие для последнего совпавшего параметра. Недопустимые параметры -W игнорируются (однако при выдаче первого предупреждения печатается сообщение о недопустимых параметрах).

Управлять предупреждениями также можно с помощью переменной среды PYTHONWARNINGS и из программы на Python с помощью модуля warnings. Например, функцию warnings.filterwarnings() можно использовать для применения регулярного выражения к тексту предупреждения.

Подробнее см. разделы Фильтр предупреждений и Описание фильтров предупреждений.

-x

Пропустить первую строку исходного кода, что позволяет использовать не относящиеся к Unix формы #!cmd. Это предназначено только для специального обходного решения для DOS.

-X

Зарезервирован для различных параметров, зависящих от реализации. В настоящее время CPython поддерживает следующие значения:

• -X faulthandler для включения faulthandler. См. также PYTHONFAULTHANDLER.

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

• -X showrefcount для вывода общего числа ссылок и количества используемых блоков памяти при завершении программы или после каждой инструкции в интерактивном интерпретаторе. Работает только в отладочных сборках.

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

• -X tracemalloc для отслеживания выделения памяти Python с помощью модуля tracemalloc. По умолчанию в трассировке сохраняется только самый последний кадр. Используйте -X tracemalloc=NFRAME, чтобы начать трассировку с ограничением трассировки стека в NFRAME кадров. Подробнее см. tracemalloc.start() и PYTHONTRACEMALLOC.

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

• -X int_max_str_digits настраивает ограничение длины преобразования целых чисел в строки. См. также PYTHONINTMAXSTRDIGITS.

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

• -X importtime для отображения времени выполнения каждого импорта. Выводятся имя модуля, суммарное время (включая вложенные импорты) и собственное время (без учёта вложенных импортов). Обратите внимание, что в многопоточном приложении вывод может быть некорректным. Типичное использование: python3 -X importtime -c 'import asyncio'. См. также PYTHONPROFILEIMPORTTIME.

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

• -X dev: включить режим разработки Python, добавляющий дополнительные проверки во время выполнения, слишком затратные для включения по умолчанию. См. также PYTHONDEVMODE.

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

• -X utf8 включает режим UTF-8 Python. -X utf8=0 явно отключает режим UTF-8 Python (даже если в противном случае он включился бы автоматически). См. также PYTHONUTF8.

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

• -X pycache_prefix=PATH включает запись файлов .pyc в параллельное дерево каталогов с корнем в указанном каталоге вместо дерева исходного кода. См. также PYTHONPYCACHEPREFIX.

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

• -X warn_default_encoding выдаёт предупреждение EncodingWarning, если для открытия файлов используется кодировка по умолчанию, зависящая от локали. См. также PYTHONWARNDEFAULTENCODING.

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

• -X no_debug_ranges отключает включение таблиц, сопоставляющих дополнительную информацию о местоположении (конечную строку, смещение начального столбца и смещение конечного столбца) каждой инструкции в объектах кода. Это полезно, если нужны более компактные объекты кода и файлы pyc, а также позволяет скрыть дополнительные визуальные индикаторы местоположения при отображении трассировок стека интерпретатором. См. также PYTHONNODEBUGRANGES.

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

• -X frozen_modules определяет, будут ли замороженные модули игнорироваться механизмом импорта. Значение «on» означает, что они импортируются, а «off» — что они игнорируются. По умолчанию используется «on», если это установленная версия Python (обычный случай). Если Python находится в разработке (запущен из дерева исходного кода), по умолчанию используется «off». Обратите внимание, что замороженные модули «importlib_bootstrap» и «importlib_bootstrap_external» используются всегда, даже если этому флагу присвоено значение «off».

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

• -X perf включает поддержку профилировщика Linux perf. Если указан этот параметр, профилировщик perf сможет сообщать о вызовах Python. Этот параметр доступен только на некоторых платформах и ничего не делает, если текущая система его не поддерживает. По умолчанию используется значение «off». См. также PYTHONPERFSUPPORT и Поддержка профилировщика Linux perf в Python.

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

Также позволяет передавать произвольные значения и получать их через словарь sys._xoptions.

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

Изменено в версии 3.9: Параметр -X showalloccount удалён.

Изменено в версии 3.10: Параметр -X oldparser удалён.

1.1.4. Параметры, которые не следует использовать

-J

Зарезервирован для использования в Jython.

1.2.1. Переменные режима отладки

PYTHONDUMPREFS

Если задана, Python выведет объекты и счётчики ссылок, которые остаются активными после завершения работы интерпретатора.

Python должен быть собран с параметром сборки --with-trace-refs.

PYTHONDUMPREFSFILE=FILENAME

Если задана, Python выведет объекты и счётчики ссылок, которые остаются активными после завершения работы интерпретатора, в файл с именем FILENAME.

Python должен быть собран с параметром сборки --with-trace-refs.

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