`subprocess.md`

390 строк · 24.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/subprocess.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `подпроцесс` – Управление подпроцессами89Модуль `subprocess` позволяет порождать новые процессы, подключаться к их каналам ввода/вывода/ошибок и получать коды возврата. Этот модуль предназначен для замены нескольких других, более старых модулей и функций, таких как:1011```python12os.system13os.spawn*14```1516Информация о том, как модуль `subprocess` может использоваться для замены этих модулей и функций, находится в следующих разделах.1718> **См. также**19>20> [**PEP 324**](https://python-all.ru/3.0/library/subprocess.html) – PEP, предлагающий модуль подпроцесса2122## Использование модуля подпроцесс2324Этот модуль определяет один класс с именем [`Popen`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen):2526#### `[subprocess.Popen]class subprocess.Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=False, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0)`2728Аргументы:2930*args* должен быть строкой или последовательностью аргументов программы. Программа для выполнения обычно является первым элементом последовательности args или строкой, если задана строка, но может быть явно задана с помощью аргумента *executable*.3132В Unix с *shell=False* (по умолчанию): В этом случае класс Popen использует [`os.execvp()`](https://python-all.ru/3.0/library/os.html#os.execvp) для выполнения дочерней программы. *args* обычно должен быть последовательностью. Строка будет рассматриваться как последовательность, содержащая эту строку в качестве единственного элемента (программы для выполнения).3334В Unix с *shell=True*: Если args – строка, она задаёт командную строку для выполнения через оболочку. Если *args* является последовательностью, первый элемент задаёт командную строку, а любые дополнительные элементы будут рассматриваться как дополнительные аргументы оболочки.3536В Windows: класс [`Popen`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen) использует CreateProcess() для выполнения дочерней программы, которая работает со строками. Если *args* – последовательность, она будет преобразована в строку с помощью метода `list2cmdline()`. Обратите внимание, что не все приложения MS Windows интерпретируют командную строку одинаково: `list2cmdline()` предназначен для приложений, использующих те же правила, что и среда выполнения MS C.3738*bufsize*, если задан, имеет тот же смысл, что и соответствующий аргумент встроенной функции open(): `0` – без буферизации, `1` – построчная буферизация, любое другое положительное значение означает использование буфера (примерно) такого размера. Отрицательное *bufsize* означает использование системного значения по умолчанию, что обычно означает полную буферизацию. Значение по умолчанию для *bufsize* – `0` (без буферизации).3940Аргумент *executable* задаёт программу для выполнения. Он требуется очень редко: обычно программа для выполнения определяется аргументом *args*. Если `shell=True`, аргумент *executable* указывает, какую оболочку использовать. В Unix оболочкой по умолчанию является `/bin/sh`. В Windows оболочка по умолчанию задаётся переменной окружения **COMSPEC**.4142*stdin*, *stdout* и *stderr* задают дескрипторы файлов стандартного ввода, стандартного вывода и стандартного вывода ошибок выполняемой программы соответственно. Допустимые значения: [`PIPE`](https://python-all.ru/3.0/library/subprocess.html#subprocess.PIPE), существующий файловый дескриптор (положительное целое число), существующий файловый объект и `None`. [`PIPE`](https://python-all.ru/3.0/library/subprocess.html#subprocess.PIPE) означает, что должен быть создан новый канал к дочернему процессу. При `None` перенаправления не происходит; дескрипторы файлов дочернего процесса наследуются от родительского. Кроме того, *stderr* может быть [`STDOUT`](https://python-all.ru/3.0/library/subprocess.html#subprocess.STDOUT), что означает, что данные stderr из приложений должны быть захвачены в тот же дескриптор файла, что и для stdout.4344Если *preexec\_fn* задан как вызываемый объект, этот объект будет вызван в дочернем процессе непосредственно перед его выполнением. (Только Unix)4546Если *close\_fds* равен true, все файловые дескрипторы, кроме `0`, `1` и `2`, будут закрыты перед выполнением дочернего процесса. (Только Unix). Или, в Windows, если *close\_fds* равен true, то дочерний процесс не унаследует ни одного дескриптора. Обратите внимание: в Windows нельзя одновременно установить *close\_fds* в true и перенаправлять стандартные дескрипторы с помощью *stdin*, *stdout* или *stderr*.4748Если *shell* равен [`True`](https://python-all.ru/3.0/library/constants.html#True), указанная команда будет выполняться через оболочку.4950Если *cwd* не равен `None`, текущий каталог дочернего процесса будет изменён на *cwd* перед его выполнением. Обратите внимание, что этот каталог не учитывается при поиске исполняемого файла, поэтому нельзя указать путь к программе относительно *cwd*.5152Если *env* не равен `None`, он должен быть отображением, определяющим переменные окружения для нового процесса; они используются вместо наследования окружения текущего процесса, что является поведением по умолчанию.5354Если *universal\_newlines* равен [`True`](https://python-all.ru/3.0/library/constants.html#True), файловые объекты stdout и stderr открываются как текстовые файлы, но строки могут завершаться любым из символов: `'\n'` (соглашение Unix), `'\r'` (соглашение старых Macintosh) или `'\r\n'` (соглашение Windows). Все эти внешние представления воспринимаются программой Python как `'\n'`.5556> **Примечание**57>58> Эта возможность доступна только в том случае, если Python собран с поддержкой универсальных символов новой строки (по умолчанию). Кроме того, атрибут newlines файловых объектов [`stdout`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.stdout), [`stdin`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.stdin) и [`stderr`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.stderr) не обновляется методом [`communicate()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.communicate).5960Параметры *startupinfo* и *creationflags*, если они заданы, будут переданы базовой функции CreateProcess(). Они могут задавать такие вещи, как внешний вид главного окна и приоритет нового процесса. (Только в Windows)6162#### `[subprocess.PIPE]subprocess.PIPE`6364Специальное значение, которое может использоваться в качестве аргумента6566*stdin*6768,6970*stdout*7172или7374*stderr*7576для7778[`Popen`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen)7980и указывает, что должен быть открыт канал к стандартному потоку.8182#### `[subprocess.STDOUT]subprocess.STDOUT`8384Специальное значение, которое может использоваться в качестве аргумента8586*stderr*8788для8990[`Popen`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen)9192и указывает, что стандартный поток ошибок должен направляться в тот же дескриптор, что и стандартный вывод.9394### Вспомогательные функции9596Этот модуль также определяет четыре вспомогательные функции:9798#### `[subprocess.call]subprocess.call(*popenargs, **kwargs)`99100Запускает команду с аргументами. Ожидает завершения команды, затем возвращает атрибут `returncode`.101102Аргументы такие же, как у конструктора Popen. Пример:103104```python105retcode = call(["ls", "-l"])106```107108#### `[subprocess.check_call]subprocess.check_call(*popenargs, **kwargs)`109110Запускает команду с аргументами. Ожидает завершения команды. Если код возврата равен нулю, то завершается, иначе возбуждает `CalledProcessError`. Объект `CalledProcessError` будет содержать код возврата в атрибуте `returncode`.111112Аргументы такие же, как у конструктора Popen. Пример:113114```python115check_call(["ls", "-l"])116```117118#### `[subprocess.getstatusoutput]subprocess.getstatusoutput(cmd)`119120#### `` Return ``(status, output)`` of executing *cmd* in a shell. ``121122Выполняет строку *cmd* в оболочке с помощью `os.popen()` и возвращает кортеж из двух элементов `(status, output)`. *cmd* фактически выполняется как `{ cmd ; } 2>&1`, так что возвращаемый вывод будет содержать сообщения вывода или ошибок. Конечный символ новой строки удаляется из вывода. Код завершения команды можно интерпретировать в соответствии с правилами для функции C `wait`. Пример:123124```python125>>> import subprocess126>>> subprocess.getstatusoutput('ls /bin/ls')127(0, '/bin/ls')128>>> subprocess.getstatusoutput('cat /bin/junk')129(256, 'cat: /bin/junk: No such file or directory')130>>> subprocess.getstatusoutput('/bin/junk')131(256, 'sh: /bin/junk: not found')132```133134Доступность: UNIX.135136#### `[subprocess.getoutput]subprocess.getoutput(cmd)`137138#### `` Return output ``(stdout or stderr)`` of executing *cmd* in a shell. ``139140Аналогично [`getstatusoutput()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.getstatusoutput), за исключением того, что код возврата игнорируется, а возвращаемое значение – строка, содержащая вывод команды. Пример:141142```python143>>> import subprocess144>>> subprocess.getoutput('ls /bin/ls')145'/bin/ls'146```147148Доступность: UNIX.149150### Исключения151152Исключения, возникшие в дочернем процессе до начала выполнения новой программы, будут повторно возбуждены в родительском процессе. Кроме того, объект исключения будет иметь дополнительный атрибут `child_traceback`, который представляет собой строку, содержащую информацию трассировки с точки зрения дочернего процесса.153154Наиболее часто возбуждаемым исключением является [`OSError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OSError). Оно возникает, например, при попытке выполнить несуществующий файл. Приложения должны быть готовы к исключениям [`OSError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OSError).155156Исключение [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) будет возбуждено, если [`Popen`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen) вызван с недопустимыми аргументами.157158check\_call() возбуждает `CalledProcessError`, если вызванный процесс возвращает ненулевой код возврата.159160### Безопасность161162В отличие от некоторых других функций popen, данная реализация никогда не вызывает /bin/sh неявно. Это означает, что все символы, включая метасимволы оболочки, могут безопасно передаваться дочерним процессам.163164## Объекты Popen165166Экземпляры класса [`Popen`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen) имеют следующие методы:167168#### `[subprocess.Popen.poll]Popen.poll()`169170Проверяет, завершён ли дочерний процесс. Устанавливает и возвращает атрибут171172[`returncode`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.returncode)173174.175176#### `[subprocess.Popen.wait]Popen.wait()`177178Ожидает завершения дочернего процесса. Устанавливает и возвращает атрибут [`returncode`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.returncode).179180> **Предупреждение**181>182> Это приведет к взаимной блокировке, если дочерний процесс создаст достаточно выходных данных для канала stdout или stderr, так что он заблокируется в ожидании, пока буфер канала ОС не сможет принять больше данных. Используйте [`communicate()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.communicate), чтобы избежать этого.183184#### `[subprocess.Popen.communicate]Popen.communicate(input=None)`185186Взаимодействие с процессом: отправляет данные в stdin. Читает данные из stdout и stderr до достижения конца файла. Ожидает завершения процесса. Необязательный аргумент *input* должен быть байтовой строкой для отправки дочернему процессу, или `None`, если данные не должны отправляться.187188[`communicate()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.communicate) возвращает кортеж `(stdoutdata, stderrdata)`.189190Обратите внимание: для отправки данных в stdin процесса объект Popen должен быть создан с `stdin=PIPE`. Аналогично, чтобы получить в результирующем кортеже что-либо, кроме `None`, нужно также указать `stdout=PIPE` и/или `stderr=PIPE`.191192> **Примечание**193>194> Прочитанные данные буферизуются в памяти, поэтому не используйте этот метод, если размер данных велик или неограничен.195196#### `[subprocess.Popen.send_signal]Popen.send_signal(signal)`197198Отправляет сигнал *signal* дочернему процессу.199200> **Примечание**201>202> В Windows на данный момент поддерживается только SIGTERM. Это псевдоним для [`terminate()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.terminate).203204#### `[subprocess.Popen.terminate]Popen.terminate()`205206Останавливает дочерний процесс. В ОС Posix метод отправляет SIGTERM дочернему процессу. В Windows для остановки дочернего процесса вызывается функция Win32 API207208`TerminateProcess`209210.211212#### `[subprocess.Popen.kill]Popen.kill()`213214Завершает дочерний процесс. В ОС POSIX функция отправляет дочернему процессу сигнал SIGKILL. В Windows215216[`kill()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.kill)217218– это псевдоним для219220[`terminate()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.terminate)221222.223224Также доступны следующие атрибуты:225226> **Предупреждение**227>228> Используйте `communicate()` вместо `stdin.write()`, `stdout.read()` или `stderr.read()`, чтобы избежать взаимоблокировок из-за переполнения буферов каналов ОС и блокировки дочернего процесса.229230#### `[subprocess.Popen.stdin]Popen.stdin`231232Если аргумент233234*stdin*235236был237238[`PIPE`](https://python-all.ru/3.0/library/subprocess.html#subprocess.PIPE)239240, то этот атрибут представляет собой файловый объект, который передаёт входные данные дочернему процессу. В противном случае он равен241242`None`243244.245246#### `[subprocess.Popen.stdout]Popen.stdout`247248Если аргумент249250*stdout*251252был253254[`PIPE`](https://python-all.ru/3.0/library/subprocess.html#subprocess.PIPE)255256, то этот атрибут представляет собой файловый объект, содержащий вывод дочернего процесса. В противном случае он равен257258`None`259260.261262#### `[subprocess.Popen.stderr]Popen.stderr`263264Если аргумент265266*stderr*267268был269270[`PIPE`](https://python-all.ru/3.0/library/subprocess.html#subprocess.PIPE)271272, то этот атрибут представляет собой файловый объект, содержащий сообщения об ошибках дочернего процесса. В противном случае он равен273274`None`275276.277278#### `[subprocess.Popen.pid]Popen.pid`279280PID дочернего процесса.281282#### `[subprocess.Popen.returncode]Popen.returncode`283284Код возврата дочернего процесса, устанавливаемый методами [`poll()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.poll) и [`wait()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.wait) (а косвенно и [`communicate()`](https://python-all.ru/3.0/library/subprocess.html#subprocess.Popen.communicate)). Значение `None` указывает, что процесс ещё не завершён.285286Отрицательное значение `-N` означает, что дочерний процесс был завершён сигналом `N` (только в Unix).287288## Замена устаревших функций модулем подпроцесс289290В этом разделе «a ==\> b» означает, что b можно использовать как замену a.291292> **Примечание**293>294> Все функции в этом разделе (более или менее) молча завершаются ошибкой, если выполняемая программа не может быть найдена; этот модуль вызывает исключение [`OSError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OSError).295296В следующих примерах предполагается, что модуль подпроцесс импортирован с помощью «from subprocess import \*».297298### Замена обратного апострофа оболочки /bin/sh299300```python301output=`mycmd myarg`302==>303output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]304```305306### Замена конвейера оболочки307308```python309output=`dmesg | grep hda`310==>311p1 = Popen(["dmesg"], stdout=PIPE)312p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)313output = p2.communicate()[0]314```315316### Замена os.system()317318```python319sts = os.system("mycmd" + " myarg")320==>321p = Popen("mycmd" + " myarg", shell=True)322sts = os.waitpid(p.pid, 0)323```324325Примечания:326327- Вызов программы через оболочку обычно не требуется.328- Проще смотреть на атрибут `returncode`, чем на код завершения.329330Более реалистичный пример выглядит так:331332```python333try:334    retcode = call("mycmd" + " myarg", shell=True)335    if retcode < 0:336        print("Child was terminated by signal", -retcode, file=sys.stderr)337    else:338        print("Child returned", retcode, file=sys.stderr)339except OSError as e:340    print("Execution failed:", e, file=sys.stderr)341```342343### Замена семейства os.spawn344345Пример P\_NOWAIT:346347```python348pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")349==>350pid = Popen(["/bin/mycmd", "myarg"]).pid351```352353Пример P\_WAIT:354355```python356retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")357==>358retcode = call(["/bin/mycmd", "myarg"])359```360361Пример с вектором:362363```python364os.spawnvp(os.P_NOWAIT, path, args)365==>366Popen([path] + args[1:])367```368369Пример с окружением:370371```python372os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)373==>374Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})375```376377### Замена os.popen378379```python380pipe = os.popen(cmd, 'r', bufsize)381==>382pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout383```384385```python386pipe = os.popen(cmd, 'w', bufsize)387==>388pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin389```390