Содержание страницы

1. Командная строка и окружение¶Command line and environment

Интерпретатор CPython сканирует командную строку и окружение на предмет различных настроек.

Особенности реализации CPython: схемы командной строки других реализаций могут отличаться. Для получения дополнительных сведений см. Альтернативные реализации.

1.1. Командная строка¶Command line

При запуске Python можно указать любые из этих опций:

python [-bBdEiOQsRStuUvVWxX3?] [-c command | -m module-name | script | - ] [args]

Наиболее распространённый вариант использования – это простой запуск скрипта:

python myscript.py

1.1.1. Опции интерфейса¶Interface options

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

При вызове с подключённым к tty-устройству стандартным вводом интерпретатор выводит приглашение для команд и выполняет их, пока не будет прочитан EOF (символ конца файла; в UNIX его можно ввести с помощью Ctrl-D, а в Windows – с помощью Ctrl-Z, Enter).
При вызове с именем файла в качестве аргумента или с файлом в качестве стандартного ввода он читает и выполняет скрипт из этого файла.
При вызове с именем каталога в качестве аргумента он читает и выполняет соответствующий скрипт из этого каталога.
При вызове с -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 (что позволяет импортировать модули из этого каталога как модули верхнего уровня).

-m <module-name>¶

Ищет sys.path указанный модуль и выполняет его содержимое как модуль __main__.

Поскольку аргумент – это имя модуля, расширение файла указывать не следует (.py). module-name должно быть допустимым именем модуля Python, но реализация может не всегда это проверять (например, может разрешить использовать имя, содержащее дефис).

Имена пакетов также допускаются. Когда вместо обычного модуля указывается имя пакета, интерпретатор выполнит <pkg>.__main__ как главный модуль. Такое поведение намеренно аналогично обработке каталогов и zip-файлов, передаваемых интерпретатору в качестве аргумента скрипта.

Примечание

Эту опцию нельзя использовать со встроенными модулями и модулями расширения, написанными на C, поскольку у них нет файлов модулей Python. Однако её можно использовать для предварительно скомпилированных модулей, даже если исходный файл недоступен.

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

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

python -mtimeit -s 'setup here' 'benchmarked code here'
python -mtimeit -h # подробнее

См. также

runpy.run_module(): Эквивалентная функциональность, доступная напрямую из кода Python

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

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

Изменено в версии 2.5: Теперь именованный модуль может находиться внутри пакета.

Изменено в версии 2.7: Указывайте имя пакета для запуска подмодуля __main__. sys.argv[0] теперь устанавливается в "-m" при поиске модуля (ранее он некорректно устанавливался в "-c").

-

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

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

См. также

runpy.run_path(): Эквивалентная функциональность, доступная напрямую из кода Python

<script>

Выполняет код Python, содержащийся в скрипте, который должен быть файловым путем (абсолютным или относительным), указывающим на файл Python, каталог с файлом __main__.py или ZIP-файл, содержащий файл __main__.py.

Если указана эта опция, первым элементом sys.argv будет имя скрипта, заданное в командной строке.

Если имя скрипта указывает непосредственно на файл Python, каталог, содержащий этот файл, добавляется в начало sys.path, а сам файл выполняется как модуль __main__.

Если имя скрипта ссылается на каталог или ZIP-файл, имя скрипта добавляется в начало sys.path, а файл __main__.py в этом расположении выполняется как модуль __main__.

Изменено в версии 2.5: Каталоги и zip-файлы, содержащие файл __main__.py на верхнем уровне, теперь считаются допустимыми скриптами Python.

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

См. также

Запуск интерпретатора

1.1.2. Общие опции¶Generic options

-?¶
-h¶
--help¶: Выводит краткое описание всех параметров командной строки.

Изменено в версии 2.5: Вариант --help.

-V¶

--version¶

Выводит номер версии Python и завершает работу. Пример вывода:

Python 2.5.1

Изменено в версии 2.5: Вариант --version.

1.1.3. Прочие опции¶Miscellaneous options

-b¶

Выдавать предупреждение при сравнении unicode с bytearray. Выдавать ошибку, если параметр указан дважды (-bb).

Обратите внимание: в отличие от соответствующего флага Python 3.x, этот параметр не будет выдавать предупреждения для сравнений между str и unicode. Вместо этого экземпляр str будет неявно декодирован в unicode и будет использовано сравнение Unicode.

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

-B¶: Если указано, Python не будет пытаться записывать файлы .pyc или .pyo при импорте исходных модулей. См. также PYTHONDONTWRITEBYTECODE.

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

-d¶: Включить отладочный вывод парсера (только для волшебников, в зависимости от опций компиляции).\nСм. также PYTHONDEBUG.

-E¶: Игнорировать все переменные окружения PYTHON*, например PYTHONPATH и PYTHONHOME, которые могут быть установлены.

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

-i¶

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

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

-O¶: Включить базовые оптимизации. Это изменяет расширение имени файла для скомпилированных (байт-код) файлов с .pyc на .pyo. См. также PYTHONOPTIMIZE.

-OO¶: Отбрасывать строки документации в дополнение к оптимизациям -O.

-Q <arg>¶

Управление делением. Аргумент должен быть одним из следующих:

old: деление int/int и long/long возвращает int или long (по умолчанию)
new: новая семантика деления, т.е. деление int/int и long/long возвращает float
warn: старая семантика деления с предупреждением для int/int и long/long
warnall: старая семантика деления с предупреждением для всех случаев использования оператора деления

См. также

Tools/scripts/fixdiv.py: за использование warnall

PEP 238 – Изменение оператора деления

-R¶

Включить рандомизацию хешей, чтобы значения __hash__() объектов str, bytes и datetime «солились» непредсказуемым случайным значением. Хотя они остаются постоянными в рамках одного процесса Python, они непредсказуемы между последовательными запусками Python.

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

Изменение хэш-значений влияет на порядок, в котором ключи извлекаются из словаря. Хотя Python никогда не давал гарантий относительно этого порядка (и он обычно различается между 32-битными и 64-битными сборками), достаточно много реального кода неявно полагается на это негарантированное поведение, поэтому рандомизация отключена по умолчанию.

См. также PYTHONHASHSEED.

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

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

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

См. также

PEP 370 – Каталог site-packages для каждого пользователя

-S¶: Отключить импорт модуля site и зависящие от сайта манипуляции с sys.path, которые он за собой влечёт.

-t¶: Выдавать предупреждение, когда в исходном файле для отступов смешиваются табуляция и пробелы таким образом, что это зависит от ширины табуляции в пробелах. Выдавать ошибку, если параметр указан дважды (-tt).

-u¶

Принудительно делает stdin, stdout и stderr полностью небуферизованными. В системах, где это имеет значение, также переводит stdin, stdout и stderr в двоичный режим.

Обратите внимание: внутренняя буферизация в file.readlines() и объектах файлов (for line in sys.stdin) не зависит от этого параметра. Чтобы обойти это, используйте file.readline() внутри цикла while 1:.

См. также PYTHONUNBUFFERED.

-v¶: Выводит сообщение при каждой инициализации модуля, показывая место (имя файла или встроенный модуль), из которого он загружается. При указании дважды (-vv) выводит сообщение для каждого файла, проверяемого при поиске модуля. Также предоставляет информацию об очистке модуля при завершении. См. также PYTHONVERBOSE.

-W arg¶

Управление предупреждениями. Механизм предупреждений Python по умолчанию выводит предупреждения в sys.stderr. Типичное предупреждение имеет следующий вид:

file:line: category: message

По умолчанию каждое предупреждение выводится один раз для каждой строки исходного кода, в которой оно возникает. Этот параметр управляет частотой вывода предупреждений.

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

Начиная с Python 2.7, DeprecationWarning и его производные игнорируются по умолчанию. Параметр -Wd можно использовать для их повторного включения.

Предупреждениями также можно управлять из программы Python с помощью\nмодуля warnings.

Простейшая форма аргумента – одна из следующих строк действия (или их однозначное сокращение) сама по себе:

ignore: Игнорировать все предупреждения.
default: Явно запросить поведение по умолчанию (вывод каждого предупреждения один раз на\nстроку исходного кода).
all: Выводить предупреждение при каждом его появлении (это может породить много сообщений, если\nпредупреждение вызывается многократно для одной и той же строки, например, внутри\nцикла).
module: Выводить каждое предупреждение только при первом появлении в каждом модуле.
once: Выводить каждое предупреждение только при первом появлении в программе.
error: Возбуждать исключение вместо вывода предупреждения.

Полная форма аргумента:

action:message:category:module:line

Здесь action (действие) как описано выше, но применяется только к сообщениям, соответствующим\nостальным полям. Пустые поля соответствуют любым значениям; конечные пустые поля можно\nопускать. Поле message соответствует началу выводимого сообщения\nпредупреждения; сравнение нечувствительно к регистру. Поле category соответствует\nкатегории предупреждения. Это должно быть имя класса; при сравнении проверяется,\nявляется ли фактическая категория предупреждения сообщения подклассом указанной\nкатегории. Необходимо указывать полное имя класса. Поле module соответствует\n(полному) имени модуля; сравнение чувствительно к регистру. Поле line\nсоответствует номеру строки; ноль соответствует всем номерам строк и, таким образом,\nэквивалентен отсутствующему номеру строки.

См. также

warnings – модуль warnings

PEP 230 – инфраструктура предупреждений

PYTHONWARNINGS

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

-3¶

Предупреждать о возможных несовместимостях с Python 3.x, выдавая DeprecationWarning для возможностей, которые удалены или существенно изменены в Python 3 и не могут быть обнаружены с помощью статического анализа кода.

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

См. Перенос кода Python 2 на Python 3 для получения более подробной информации.

1.1.4. Параметры, которые не стоит использовать¶Options you shouldn’t use

-J¶: Зарезервировано для Jython.

-U¶

Преобразует все строковые литералы в Unicode глобально. Не поддавайтесь искушению использовать этот параметр – он, скорее всего, сломает ваш мир. Он также создаёт файлы .pyc с другим магическим числом, чем обычно. Вместо этого вы можете включить литералы Unicode на уровне модуля, используя:

from __future__ import unicode_literals

в начале файла. Подробнее см. __future__.

-X¶: Зарезервировано для использования альтернативными реализациями Python в собственных целях.

1.2. Переменные окружения¶Environment variables

Эти переменные окружения влияют на поведение Python; они обрабатываются до запуска с флагами командной строки, кроме -E. Обычно флаги командной строки переопределяют переменные окружения в случае конфликта.

PYTHONHOME¶

Изменяет расположение стандартных библиотек Python. По умолчанию библиотеки ищутся в prefix/lib/pythonversion и exec_prefix/lib/pythonversion, где prefix и exec_prefix – это каталоги, зависящие от установки; оба по умолчанию имеют значение /usr/local.

Когда PYTHONHOME установлен в один каталог, его значение заменяет оба prefix и exec_prefix. Чтобы указать для них разные значения, установите PYTHONHOME в prefix:exec_prefix.

PYTHONPATH¶

Дополняет путь поиска модулей по умолчанию. Формат такой же, как у PATH оболочки: один или несколько путей к каталогам, разделённых os.pathsep (например, двоеточиями в Unix или точкой с запятой в Windows). Несуществующие каталоги игнорируются без предупреждения.

В дополнение к обычным каталогам, отдельные записи PYTHONPATH могут ссылаться на zip-файлы, содержащие чистые модули Python (в исходной или скомпилированной форме). Модули расширений не могут быть импортированы из zip-файлов.

Путь поиска по умолчанию зависит от установки, но обычно начинается с prefix/lib/pythonversion (см. PYTHONHOME выше). Он всегда добавляется к PYTHONPATH.

Дополнительный каталог будет вставлен в путь поиска перед PYTHONPATH, как описано выше в разделе Параметры интерфейса. Путь поиска можно изменять из программы Python как переменную sys.path.

PYTHONSTARTUP¶: Если это имя читаемого файла, команды Python из этого файла выполняются до отображения первого приглашения в интерактивном режиме. Файл выполняется в том же пространстве имён, что и интерактивные команды, поэтому объекты, определённые или импортированные в нём, можно использовать без дополнительных уточнений в интерактивном сеансе. Также в этом файле можно изменить приглашения sys.ps1 и sys.ps2.

PYTHONY2K¶: Если присвоить этой переменной непустую строку, модуль time будет требовать, чтобы даты, задаваемые в виде строк, содержали четырёхзначные годы; в противном случае двузначные годы преобразуются по правилам, описанным в документации модуля time.

PYTHONOPTIMIZE¶: Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -O. Если установлено целое число, это эквивалентно указанию -O несколько раз.

PYTHONDEBUG¶: Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -d. Если установлено целое число, это эквивалентно указанию -d несколько раз.

PYTHONINSPECT¶

Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -i.

Эта переменная также может быть изменена кодом Python с помощью os.environ, чтобы принудительно включить режим инспектирования при завершении программы.

PYTHONUNBUFFERED¶: Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -u.

PYTHONVERBOSE¶: Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -v. Если установлено целое число, это эквивалентно указанию -v несколько раз.

PYTHONCASEOK¶: Если эта переменная установлена, Python игнорирует регистр в операторах import. Это работает только на Windows, OS X, OS/2 и RiscOS.

PYTHONDONTWRITEBYTECODE¶: Если эта переменная установлена, Python не будет записывать файлы .pyc или .pyo при импорте исходных модулей. Это эквивалентно указанию опции -B.

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

PYTHONHASHSEED¶

Если эта переменная установлена в random, эффект аналогичен указанию опции -R: для инициализации хешей объектов str, bytes и datetime используется случайное значение.

Если PYTHONHASHSEED установлена в целое число, оно используется как фиксированное начальное значение для генерации hash() типов, на которые распространяется рандомизация хешей.

Его цель – обеспечить воспроизводимое хеширование, например, для самотестирования самого интерпретатора, или чтобы позволить кластеру процессов Python обмениваться значениями хешей.

Целое число должно быть десятичным числом в диапазоне [0, 4294967295]. Указание значения 0 приведёт к тем же значениям хеша, что и при отключённой рандомизации хешей.

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

PYTHONIOENCODING¶: Переопределяет кодировку, используемую для stdin/stdout/stderr, в синтаксисе encodingname:errorhandler. Часть :errorhandler необязательна и имеет то же значение, что и в str.encode().

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

PYTHONNOUSERSITE¶: Если эта переменная установлена, Python не будет добавлять user site-packages directory в sys.path.

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

См. также

PEP 370 – Каталог site-packages для каждого пользователя

PYTHONUSERBASE¶: Определяет user base directory, который используется для вычисления пути к user site-packages directory и путям установки Distutils для python setup.py install --user.

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

См. также

PEP 370 – Каталог site-packages для каждого пользователя

PYTHONEXECUTABLE¶: Если эта переменная окружения установлена, sys.argv[0] будет установлено в её значение вместо значения, полученного через C runtime. Работает только в Mac OS X.

PYTHONWARNINGS¶: Это эквивалентно опции -W. Если присвоена строка, разделённая\nзапятыми, это эквивалентно указанию -W несколько\nраз.

PYTHONHTTPSVERIFY¶

Если эта переменная окружения установлена именно в 0, то это эквивалентно неявному вызову ssl._https_verify_certificates() с enable=False при первом импорте ssl.

Подробнее см. документацию ssl._https_verify_certificates().

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

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

Установка этих переменных работает только в отладочной сборке Python, то есть если Python был сконфигурирован с параметром сборки --with-pydebug.

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

Изменено в версии 2.6: Ранее эта переменная называлась THREADDEBUG.

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

PYTHONMALLOCSTATS¶: Если установлено, Python будет выводить статистику распределения памяти каждый раз при создании новой арены объектов, а также при завершении работы.

PYTHONSHOWALLOCCOUNT¶: Если эта переменная установлена и Python был скомпилирован с определённым COUNT_ALLOCS, то Python выведет счётчики выделений в stderr при завершении работы.

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

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

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