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

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

Вывести краткое описание всех параметров командной строки.

-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, которые могут быть установлены.

-i

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

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

-I

Запускает Python в изолированном режиме. Это также подразумевает -E и -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.

-q

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

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

-R

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

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

Случайная генерация хэшей предназначена для защиты от отказа в обслуживании, вызванного тщательно выбранными входными данными, которые эксплуатируют худшее время работы конструкции dict, сложность O(n²). Подробности см. в http://www.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;
• -X showrefcount для вывода общего счётчика ссылок и количества используемых блоков памяти при завершении программы или после каждой инструкции в интерактивном интерпретаторе. Это работает только в отладочных сборках.
• -X tracemalloc для начала отслеживания выделения памяти Python с использованием модуля tracemalloc. По умолчанию в трассировке отладки хранится только последний кадр. Используйте -X tracemalloc=NFRAME для начала отслеживания с ограничением трассировки в NFRAME кадрах. Для получения дополнительной информации см. tracemalloc.start().
• -X int_max_str_digits настраивает ограничение длины преобразования целых чисел в строки. Также см. PYTHONINTMAXSTRDIGITS.
• -X importtime для отображения времени выполнения каждого импорта. Отображаются имя модуля, общее время (включая вложенные импорты) и собственное время (исключая вложенные импорты). Обратите внимание, что его вывод может быть некорректным в многопоточной программе. Типичное использование python3 -X importtime -c 'import asyncio'. Также см. PYTHONPROFILEIMPORTTIME.
• -X dev: включить режим разработки Python, вводя дополнительные проверки во время выполнения, которые слишком дороги для включения по умолчанию.
• -X utf8 включает режим Python UTF-8. -X utf8=0 явно отключает режим Python UTF-8 (даже если он бы иначе активировался автоматически).
• -X pycache_prefix=PATH разрешает запись файлов .pyc в параллельную структуру, укоренённую в указанном каталоге, вместо кодовой структуры. Также см. PYTHONPYCACHEPREFIX.
• -X warn_default_encoding выводит EncodingWarning при использовании локализованного кодирования по умолчанию для открытия файлов. Также см. PYTHONWARNDEFAULTENCODING.

Также позволяет передавать произвольные значения и получать их через словарь 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.

Добавлена в версии 3.10.7: Опция -X int_max_str_digits.

Устарело начиная с версии 3.9, удалено в версии 3.10: Опция -X oldparser.

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

-J

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

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

PYTHONTHREADDEBUG

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

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

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

PYTHONDUMPREFS

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

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