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

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

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

Вызывает auditing event 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__. Дополните имя файла для скомпилированных (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.

-q¶

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

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

-R¶

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

В предыдущих версиях Python эта опция включает рандомизацию хэша, так что значения __hash__() объектов 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 – Каталог пакетов сайта для каждого пользователя

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

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

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

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

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

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

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

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

Более подробную информацию смотрите в Фильтр предупреждений и Описание предупреждающих фильтров.

-x¶

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

-X¶

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

• -X faulthandler, чтобы включить faulthandler;

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

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

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

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

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

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

Deprecated since version 3.9, removed in version 3.10: Опция -X oldparser.

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

-J¶

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

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

PYTHONTHREADDEBUG¶

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

Необходимо debug build of Python.

Deprecated since version 3.10, will be removed in version 3.12.

PYTHONDUMPREFS¶

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

Необходимо, чтобы Python был настроен с опцией сборки --with-trace-refs.