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

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

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

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

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

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

python [-bBdEhiIOqsSuvVWx?] [-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). Имя модуля должно быть допустимым абсолютным именем модуля Python, но реализация может не всегда это проверять (например, может позволить использовать имя, содержащее дефис).

Имена пакетов (включая пакеты пространств имён) также допускаются. Если вместо обычного модуля указано имя пакета, интерпретатор выполнит <pkg>.__main__ в качестве главного модуля. Это поведение намеренно аналогично обработке каталогов и zip-файлов, которые передаются интерпретатору в качестве аргумента скрипта.

Примечание

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

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

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

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

См. также

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

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

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

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

-

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

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

<script>

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

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

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

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

См. также

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

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

См. также

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

Изменено в версии 3.4: Автоматическое включение автодополнения по табуляции и редактирования истории.

1.1.2. Общие параметры¶Generic options

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

-V¶

--version¶

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

Python 3.0

1.1.3. Прочие параметры¶Miscellaneous options

-b¶: Выдаёт предупреждение при сравнении bytes или bytearray с str или bytes с int. Выдаёт ошибку, если параметр указан дважды (-bb).

Изменено в версии 3.5: Влияет на сравнения bytes с int.

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

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

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

-i¶

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

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

-I¶: Запускает Python в изолированном режиме. Это также подразумевает -E и -s. В изолированном режиме sys.path не содержит ни каталога скрипта, ни каталога site-packages пользователя. Все переменные окружения PYTHON* также игнорируются. Могут быть наложены дополнительные ограничения, чтобы предотвратить внедрение пользователем вредоносного кода.

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

-O¶: Включить базовые оптимизации. См. также PYTHONOPTIMIZE.

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

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

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

-R¶

Сохранено для совместимости. Начиная с Python 3.3, рандомизация хешей включена по умолчанию.

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

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

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

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

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

См. также

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

-S¶: Отключает импорт модуля site и связанные с ним site-зависимые манипуляции с sys.path. Также отключает эти манипуляции, если site явно импортирован позже (для их выполнения следует вызвать site.main()).

-u¶

Принудительно сделать двоичный слой потоков stdout и stderr (доступный\nкак их атрибут buffer) небуферизованным. Текстовый слой ввода-вывода\nпо-прежнему будет буферизован построчно при выводе в консоль или\nпоблочно при перенаправлении в неинтерактивный файл.

См. также PYTHONUNBUFFERED.

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

-W arg¶

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

file:line: category: message

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

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

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

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

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.

Примечание

Номера строк в сообщениях об ошибках будут смещены на единицу.

-X¶

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

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

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

Изменено в версии 3.2: Теперь допускается передача -X в CPython.

Новое в версии 3.3: Параметр -X faulthandler.

Новое в версии 3.4: Параметры -X showrefcount и -X tracemalloc.

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

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

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

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

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 и хук sys.__interactivehook__.

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

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

PYTHONINSPECT¶

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

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

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

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

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

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

PYTHONHASHSEED¶

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

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

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

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

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

PYTHONIOENCODING¶

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

Для stderr часть :errorhandler игнорируется; обработчик всегда будет 'backslashreplace'.

Изменено в версии 3.4: Часть encodingname теперь необязательна.

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

См. также

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

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

См. также

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

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

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

PYTHONFAULTHANDLER¶: Если эта переменная окружения установлена в непустую строку, faulthandler.enable() вызывается при запуске: устанавливается обработчик сигналов SIGSEGV, SIGFPE, SIGABRT, SIGBUS и SIGILL для дампа обратной трассировки Python. Это эквивалентно параметру -X faulthandler.

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

PYTHONTRACEMALLOC¶: Если эта переменная окружения установлена в непустую строку, начинается трассировка выделений памяти Python с помощью модуля tracemalloc. Значение переменной – максимальное количество кадров, сохраняемых в обратной трассировке. Например, PYTHONTRACEMALLOC=1 сохраняет только самый последний кадр. Дополнительную информацию см. в tracemalloc.start().

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

PYTHONASYNCIODEBUG¶: Если эта переменная окружения установлена в непустую строку, включает режим отладки модуля asyncio.

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

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

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

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

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

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