1. Командная строка и окружающая среда¶

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

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

• При вызове со стандартного ввода, подключенного к устройству tty, он запрашивает команды и выполняет их до тех пор, пока не будет считан EOF (символ конца файла, который можно ввести с помощью Ctrl-D в UNIX или Ctrl-Z, Enter в Windows).

• При вызове с аргументом filename или с файлом в качестве стандартного ввода он считывает и выполняет скрипт из этого файла.

• При вызове с аргументом имени каталога он считывает и выполняет сценарий с соответствующим именем из этого каталога.

• При вызове с помощью -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 (что позволит импортировать модули из этого каталога как модули верхнего уровня).

Создает auditing event 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 не содержит ни текущего каталога, ни каталога пакетов сайта пользователя. Все PYTHON* переменные среды также игнорируются.

Многие модули стандартной библиотеки содержат код, который вызывается при их выполнении в виде скрипта. Примером может служить модуль timeit:

python -m timeit -s 'setup here' 'benchmarked code here'
python -m timeit -h # for details

Создает auditing event cpython.run_module с аргументом module-name.

См.также

runpy.run_module()

Эквивалентная функциональность, доступная непосредственно коду на Python

PEP 338 – Выполнение модулей в виде скриптов

Изменено в версии 3.1: Укажите имя пакета для запуска подмодуля __main__.

Изменено в версии 3.4: также поддерживаются пакеты пространства имен

-

Считывать команды из стандартного ввода (sys.stdin). Если стандартный ввод является терминальным, то подразумевается -i.

Если задан этот параметр, то первым элементом sys.argv будет "-", а текущий каталог будет добавлен в начало sys.path.

Выдает auditing event 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 не содержит ни каталога скрипта, ни каталога пользовательских пакетов сайта. Все PYTHON* переменные среды также игнорируются.

Создает auditing event cpython.run_file с аргументом filename.

См.также

runpy.run_path()

Эквивалентная функциональность, доступная непосредственно коду на Python

Если параметр интерфейса не указан, то подразумевается -i, sys.argv[0] является пустой строкой (""), и текущий каталог будет добавлен в начало sys.path. Кроме того, автоматически включаются функции заполнения вкладок и редактирования истории, если они доступны на вашей платформе (см. Конфигурация строки чтения).

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 не содержит ни каталога скрипта, ни каталога пакетов сайта пользователя. Все переменные среды PYTHON* также игнорируются. Могут быть введены дополнительные ограничения, чтобы пользователь не мог внедрить вредоносный код.

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

-O¶

Удалите операторы assert и любой код, зависящий от значения __debug__. Увеличьте имя файла для скомпилированных (bytecode) файлов, добавив .opt-1 перед расширением .pyc (см. PEP 488). Смотрите также PYTHONOPTIMIZE.

Изменено в версии 3.5: Измените .pyc имена файлов в соответствии с PEP 488.

-OO¶

Выполните -O, а также удалите строки документации. Увеличьте имя файла для скомпилированных (bytecode) файлов, добавив .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 – Для каждого сайта пользователя-каталог пакетов

-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 игнорирует все предупреждения об устаревании.

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

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

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

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

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

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

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

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

-x¶

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

-X¶

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

• -X faulthandler, чтобы включить faulthandler. Смотрите также PYTHONFAULTHANDLER.

• -X showrefcount для вывода общего количества ссылок и количества используемых блоков памяти при завершении программы или после каждой инструкции в интерактивном интерпретаторе. Это работает только на debug builds.

• -X tracemalloc чтобы начать отслеживание распределения памяти в Python, используйте модуль tracemalloc. По умолчанию в режиме обратной трассировки сохраняется только самый последний кадр. Используйте -X tracemalloc=NFRAME, чтобы начать трассировку с ограничением обратной трассировки в N КАДРОВ frames. Смотрите tracemalloc.start() и PYTHONTRACEMALLOC для получения дополнительной информации.

• -X int_max_str_digits настраивает integer string conversion length limitation. Смотрите также PYTHONINTMAXSTRDIGITS.

• -X importtime, чтобы показать, сколько времени занимает каждый импорт. В нем отображается название модуля, суммарное время (включая вложенный импорт) и время автономной работы (исключая вложенный импорт). Обратите внимание, что в многопоточном приложении его вывод может быть нарушен. Обычно используется python3 -X importtime -c 'import asyncio'. Смотрите также PYTHONPROFILEIMPORTTIME.

• -X dev: включить Python Development Mode, вводя дополнительные проверки во время выполнения, которые слишком дороги, чтобы включать их по умолчанию. Смотрите также PYTHONDEVMODE.

• -X utf8 включает функцию Python UTF-8 Mode. -X utf8=0 явно отключает функцию Python UTF-8 Mode (даже если в противном случае она активировалась бы автоматически). Смотрите также PYTHONUTF8.

• -X pycache_prefix=PATH позволяет записывать .pyc файлы в параллельное дерево с корнем в данном каталоге, а не в дерево кода. Смотрите также PYTHONPYCACHEPREFIX.

• -X warn_default_encoding выдает EncodingWarning, когда для открытия файлов используется кодировка по умолчанию, зависящая от языкового стандарта. Смотрите также PYTHONWARNDEFAULTENCODING.

• -X no_debug_ranges отключает включение таблиц, отображающих дополнительную информацию о местоположении (конечная строка, смещение начального столбца и смещение конечного столбца) для каждой команды в code objects. Это полезно, когда требуются объекты кода меньшего размера и pyc-файлы, а также для подавления дополнительных визуальных индикаторов местоположения, когда интерпретатор отображает трассировку. Смотрите также PYTHONNODEBUGRANGES.

• -X frozen_modules определяет, игнорируются ли замороженные модули механизмом импорта. Значение «on» означает, что они импортируются, а «off» означает, что они игнорируются. Значение по умолчанию «on», если это установленный Python (обычный случай). Если он находится в стадии разработки (запускается из дерева исходных текстов), то значение по умолчанию равно «выкл.». Обратите внимание, что замороженные модули «importlib_bootstrap» и «importlib_bootstrap_external» используются всегда, даже если для этого флага установлено значение «выкл.».

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

Нужен debug build of Python.

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

PYTHONDUMPREFS¶

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

Нужен Python, настроенный с параметром --with-trace-refs build.

PYTHONDUMPREFSFILE=FILENAME¶

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

Нужен Python, настроенный с параметром --with-trace-refs build.

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