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

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

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

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

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

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

-c <command>

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

Если указан этот параметр, первым элементом 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, содержащийся в script, который должен быть путём в файловой системе (абсолютным или относительным) к файлу 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.

-E

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

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

-i

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

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

-I

Запустить Python в изолированном режиме. Это также подразумевает параметры -E, -P и -s.

В изолированном режиме sys.path не содержит ни каталог скрипта, ни каталог пользовательских site-packages. Все переменные окружения 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 — Каталог site-packages для каждого пользователя

-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
-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

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

-X

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

• -X faulthandler для включения faulthandler. См. также PYTHONFAULTHANDLER.
• -X showrefcount для вывода общего количества ссылок и числа используемых блоков памяти при завершении программы или после каждого выражения в интерактивном интерпретаторе. Работает только в отладочных сборках.
• -X tracemalloc для начала трассировки выделения памяти Python с помощью модуля tracemalloc. По умолчанию в трассировке сохраняется только самый последний кадр. Используйте -X tracemalloc=NFRAME, чтобы начать трассировку с ограничением трассировки стека в NFRAME кадров. Дополнительные сведения см. в tracemalloc.start() и PYTHONTRACEMALLOC.
• -X int_max_str_digits настраивает ограничение длины преобразования целого числа в строку. См. также PYTHONINTMAXSTRDIGITS.
• -X importtime для отображения длительности каждого импорта. Выводятся имя модуля, суммарное время (включая вложенные импорты) и собственное время (без вложенных импортов). Обратите внимание, что в многопоточном приложении вывод может быть некорректным. Типичное использование: python3 -X importtime -c 'import asyncio'. См. также PYTHONPROFILEIMPORTTIME.
• -X dev: включить режим разработки Python, добавляющий дополнительные проверки во время выполнения, которые слишком затратны, чтобы включать их по умолчанию. См. также PYTHONDEVMODE.
• -X utf8 включает режим UTF-8 Python. -X utf8=0 явно отключает режим UTF-8 Python (даже если в противном случае он включился бы автоматически). См. также PYTHONUTF8.
• -X pycache_prefix=PATH включает запись файлов .pyc в параллельную иерархию каталогов, корнем которой является указанный каталог, вместо дерева кода. См. также PYTHONPYCACHEPREFIX.
• -X warn_default_encoding выдаёт предупреждение EncodingWarning, если для открытия файлов используется кодировка по умолчанию, зависящая от локали. См. также PYTHONWARNDEFAULTENCODING.
• -X no_debug_ranges отключает добавление таблиц, сопоставляющих дополнительные сведения о местоположении (конечную строку, смещение начального столбца и смещение конечного столбца) каждой инструкции в объектах кода. Это полезно, если нужны более компактные объекты кода и файлы pyc, а также позволяет скрыть дополнительные визуальные индикаторы местоположения при отображении трассировок стека интерпретатором. См. также PYTHONNODEBUGRANGES.
• -X frozen_modules определяет, игнорируются ли замороженные модули механизмом импорта. Значение «on» означает, что они импортируются, а «off» — что игнорируются. По умолчанию используется значение «on», если Python установлен (обычный случай). Если Python находится в разработке (запущен из дерева исходного кода), по умолчанию используется значение «off». Обратите внимание, что замороженные модули «importlib_bootstrap» и «importlib_bootstrap_external» используются всегда, даже если этому флагу присвоено значение «off».

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

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

Изменено в версии 3.3: Добавлен параметр -X faulthandler.

Изменено в версии 3.4: Добавлены параметры -X showrefcount и -X tracemalloc.

Изменено в версии 3.6: Добавлен параметр -X showalloccount.

Изменено в версии 3.7: Добавлены параметры -X importtime, -X dev и -X utf8.

Изменено в версии 3.8: Добавлен параметр -X pycache_prefix. Теперь параметр -X dev регистрирует исключения close() в деструкторе io.IOBase.

Изменено в версии 3.9: При использовании параметра -X dev проверяются аргументы encoding и errors при операциях кодирования и декодирования строк.

Параметр -X showalloccount удалён.

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

Изменено в версии 3.11: Добавлены параметры -X no_debug_ranges, -X frozen_modules и -X int_max_str_digits.

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

-J

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

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

PYTHONTHREADDEBUG

Если задана, Python будет выводить отладочную информацию о потоках в stdout.

Требуется отладочная сборка Python.

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

PYTHONDUMPREFS

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

Требуется, чтобы Python был собран с параметром сборки --with-trace-refs.

PYTHONDUMPREFSFILE=FILENAME

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

Требуется, чтобы Python был собран с параметром сборки --with-trace-refs.

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