`subprocess.md`

663 строк · 62.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/library/subprocess.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 17.1. [`subprocess`](https://python-all.ru/3.2/library/subprocess.html#module-subprocess) – Управление подпроцессами89Модуль [`subprocess`](https://python-all.ru/3.2/library/subprocess.html#module-subprocess) позволяет порождать новые процессы, подключаться к их каналам ввода/вывода/ошибок и получать их коды возврата. Этот модуль призван заменить несколько других, более старых модулей и функций, таких как:1011```python12os.system13os.spawn*14```1516Информация о том, как модуль [`subprocess`](https://python-all.ru/3.2/library/subprocess.html#module-subprocess) может использоваться для замены этих модулей и функций, приведена в следующих разделах.1718> **См. также**19>20> [**PEP 324**](https://python-all.ru/3.2/library/subprocess.html) – PEP, предлагающий модуль подпроцесса2122## 17.1.1. Использование модуля [`subprocess`](https://python-all.ru/3.2/library/subprocess.html#module-subprocess)2324Рекомендуемый способ запуска подпроцессов – использовать следующие удобные функции во всех случаях, где они применимы. Для более сложных случаев можно напрямую использовать низкоуровневый интерфейс [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen).2526#### `subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False)`2728Выполняет команду, описанную аргументом *args*. Ожидает завершения команды, затем возвращает атрибут `returncode`.2930Указанные выше аргументы – лишь самые распространённые; они описаны ниже в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments) (отсюда несколько необычная запись в сокращённой сигнатуре). Полная сигнатура функции совпадает с сигнатурой конструктора [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) – эта функция передаёт все переданные аргументы напрямую этому интерфейсу.3132Примеры:3334```python35>>> subprocess.call(["ls", "-l"])3603738>>> subprocess.call("exit 1", shell=True)39140```4142> **Предупреждение**43>44> Вызов системной оболочки с `shell=True` может быть опасен для безопасности, если используется вместе с недоверенными входными данными. Подробнее см. предупреждение в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments).4546> **Примечание**47>48> Не используйте `stdout=PIPE` или `stderr=PIPE` с этой функцией. Поскольку каналы не читаются текущим процессом, дочерний процесс может заблокироваться, если он генерирует достаточно выходных данных для заполнения буфера канала ОС.4950#### `subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False)`5152Выполняет команду с аргументами. Ожидает завершения команды. Если код возврата равен нулю, возвращает результат, иначе возбуждает [`CalledProcessError`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CalledProcessError). Объект [`CalledProcessError`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CalledProcessError) будет содержать код возврата в атрибуте `returncode`.5354Указанные выше аргументы – лишь самые распространённые; они описаны ниже в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments) (отсюда несколько необычная запись в сокращённой сигнатуре). Полная сигнатура функции совпадает с сигнатурой конструктора [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) – эта функция передаёт все переданные аргументы напрямую этому интерфейсу.5556Примеры:5758```python59>>> subprocess.check_call(["ls", "-l"])6006162>>> subprocess.check_call("exit 1", shell=True)63Traceback (most recent call last):64   ...65subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 166```6768Новое в версии 2.5.6970> **Предупреждение**71>72> Вызов системной оболочки с `shell=True` может быть опасен для безопасности, если используется вместе с недоверенными входными данными. Подробнее см. предупреждение в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments).7374> **Примечание**75>76> Не используйте `stdout=PIPE` или `stderr=PIPE` с этой функцией. Поскольку каналы не читаются текущим процессом, дочерний процесс может заблокироваться, если он генерирует достаточно выходных данных для заполнения буфера канала ОС.7778#### `subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False)`7980Выполняет команду с аргументами и возвращает её вывод в виде байтовой строки.8182Если код возврата не равен нулю, возбуждается исключение [`CalledProcessError`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CalledProcessError). Объект [`CalledProcessError`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CalledProcessError) будет содержать код возврата в атрибуте `returncode`, а любой вывод – в атрибуте `output`.8384Указанные выше аргументы – лишь самые распространённые; они описаны ниже в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments) (отсюда несколько необычная запись в сокращённой сигнатуре). Полная сигнатура функции в основном совпадает с сигнатурой конструктора [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen), за исключением того, что параметр *stdout* не допускается, так как используется внутри. Все остальные переданные аргументы напрямую передаются конструктору [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen).8586Примеры:8788```python89>>> subprocess.check_output(["echo", "Hello World!"])90b'Hello World!\n'9192>>> subprocess.check_output(["echo", "Hello World!"], universal_newlines=True)93'Hello World!\n'9495>>> subprocess.check_output("exit 1", shell=True)96Traceback (most recent call last):97   ...98subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 199```100101По умолчанию эта функция возвращает данные в виде закодированных байтов. Фактическая кодировка выходных данных может зависеть от вызываемой команды, поэтому декодирование в текст часто приходится выполнять на уровне приложения.102103Это поведение можно переопределить, установив *universal\_newlines* в `True`, как описано ниже в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments).104105Чтобы также захватить стандартный поток ошибок в результате, используйте `stderr=subprocess.STDOUT`:106107```python108>>> subprocess.check_output(109...     "ls non_existent_file; exit 0",110...     stderr=subprocess.STDOUT,111...     shell=True)112'ls: non_existent_file: No such file or directory\n'113```114115Новое в версии 2.7.116117> **Предупреждение**118>119> Вызов системной оболочки с `shell=True` может быть опасен для безопасности, если используется вместе с недоверенными входными данными. Подробнее см. предупреждение в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments).120121> **Примечание**122>123> Не используйте `stderr=PIPE` с этой функцией. Поскольку канал не читается текущим процессом, дочерний процесс может заблокироваться, если он генерирует достаточно выходных данных для заполнения буфера канала ОС.124125#### `subprocess.PIPE`126127Специальное значение, которое может использоваться в качестве аргумента *stdin*, *stdout* или *stderr* для [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) и указывает, что должен быть открыт канал к стандартному потоку.128129#### `subprocess.STDOUT`130131Специальное значение, которое может использоваться в качестве аргумента *stderr* для [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) и указывает, что стандартный поток ошибок должен направляться в тот же дескриптор, что и стандартный вывод.132133#### `exception subprocess.CalledProcessError`134135Исключение, возбуждаемое, когда процесс, запущенный с помощью [`check_call()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.check_call) или [`check_output()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.check_output), возвращает ненулевой статус выхода.136137#### `returncode`138139Код возврата дочернего процесса.140141#### `cmd`142143Команда, которая использовалась для запуска дочернего процесса.144145#### `output`146147Вывод дочернего процесса, если это исключение вызвано [`check_output()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.check_output). В противном случае – `None`.148149### 17.1.1.1. Часто используемые аргументы150151Для поддержки широкого круга сценариев использования конструктор [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) (и удобные функции) принимают большое количество необязательных аргументов. В большинстве типичных случаев многие из этих аргументов можно смело оставить со значениями по умолчанию. Наиболее часто требуемые аргументы:152153> *args* обязателен для всех вызовов и должен быть строкой или последовательностью аргументов программы. Передача последовательности аргументов, как правило, предпочтительнее, поскольку позволяет модулю позаботиться о необходимом экранировании и кавычках (например, для пробелов в именах файлов). Если передаётся одна строка, то либо *shell* должен быть [`True`](https://python-all.ru/3.2/library/constants.html#True) (см. ниже), либо строка должна просто задавать имя исполняемой программы без указания аргументов.154>155> Параметры *stdin*, *stdout* и *stderr* задают дескрипторы стандартного ввода, стандартного вывода и стандартного вывода ошибок выполняемой программы. Допустимые значения: [`PIPE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.PIPE), существующий файловый дескриптор (положительное целое число), существующий файловый объект и `None`. Значение [`PIPE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.PIPE) указывает, что следует создать новый канал к дочернему процессу. При настройках по умолчанию (`None`) перенаправление не происходит; дескрипторы файлов дочернего процесса наследуются от родительского. Кроме того, *stderr* может быть установлен в [`STDOUT`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STDOUT), что означает, что данные stderr дочернего процесса должны захватываться в тот же дескриптор, что и stdout.156>157> Если *universal\_newlines* равен `True`, файловые объекты *stdin*, *stdout* и *stderr* будут открыты как текстовые потоки в режиме [*универсальных новых строк*](https://python-all.ru/3.2/glossary.html#term-universal-newlines) с использованием кодировки, возвращаемой [`locale.getpreferredencoding()`](https://python-all.ru/3.2/library/locale.html#locale.getpreferredencoding). Для *stdin* символы конца строки `'\n'` во входных данных будут преобразованы в разделитель строк по умолчанию [`os.linesep`](https://python-all.ru/3.2/library/os.html#os.linesep). Для *stdout* и *stderr* все концы строк в выводе будут преобразованы в `'\n'`. Дополнительную информацию см. в документации класса [`io.TextIOWrapper`](https://python-all.ru/3.2/library/io.html#io.TextIOWrapper), когда аргумент *newline* его конструктора равен `None`.158>159> > **Примечание**160> >161> > Атрибут newlines файловых объектов [`Popen.stdin`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.stdin), [`Popen.stdout`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.stdout) и [`Popen.stderr`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.stderr) не обновляется методом [`Popen.communicate()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.communicate).162>163> Если *shell* равен `True`, указанная команда будет выполняться через оболочку. Это может быть полезно, если Python используется в первую очередь из-за улучшенного управления потоком выполнения по сравнению с большинством системных оболочек, и при этом нужен удобный доступ к другим возможностям оболочки, таким как конвейеры, маски имён файлов, подстановка переменных окружения и подстановка `~` в домашний каталог пользователя. Однако следует отметить, что сам Python предоставляет реализации многих возможностей, похожих на оболочку (в частности, [`glob`](https://python-all.ru/3.2/library/glob.html#module-glob), [`fnmatch`](https://python-all.ru/3.2/library/fnmatch.html#module-fnmatch), [`os.walk()`](https://python-all.ru/3.2/library/os.html#os.walk), [`os.path.expandvars()`](https://python-all.ru/3.2/library/os.path.html#os.path.expandvars), [`os.path.expanduser()`](https://python-all.ru/3.2/library/os.path.html#os.path.expanduser) и [`shutil`](https://python-all.ru/3.2/library/shutil.html#module-shutil)).164>165> > **Предупреждение**166> >167> > Выполнение команд оболочки, содержащих непроверенные входные данные из недоверенного источника, делает программу уязвимой к [внедрению в оболочку](https://python-all.ru/3.2/library/subprocess.html) – серьёзной уязвимости безопасности, которая может привести к выполнению произвольных команд. По этой причине использование `shell=True` **настоятельно не рекомендуется** в случаях, когда командная строка формируется из внешних данных:168> >169> > ```python170> > >>> from subprocess import call171> > >>> filename = input("What file would you like to display?\n")172> > What file would you like to display?173> > non_existent; rm -rf / #174> > >>> call("cat " + filename, shell=True) # Ой-ой. Это плохо кончится...175> > ```176> >177> > `shell=False` отключает все функции на основе оболочки, но не подвержен этой уязвимости; обратитесь к примечанию в документации конструктора [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) за полезными советами по настройке `shell=False`.178179Эти параметры, как и все остальные, более подробно описаны в документации конструктора [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen).180181### 17.1.1.2. Конструктор Popen182183Создание и управление процессами в этом модуле осуществляется классом [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen). Он предоставляет большую гибкость, позволяя разработчикам обрабатывать менее распространённые случаи, не охваченные удобными функциями.184185#### `class subprocess.Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=())`186187Запускает дочернюю программу в новом процессе. На Unix класс использует поведение, подобное [`os.execvp()`](https://python-all.ru/3.2/library/os.html#os.execvp), для выполнения дочерней программы. На Windows класс использует функцию Windows `CreateProcess()`. Аргументы [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) следующие.188189*args* должен быть последовательностью аргументов программы или отдельной строкой. По умолчанию, если *args* является последовательностью, исполняемая программа – это первый элемент в *args*. Если *args* – строка, интерпретация зависит от платформы и описана ниже. Дополнительные отличия от поведения по умолчанию см. в аргументах *shell* и *executable*. Если не указано иное, рекомендуется передавать *args* как последовательность.190191В Unix, если *args* является строкой, она интерпретируется как имя или путь к выполняемой программе. Однако это можно сделать только в том случае, если программе не передаются аргументы.192193> **Примечание**194>195> [`shlex.split()`](https://python-all.ru/3.2/library/shlex.html#shlex.split) может быть полезен при определении правильной токенизации *args*, особенно в сложных случаях:196>197> ```python198> >>> import shlex, subprocess199> >>> command_line = input()200> /bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"201> >>> args = shlex.split(command_line)202> >>> print(args)203> ['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]204> >>> p = subprocess.Popen(args) # Успешно!205> ```206>207> Обратите внимание, что опции (такие как *-input*) и аргументы (такие как *eggs.txt*), разделённые пробелами в оболочке, помещаются в отдельные элементы списка, в то время как аргументы, требующие кавычек или обратной косой черты в оболочке (например, имена файлов, содержащие пробелы, или команда *echo*, показанная выше), являются отдельными элементами списка.208209В Windows, если *args* является последовательностью, она будет преобразована в строку способом, описанным в разделе [*Преобразование последовательности аргументов в строку в Windows*](https://python-all.ru/3.2/library/subprocess.html#converting-argument-sequence). Это связано с тем, что базовая функция `CreateProcess()` работает со строками.210211Аргумент *shell* (по умолчанию *False*) указывает, следует ли использовать оболочку в качестве выполняемой программы. Если *shell* равен *True*, рекомендуется передавать *args* в виде строки, а не последовательности.212213В Unix с `shell=True` оболочкой по умолчанию является `/bin/sh`. Если *args* – строка, она задаёт команду для выполнения через оболочку. Это означает, что строка должна быть отформатирована точно так, как если бы она была введена в приглашении оболочки. Сюда входит, например, экранирование кавычками или обратной косой чертой имён файлов с пробелами. Если *args* – последовательность, первый элемент задаёт командную строку, а все дополнительные элементы будут рассматриваться как дополнительные аргументы для самой оболочки. Иными словами, [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) делает эквивалент следующего:214215```python216Popen(['/bin/sh', '-c', args[0], args[1], ...])217```218219В Windows с `shell=True` переменная окружения `COMSPEC` задаёт оболочку по умолчанию. Единственный случай, когда нужно указывать `shell=True` в Windows – это когда команда, которую требуется выполнить, встроена в оболочку (например, **dir** или **copy**). Для запуска пакетного файла или консольного исполняемого файла `shell=True` не требуется.220221> **Предупреждение**222>223> Передача `shell=True` может быть опасна для безопасности при использовании с недоверенными входными данными. Подробнее см. предупреждение в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments).224225Параметр *bufsize* будет передан в качестве соответствующего аргумента функции [`io.open()`](https://python-all.ru/3.2/library/io.html#io.open) при создании файловых объектов каналов stdin/stdout/stderr: `0` означает отсутствие буферизации (чтение и запись – один системный вызов, могут вернуть меньше данных), `1` означает построчную буферизацию, любое другое положительное значение указывает использовать буфер примерно такого размера. Отрицательное значение bufsize (по умолчанию) означает, что будет использоваться системное значение по умолчанию io.DEFAULT\_BUFFER\_SIZE.226227Изменено в версии 3.2.4.228229Аргумент *executable* задаёт заменяющую программу для выполнения. Он требуется очень редко. Когда `shell=False`, *executable* заменяет программу, указанную в *args*. Однако исходный *args* всё равно передаётся программе. Большинство программ рассматривают программу, указанную в *args*, как имя команды, которое затем может отличаться от фактически выполняемой программы. В Unix имя *args* становится отображаемым именем для исполняемого файла в таких утилитах, как **ps**. Если `shell=True`, в Unix аргумент *executable* задаёт заменяющую оболочку для оболочки по умолчанию `/bin/sh`.230231Параметры *stdin*, *stdout* и *stderr* задают дескрипторы стандартного ввода, стандартного вывода и стандартного вывода ошибок выполняемой программы. Допустимые значения: [`PIPE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.PIPE), существующий файловый дескриптор (положительное целое число), существующий [*файловый объект*](https://python-all.ru/3.2/glossary.html#term-file-object) и `None`. Значение [`PIPE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.PIPE) указывает, что следует создать новый канал к дочернему процессу. При настройках по умолчанию (`None`) перенаправление не происходит; дескрипторы файлов дочернего процесса наследуются от родительского. Кроме того, *stderr* может быть установлен в [`STDOUT`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STDOUT), что означает, что данные stderr от приложения должны захватываться в тот же дескриптор, что и stdout.232233Если *preexec\_fn* установлен в вызываемый объект, этот объект будет вызван в дочернем процессе непосредственно перед выполнением дочернего процесса. (только Unix)234235> **Предупреждение**236>237> Параметр *preexec\_fn* небезопасно использовать при наличии потоков в приложении. Дочерний процесс может зависнуть до вызова exec. Если его всё же нужно использовать, пусть он будет тривиальным! Сведите к минимуму количество вызываемых библиотек.238239> **Примечание**240>241> Если нужно изменить окружение для дочернего процесса, используйте параметр *env* вместо изменения в *preexec\_fn*. Параметр *start\_new\_session* может заменить ранее распространённое использование *preexec\_fn* для вызова os.setsid() в дочернем процессе.242243Если *close\_fds* имеет значение true, все файловые дескрипторы, кроме `0`, `1` и `2`, будут закрыты перед выполнением дочернего процесса. (Только Unix). Значение по умолчанию зависит от платформы: на Unix всегда true. На Windows оно равно true, когда *stdin*/*stdout*/*stderr* равны [`None`](https://python-all.ru/3.2/library/constants.html#None), и false в противном случае. На Windows, если *close\_fds* равно true, то дочерний процесс не наследует ни одного дескриптора. Обратите внимание, что в Windows нельзя одновременно установить *close\_fds* в true и перенаправлять стандартные дескрипторы, задавая *stdin*, *stdout* или *stderr*.244245Изменено в версии 3.2: Значение по умолчанию для *close\_fds* было изменено с [`False`](https://python-all.ru/3.2/library/constants.html#False) на то, что описано выше.246247*pass\_fds* – это необязательная последовательность файловых дескрипторов, которые должны оставаться открытыми между родительским и дочерним процессами. Если задан любой *pass\_fds*, то *close\_fds* принудительно устанавливается в [`True`](https://python-all.ru/3.2/library/constants.html#True). (Только Unix)248249Новое в версии 3.2: Был добавлен параметр *pass\_fds*.250251Если *cwd* не равен `None`, функция меняет рабочий каталог на *cwd* перед выполнением дочернего процесса. В частности, функция ищет *executable* (или первый элемент в *args*) относительно *cwd*, если путь к исполняемому файлу является относительным.252253Если *restore\_signals* равен True (значение по умолчанию), все сигналы, которые Python установил в SIG\_IGN, восстанавливаются в SIG\_DFL в дочернем процессе перед exec. В настоящее время это включает сигналы SIGPIPE, SIGXFZ и SIGXFSZ. (Только Unix)254255Изменено в версии 3.2: Был добавлен параметр *restore\_signals*.256257Если *start\_new\_session* равен True, системный вызов setsid() будет выполнен в дочернем процессе перед запуском подпроцесса. (Только Unix)258259Изменено в версии 3.2: добавлен параметр *start\_new\_session*.260261Если *env* не равен `None`, он должен быть отображением, определяющим переменные окружения для нового процесса; они используются вместо поведения по умолчанию, заключающегося в наследовании окружения текущего процесса.262263> **Примечание**264>265> Если задан, то *env* должен предоставлять все переменные, необходимые для выполнения программы. В Windows, для запуска [side-by-side assembly](https://python-all.ru/3.2/library/subprocess.html), указанный *env* **обязан** включать корректный `SystemRoot`.266267Если *universal\_newlines* равно `True`, то файловые объекты *stdin*, *stdout* и *stderr* открываются как текстовые потоки в режиме универсальных новых строк, как описано выше в разделе [*Часто используемые аргументы*](https://python-all.ru/3.2/library/subprocess.html#frequently-used-arguments).268269Если указан, *startupinfo* будет объектом [`STARTUPINFO`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO), который передаётся базовой функции `CreateProcess`. *creationflags*, если заданы, могут быть [`CREATE_NEW_CONSOLE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CREATE_NEW_CONSOLE) или [`CREATE_NEW_PROCESS_GROUP`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CREATE_NEW_PROCESS_GROUP) (только Windows).270271Объекты Popen поддерживаются в качестве контекстных менеджеров с помощью оператора [`with`](https://python-all.ru/3.2/reference/compound_stmts.html#with): при выходе стандартные файловые дескрипторы закрываются, и выполняется ожидание завершения процесса.272273```python274with Popen(["ifconfig"], stdout=PIPE) as proc:275    log.write(proc.stdout.read())276```277278Изменено в версии 3.2: Добавлена поддержка контекстного менеджера.279280### 17.1.1.3. Исключения281282Исключения, возникшие в дочернем процессе до того, как новая программа начала выполнение, будут повторно возбуждены в родительском процессе. Кроме того, объект исключения будет иметь дополнительный атрибут с именем `child_traceback`, представляющий собой строку, содержащую информацию о трассировке с точки зрения дочернего процесса.283284Наиболее часто возбуждаемым исключением является [`OSError`](https://python-all.ru/3.2/library/exceptions.html#OSError). Оно возникает, например, при попытке выполнить несуществующий файл. Приложения должны быть готовы к исключениям [`OSError`](https://python-all.ru/3.2/library/exceptions.html#OSError).285286Исключение [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError) будет возбуждено, если [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) вызван с недопустимыми аргументами.287288[`check_call()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.check_call) и [`check_output()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.check_output) возбудят [`CalledProcessError`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CalledProcessError), если вызванный процесс вернёт ненулевой код возврата.289290### 17.1.1.4. Безопасность291292В отличие от некоторых других функций popen, данная реализация никогда не вызывает системную оболочку неявно. Это означает, что все символы, включая метасимволы оболочки, можно безопасно передавать дочерним процессам. Очевидно, если оболочка вызывается явно, то приложение отвечает за то, чтобы все пробелы и метасимволы были правильно экранированы.293294## 17.1.2. Объекты Popen295296Экземпляры класса [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) имеют следующие методы:297298#### `Popen.poll()`299300Проверяет, завершён ли дочерний процесс. Устанавливает и возвращает атрибут [`returncode`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.returncode).301302#### `Popen.wait()`303304Ожидает завершения дочернего процесса. Устанавливает и возвращает атрибут [`returncode`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.returncode).305306> **Предупреждение**307>308> Это приведёт к взаимоблокировке при использовании `stdout=PIPE` и/или `stderr=PIPE`, если дочерний процесс генерирует достаточно выходных данных для канала, так что он блокируется в ожидании, пока буфер канала ОС сможет принять больше данных. Используйте [`communicate()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.communicate), чтобы избежать этого.309310#### `Popen.communicate(input=None)`311312Взаимодействует с процессом: отправляет данные в stdin. Читает данные из stdout и stderr до достижения конца файла. Ожидает завершения процесса. Необязательный аргумент *input* должен содержать данные для отправки дочернему процессу, или `None`, если данные отправлять не нужно. Тип *input* должен быть bytes или, если *universal\_newlines* был `True`, строкой.313314[`communicate()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.communicate) возвращает кортеж `(stdoutdata, stderrdata)`.315316Обратите внимание: для отправки данных в stdin процесса объект Popen должен быть создан с `stdin=PIPE`. Аналогично, чтобы получить в результирующем кортеже что-либо, кроме `None`, нужно также указать `stdout=PIPE` и/или `stderr=PIPE`.317318> **Примечание**319>320> Прочитанные данные буферизуются в памяти, поэтому не используйте этот метод, если размер данных велик или неограничен.321322#### `Popen.send_signal(signal)`323324Отправляет сигнал *signal* дочернему процессу.325326> **Примечание**327>328> В Windows SIGTERM – это псевдоним для [`terminate()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.terminate). Сигналы CTRL\_C\_EVENT и CTRL\_BREAK\_EVENT можно отправлять процессам, запущенным с параметром *creationflags*, включающим *CREATE\_NEW\_PROCESS\_GROUP*.329330#### `Popen.terminate()`331332Останавливает дочерний процесс. В ОС POSIX метод отправляет дочернему процессу сигнал SIGTERM. В Windows для остановки дочернего процесса вызывается функция Win32 API `TerminateProcess()`.333334#### `Popen.kill()`335336Завершает дочерний процесс. В ОС POSIX функция отправляет дочернему процессу сигнал SIGKILL. В Windows [`kill()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.kill) – это псевдоним для [`terminate()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.terminate).337338Также доступны следующие атрибуты:339340> **Предупреждение**341>342> Используйте [`communicate()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.communicate) вместо [`.stdin.write`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.stdin), [`.stdout.read`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.stdout) или [`.stderr.read`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.stderr), чтобы избежать взаимоблокировок из-за переполнения любого из буферов других каналов ОС, что блокирует дочерний процесс.343344#### `Popen.stdin`345346Если аргумент *stdin* был равен [`PIPE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.PIPE), то этот атрибут представляет собой [*файловый объект*](https://python-all.ru/3.2/glossary.html#term-file-object), который передаёт входные данные дочернему процессу. В противном случае он равен `None`.347348#### `Popen.stdout`349350Если аргумент *stdout* был равен [`PIPE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.PIPE), то этот атрибут представляет собой [*файловый объект*](https://python-all.ru/3.2/glossary.html#term-file-object), который возвращает выходные данные дочернего процесса. В противном случае он равен `None`.351352#### `Popen.stderr`353354Если аргумент *stderr* был равен [`PIPE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.PIPE), то этот атрибут представляет собой [*файловый объект*](https://python-all.ru/3.2/glossary.html#term-file-object), который возвращает сообщения об ошибках дочернего процесса. В противном случае он равен `None`.355356#### `Popen.pid`357358PID дочернего процесса.359360Обратите внимание: если установить аргумент *shell* в значение `True`, то это будет идентификатор процесса запущенной оболочки.361362#### `Popen.returncode`363364Код возврата дочернего процесса, устанавливаемый методами [`poll()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.poll) и [`wait()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.wait) (а косвенно и [`communicate()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen.communicate)). Значение `None` указывает, что процесс ещё не завершён.365366Отрицательное значение `-N` означает, что дочерний процесс был завершён сигналом `N` (только в Unix).367368## 17.1.3. Вспомогательные средства Popen для Windows369370Класс [`STARTUPINFO`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO) и следующие константы доступны только в Windows.371372#### `class subprocess.STARTUPINFO`373374Частичная поддержка структуры Windows [STARTUPINFO](https://python-all.ru/3.2/library/subprocess.html) используется при создании [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen).375376#### `dwFlags`377378Битовое поле, определяющее, используются ли некоторые атрибуты структуры [`STARTUPINFO`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO) при создании окна процесса.379380```python381si = subprocess.STARTUPINFO()382si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW383```384385#### `hStdInput`386387Если в [`dwFlags`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO.dwFlags) указан флаг [`STARTF_USESTDHANDLES`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTF_USESTDHANDLES), этот атрибут является дескриптором стандартного ввода процесса. Если [`STARTF_USESTDHANDLES`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTF_USESTDHANDLES) не указан, по умолчанию для стандартного ввода используется буфер клавиатуры.388389#### `hStdOutput`390391Если в [`dwFlags`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO.dwFlags) указан флаг [`STARTF_USESTDHANDLES`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTF_USESTDHANDLES), этот атрибут является дескриптором стандартного вывода процесса. В противном случае этот атрибут игнорируется, и по умолчанию для стандартного вывода используется буфер окна консоли.392393#### `hStdError`394395If [`dwFlags`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO.dwFlags) specifies [`STARTF_USESTDHANDLES`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTF_USESTDHANDLES), this attribute is the standard error handle for the process. Otherwise, this attribute is ignored and the default for standard error is the console window’s buffer.396397#### `wShowWindow`398399Если в [`dwFlags`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO.dwFlags) указан флаг [`STARTF_USESHOWWINDOW`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTF_USESHOWWINDOW), то этот атрибут может принимать любое из значений, допустимых для параметра `nCmdShow` функции [ShowWindow](https://python-all.ru/3.2/library/subprocess.html), за исключением `SW_SHOWDEFAULT`. В противном случае данный атрибут игнорируется.400401Для этого атрибута предусмотрено значение [`SW_HIDE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.SW_HIDE). Оно используется, когда [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) вызывается с параметром `shell=True`.402403### 17.1.3.1. Константы404405Модуль [`подпроцесс`](https://python-all.ru/3.2/library/subprocess.html#module-subprocess) предоставляет следующие константы.406407#### `subprocess.STD_INPUT_HANDLE`408409Устройство стандартного ввода. Изначально это буфер ввода консоли, `CONIN$`.410411#### `subprocess.STD_OUTPUT_HANDLE`412413Устройство стандартного вывода. Изначально это активный экранный буфер консоли, `CONOUT$`.414415#### `subprocess.STD_ERROR_HANDLE`416417Устройство стандартного вывода ошибок. Изначально это активный экранный буфер консоли, `CONOUT$`.418419#### `subprocess.SW_HIDE`420421Скрывает окно. Другое окно будет активировано.422423#### `subprocess.STARTF_USESTDHANDLES`424425Указывает, что атрибуты [`STARTUPINFO.hStdInput`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO.hStdInput), [`STARTUPINFO.hStdOutput`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO.hStdOutput) и [`STARTUPINFO.hStdError`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO.hStdError) содержат дополнительную информацию.426427#### `subprocess.STARTF_USESHOWWINDOW`428429Указывает, что атрибут [`STARTUPINFO.wShowWindow`](https://python-all.ru/3.2/library/subprocess.html#subprocess.STARTUPINFO.wShowWindow) содержит дополнительную информацию.430431#### `subprocess.CREATE_NEW_CONSOLE`432433Новый процесс получает новую консоль вместо наследования консоли родителя (по умолчанию).434435Этот флаг всегда устанавливается, когда [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) создаётся с `shell=True`.436437#### `subprocess.CREATE_NEW_PROCESS_GROUP`438439Параметр `creationflags` функции [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen), указывающий, что будет создана новая группа процессов. Этот флаг необходим для использования [`os.kill()`](https://python-all.ru/3.2/library/os.html#os.kill) для подпроцесса.440441Этот флаг игнорируется, если указан [`CREATE_NEW_CONSOLE`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CREATE_NEW_CONSOLE).442443## 17.1.4. Замена устаревших функций с помощью [`подпроцесс`](https://python-all.ru/3.2/library/subprocess.html#module-subprocess) модуля444445В этом разделе «a становится b» означает, что b можно использовать как замену для a.446447> **Примечание**448>449> Все функции «a» в этом разделе при ненахождении исполняемой программы выдают ошибку (более или менее) молча; замены «b» вместо этого возбуждают исключение [`OSError`](https://python-all.ru/3.2/library/exceptions.html#OSError).450>451> Кроме того, замена с помощью [`check_output()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.check_output) завершится ошибкой [`CalledProcessError`](https://python-all.ru/3.2/library/subprocess.html#subprocess.CalledProcessError), если запрошенная операция вернёт ненулевой код возврата. Вывод по-прежнему доступен как атрибут `output` возбуждённого исключения.452453В следующих примерах предполагается, что соответствующие функции уже импортированы из модуля [`подпроцесс`](https://python-all.ru/3.2/library/subprocess.html#module-subprocess).454455### 17.1.4.1. Замена обратных кавычек оболочки /bin/sh456457```python458output=`mycmd myarg`459# becomes460output = check_output(["mycmd", "myarg"])461```462463### 17.1.4.2. Замена конвейера оболочки464465```python466output=`dmesg | grep hda`467# becomes468p1 = Popen(["dmesg"], stdout=PIPE)469p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)470p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.471output = p2.communicate()[0]472```473474Вызов p1.stdout.close() после запуска p2 важен для того, чтобы p1 получил SIGPIPE, если p2 завершится раньше p1.475476В качестве альтернативы, для доверенного ввода можно по-прежнему напрямую использовать встроенную поддержку конвейеров оболочки:477478```python479output=`dmesg | grep hda`480# becomes481output=check_output("dmesg | grep hda", shell=True)482```483484### 17.1.4.3. Замена [`os.system()`](https://python-all.ru/3.2/library/os.html#os.system)485486```python487sts = os.system("mycmd" + " myarg")488# становится489sts = call("mycmd" + " myarg", shell=True)490```491492Примечания:493494- Вызов программы через оболочку обычно не требуется.495496Более реалистичный пример выглядит так:497498```python499try:500    retcode = call("mycmd" + " myarg", shell=True)501    if retcode < 0:502        print("Child was terminated by signal", -retcode, file=sys.stderr)503    else:504        print("Child returned", retcode, file=sys.stderr)505except OSError as e:506    print("Execution failed:", e, file=sys.stderr)507```508509### 17.1.4.4. Замена семейства [`os.spawn`](https://python-all.ru/3.2/library/os.html#os.spawnl)510511Пример P\_NOWAIT:512513```python514pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")515==>516pid = Popen(["/bin/mycmd", "myarg"]).pid517```518519Пример P\_WAIT:520521```python522retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")523==>524retcode = call(["/bin/mycmd", "myarg"])525```526527Пример с вектором:528529```python530os.spawnvp(os.P_NOWAIT, path, args)531==>532Popen([path] + args[1:])533```534535Пример с окружением:536537```python538os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)539==>540Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})541```542543### 17.1.4.5. Замена `os.popen()`, `os.popen2()`, `os.popen3()`544545```python546(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)547==>548p = Popen(cmd, shell=True, bufsize=bufsize,549          stdin=PIPE, stdout=PIPE, close_fds=True)550(child_stdin, child_stdout) = (p.stdin, p.stdout)551```552553```python554(child_stdin,555 child_stdout,556 child_stderr) = os.popen3(cmd, mode, bufsize)557==>558p = Popen(cmd, shell=True, bufsize=bufsize,559          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)560(child_stdin,561 child_stdout,562 child_stderr) = (p.stdin, p.stdout, p.stderr)563```564565```python566(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)567==>568p = Popen(cmd, shell=True, bufsize=bufsize,569          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)570(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)571```572573Обработка кода возврата выполняется следующим образом:574575```python576pipe = os.popen(cmd, 'w')577...578rc = pipe.close()579if rc is not None and rc >> 8:580    print("There were some errors")581==>582process = Popen(cmd, 'w', stdin=PIPE)583...584process.stdin.close()585if process.wait() != 0:586    print("There were some errors")587```588589### 17.1.4.6. Замена функций из модуля `popen2`590591> **Примечание**592>593> Если аргумент cmd функций popen2 является строкой, команда выполняется через /bin/sh. Если это список, команда выполняется напрямую.594595```python596(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)597==>598p = Popen(["somestring"], shell=True, bufsize=bufsize,599          stdin=PIPE, stdout=PIPE, close_fds=True)600(child_stdout, child_stdin) = (p.stdout, p.stdin)601```602603```python604(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)605==>606p = Popen(["mycmd", "myarg"], bufsize=bufsize,607          stdin=PIPE, stdout=PIPE, close_fds=True)608(child_stdout, child_stdin) = (p.stdout, p.stdin)609```610611`popen2.Popen3` и `popen2.Popen4` в основном работают как [`subprocess.Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen), за исключением того, что:612613- [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen) возбуждает исключение, если выполнение завершается неудачей.614- аргумент *capturestderr* заменён аргументом *stderr*.615- Необходимо указать `stdin=PIPE` и `stdout=PIPE`.616- popen2 по умолчанию закрывает все файловые дескрипторы, но для гарантии такого поведения на всех платформах или в старых версиях Python необходимо указать `close_fds=True` вместе с [`Popen`](https://python-all.ru/3.2/library/subprocess.html#subprocess.Popen).617618## 17.1.5. Устаревшие функции вызова оболочки619620Этот модуль также предоставляет следующие устаревшие функции из модуля `commands` версии 2.x. Эти операции неявно вызывают системную оболочку, и ни одно из описанных выше гарантий безопасности и согласованности обработки исключений для этих функций не действует.621622#### `subprocess.getstatusoutput(cmd)`623624Возвращает `(status, output)` выполнения *cmd* в оболочке.625626Выполняет строку *cmd* в оболочке с помощью `os.popen()` и возвращает кортеж из двух элементов `(status, output)`. Строка *cmd* на самом деле выполняется как `{ cmd ; } 2>&1`, поэтому возвращаемый вывод содержит сообщения стандартного вывода и ошибок. Завершающий символ новой строки удаляется из вывода. Код завершения команды можно интерпретировать согласно правилам для C-функции `wait()`. Пример:627628```python629>>> subprocess.getstatusoutput('ls /bin/ls')630(0, '/bin/ls')631>>> subprocess.getstatusoutput('cat /bin/junk')632(256, 'cat: /bin/junk: No such file or directory')633>>> subprocess.getstatusoutput('/bin/junk')634(256, 'sh: /bin/junk: not found')635```636637Доступность: UNIX.638639#### `subprocess.getoutput(cmd)`640641Возвращает вывод (stdout и stderr) выполнения *cmd* в оболочке.642643Аналогично [`getstatusoutput()`](https://python-all.ru/3.2/library/subprocess.html#subprocess.getstatusoutput), за исключением того, что код возврата игнорируется, а возвращаемое значение – строка, содержащая вывод команды. Пример:644645```python646>>> subprocess.getoutput('ls /bin/ls')647'/bin/ls'648```649650Доступность: UNIX.651652## 17.1.6. Примечания653654### 17.1.6.1. Преобразование последовательности аргументов в строку в Windows655656В Windows последовательность *args* преобразуется в строку, которая может быть разобрана с помощью следующих правил (которые соответствуют правилам, используемым в MS C runtime):6576581. Аргументы разделяются пробельными символами, то есть пробелом или табуляцией.6592. Строка, заключённая в двойные кавычки, интерпретируется как один аргумент, независимо от пробельных символов внутри неё. Строка в кавычках может быть встроена в аргумент.6603. Двойная кавычка, перед которой стоит обратная косая черта, интерпретируется как литеральная двойная кавычка.6614. Обратные косые черты интерпретируются буквально, если только они не стоят непосредственно перед двойной кавычкой.6625. Если обратные косые черты стоят непосредственно перед двойной кавычкой, каждая пара обратных косых черт интерпретируется как литеральная обратная косая черта. Если количество обратных косых черт нечётное, последняя обратная косая черта экранирует следующую за ней двойную кавычку, как описано в правиле 3.663