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

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

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

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

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

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

python [-bBdEhiOqsSuvVWx?] [-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 будет полный путь к файлу модуля (пока файл модуля находится, первым элементом будет "-m"). Как и в случае с опцией -c, текущий каталог будет добавлен в начало sys.path.

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

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

См. также

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

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

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

-

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

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

<script>

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

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

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

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

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

См. также

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

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

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

-V¶

--version¶

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

Python 3.0

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

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

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

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

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

-i¶

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

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

-O¶: Включает базовые оптимизации. Это изменяет расширение файлов для скомпилированных (байткод) файлов с .pyc на .pyo. См. также 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 каталог в sys.path.

См. также

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

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

-u¶

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

См. также PYTHONUNBUFFERED.

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

-W arg¶

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

file:line: category: message

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

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

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

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

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

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

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

Примечание

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

-X¶: Зарезервировано для различных опций, специфичных для реализации. CPython в настоящее время определяет только одну: вы можете использовать -X faulthandler для включения faulthandler. Также позволяет передавать произвольные значения и получать их через словарь sys._xoptions.

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

Новое в версии 3.3: Опция -X faulthandler.

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

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

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 будет требовать, чтобы даты, указанные в виде строк, содержали 4-значные годы; в противном случае 2-значные годы преобразуются по правилам, описанным в документации модуля time.

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 или .pyo при импорте исходных модулей. Это эквивалентно указанию опции -B.

PYTHONHASHSEED¶

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

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

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

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

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

PYTHONIOENCODING¶

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

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

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

См. также

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

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

См. также

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

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

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

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

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

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

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

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

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

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