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

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

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

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

Поле сообщение должно соответствовать всему сообщению о предупреждении; это соответствие не учитывает регистр.

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

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

Поле номер строки соответствует номеру строки, где ноль соответствует всем номерам строк и, следовательно, эквивалентно опущенному номеру строки.

Можно задать несколько параметров -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 (обычный случай). Если он находится в разработке (запускается из дерева исходных кодов), то по умолчанию off. Обратите внимание, что модули importlib_bootstrap и importlib_bootstrap_external всегда используются, даже если этот флаг установлен в off. См. также PYTHON_FROZEN_MODULES.

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

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

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

• -X perf_jit включает поддержку профайлера Linux perf с поддержкой DWARF. При указании этой опции профайлер perf сможет сообщать о вызовах Python, используя информацию DWARF. Эта опция доступна только на некоторых платформах и не будет работать, если она не поддерживается на текущей системе. Значение по умолчанию — «выкл». См. также PYTHON_PERF_JIT_SUPPORT и Поддержка Python для профайлера Linux perf.

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

• -X cpu_count=n переопределяет os.cpu_count(), os.process_cpu_count() и multiprocessing.cpu_count(). n должно быть больше или равно 1. Эта опция может быть полезна пользователям, которым нужно ограничить ресурсы ЦП системы контейнера. См. также PYTHON_CPU_COUNT. Если n равно default, ничего не переопределяется.

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

• -X presite=package.module указывает модуль, который должен быть импортирован до выполнения модуля site и до существования модуля __main__. Поэтому импортированный модуль не является __main__. Это можно использовать для выполнения кода на ранних этапах инициализации Python. Для этой опции требуется, чтобы Python был скомпилирован в отладочном режиме. См. также PYTHON_PRESITE.

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

• -X gil=0,1 соответственно, принудительно отключает или включает GIL. Установка в 0 доступна только в сборках, сконфигурированных с помощью --disable-gil. См. также PYTHON_GIL и Многопотоковый CPython.

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

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

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

Изменено в версии 3.9: Убрана опция -X showalloccount.

Изменено в версии 3.10: Убрана опция -X oldparser.

1.1.4. Управление цветом

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

Установка переменной окружения TERM в значение dumb отключит цвет.

Если переменная окружения FORCE_COLOR установлена, цвет будет включён независимо от значения TERM. Это полезно в системах CI, которые не являются терминалами, но всё ещё могут отображать ANSI escape-последовательности.

Если установлена переменная окружения NO_COLOR, Python отключит весь цвет в выводе. Это имеет приоритет над FORCE_COLOR.

Все эти переменные окружения используются также другими инструментами для управления выводом цвета. Чтобы управлять выводом цвета только в интерпретаторе Python, можно использовать переменную окружения PYTHON_COLORS. Эта переменная имеет приоритет над NO_COLOR, которая, в свою очередь, имеет приоритет над FORCE_COLOR.

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

-J

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

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

PYTHONDUMPREFS

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

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

PYTHONDUMPREFSFILE

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

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

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

PYTHON_PRESITE

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

Это может быть использовано для выполнения кода на ранних этапах инициализации Python.

Для импорта подмодуля используйте package.module в качестве значения, подобно строке импорта.

См. также опцию командной строки -X presite, которая имеет приоритет над этой переменной.

Требуется, чтобы Python был сконфигурирован с опцией компиляции --with-pydebug.

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