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

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

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

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

  Добавлена в версии 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.