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

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

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

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

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

Новое в версии 3.2.3.

-s

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

См. также

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.

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

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

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

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

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

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

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

См. Фильтр предупреждений и Описание фильтров предупреждений для получения более подробной информации.

-x

Пропустить первую строку исходного кода, что позволяет использовать не-Unix-формы #!cmd. Это предназначено только для специфичного для 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, добавляя дополнительные проверки во время выполнения, которые слишком дорого обходятся для включения по умолчанию.
• -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 (обычный случай). Если он находится в стадии разработки (запущен из дерева исходных текстов), то значение по умолчанию «off». Обратите внимание, что замороженные модули «importlib_bootstrap» и «importlib_bootstrap_external» всегда используются, даже если этот флаг установлен в «off».

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

Изменено в версии 3.2: Опция -X была добавлена.

Введено в версии 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.

Введено в версии 3.11: Опция -X frozen_modules.

Введено в версии 3.11: Опция -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.