subprocess — Управление дочерними процессами

Исходный код: Lib/subprocess.py

Модуль subprocess позволяет запускать новые процессы, подключаться к их каналам ввода/вывода/ошибок и получать их коды возврата. Этот модуль призван заменить несколько устаревших модулей и функций:

os.system
os.spawn*

Информация о том, как модуль subprocess может быть использован для замены этих модулей и функций, приведена в следующих разделах.

См. также

PEP 324 — PEP, предлагающий модуль subprocess

Доступность: не Emscripten, не WASI.

Этот модуль не работает или недоступен на платформах WebAssembly wasm32-emscripten и wasm32-wasi. Дополнительную информацию см. в разделе Платформы WebAssembly.

Использование модуля subprocess

Рекомендуемый подход к вызову подпроцессов — использовать функцию run() для всех случаев, которые она может обработать. Для более сложных случаев можно напрямую использовать интерфейс Popen.

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, capture_output=False, shell=False, cwd=None, timeout=None, check=False, encoding=None, errors=None, text=None, env=None, universal_newlines=None, **other_popen_kwargs)

Выполняет команду, описанную в args. Ждёт завершения команды, а затем возвращает экземпляр CompletedProcess.

Приведённые выше аргументы — лишь наиболее распространённые, описанные ниже в Часто используемые аргументы (отсюда использование нотации только ключевых слов в сокращённой сигнатуре). Полная сигнатура функции в основном такая же, как у конструктора Popen — большинство аргументов этой функции передаются в этот интерфейс. (timeout, input, check и capture_output не передаются.)

Если capture_output имеет значение true, stdout и stderr будут захвачены. При использовании внутренний объект Popen автоматически создаётся с stdout=PIPE и stderr=PIPE. Аргументы stdout и stderr не могут быть переданы одновременно с capture_output. Если вы хотите захватить и объединить оба потока в один, используйте stdout=PIPE и stderr=STDOUT вместо capture_output.

timeout может быть указан в секундах, он передаётся во внутренний вызов Popen.communicate(). Если таймаут истекает, подпроцесс будет убит, и будет подождано его завершение. Исключение TimeoutExpired будет повторно поднято после завершения подпроцесса. На многих платформах API создания процесса изначально прервать нельзя, поэтому нет гарантии, что исключение таймаута произойдёт сразу же после создания, а только после ожидания определённого времени.

Аргумент input передаётся в Popen.communicate() и, следовательно, в стандартный ввод подпроцесса. При использовании это должна быть последовательность байтов или строка, если указаны encoding или errors, или text имеет значение true. При использовании внутренний объект Popen автоматически создаётся с stdin=PIPE, и аргумент stdin также не может быть использован.

Если check имеет значение true, и процесс завершается с ненулевым кодом возврата, будет поднято исключение CalledProcessError. Атрибуты этого исключения содержат аргументы, код возврата и stdout и stderr, если они были захвачены.

Если указаны encoding или errors, или text имеет значение true, файлы для стандартного ввода, вывода и стандартной ошибки открываются в текстовом режиме с указанными encoding и errors или значениями по умолчанию io.TextIOWrapper. Аргумент universal_newlines эквивалентен text и предоставляется для обратной совместимости. По умолчанию файлы открываются в двоичном режиме.

Если env не None, он должен быть отображением, определяющим переменные среды для нового процесса; они используются вместо поведения по умолчанию, которое наследует среду текущего процесса. Он передаётся непосредственно в Popen. Это отображение может быть от str к str на любой платформе или от bytes к bytes на платформах POSIX, очень похоже на os.environ или os.environb.

Примеры:

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')

Новая в версии 3.5.

Изменено в версии 3.6: Добавлены параметры encoding и errors

Изменено в версии 3.7: Добавлен параметр text в качестве более понятного псевдонима universal_newlines. Добавлена параметр capture_output.

Изменено в версии 3.11.3: Изменён порядок поиска оболочки Windows для shell=True. Текущая папка и %PATH% заменяются на %COMSPEC% и %SystemRoot%\System32\cmd.exe. В результате, размещение вредоносной программы с именем cmd.exe в текущей папке больше не работает.

class subprocess.CompletedProcess

Значение, возвращаемое run(), представляющее собой процесс, завершивший свою работу.

args: Аргументы, используемые для запуска процесса. Это может быть список или строка.

returncode

Код завершения дочернего процесса. Обычно код завершения 0 указывает, что процесс завершился успешно.

Отрицательное значение -N указывает, что дочерний процесс был завершён сигналом N (только POSIX).

stdout

Захваченный stdout дочернего процесса. Последовательность байтов или строка, если run() вызывалась с кодировкой, ошибками или text=True. None если stdout не был захвачен.

Если вы запустили процесс с stderr=subprocess.STDOUT, stdout и stderr будут объединены в этом атрибуте, и stderr будет None.

stderr: Захваченный stderr дочернего процесса. Последовательность байтов или строка, если run() вызывалась с кодировкой, ошибками или text=True. None если stderr не был захвачен.

check_returncode(): Если returncode не равен нулю, вызовите исключение CalledProcessError.

Новая в версии 3.5.

subprocess.DEVNULL: Специальное значение, которое может использоваться в качестве аргумента stdin, stdout или stderr для Popen и указывает, что будет использован специальный файл os.devnull.

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

subprocess.PIPE: Специальное значение, которое может использоваться в качестве аргумента stdin, stdout или stderr для Popen и указывает на открытие канала к стандартному потоку. Наиболее полезно с Popen.communicate().

subprocess.STDOUT: Специальное значение, которое может использоваться в качестве аргумента stderr для Popen и указывает, что стандартная ошибка должна быть направлена в тот же поток, что и стандартный вывод.

exception subprocess.SubprocessError: Базовый класс для всех остальных исключений из этого модуля.

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

exception subprocess.TimeoutExpired

Подкласс SubprocessError, поднимаемый при истечении таймаута ожидания дочернего процесса.

cmd: Команда, которая была использована для запуска дочернего процесса.

timeout: Таймаут в секундах.

output: Вывод дочернего процесса, если он был перехвачен run() или check_output(). В противном случае, None. Это всегда bytes, когда любой вывод был перехвачен независимо от text=True настройки. Может оставаться None вместо b'' при отсутствии вывода.

stdout: Псевдоним для output для симметрии с stderr.

stderr: Вывод stderr дочернего процесса, если он был перехвачен run(). В противном случае, None. Это всегда bytes, когда вывод stderr был перехвачен независимо от text=True настройки. Может оставаться None вместо b'' при отсутствии вывода stderr.

New in version 3.3.

Changed in version 3.5: stdout и stderr атрибуты добавлены

exception subprocess.CalledProcessError

Подкласс SubprocessError, поднимаемый, когда процесс, запущенный с помощью check_call(), check_output() или run() (с check=True) возвращает не нулевой код выхода.

returncode: Код завершения дочернего процесса. Если процесс завершился из-за сигнала, это будет отрицательное число сигнала.

cmd: Команда, которая была использована для запуска дочернего процесса.

output: Вывод дочернего процесса, если он был перехвачен run() или check_output(). В противном случае, None.

stdout: Псевдоним для output для симметрии с stderr.

stderr: Вывод stderr дочернего процесса, если он был перехвачен run(). В противном случае, None.

Изменено в версии 3.5: атрибуты stdout и stderr добавлены

Часто используемые аргументы

Для поддержки широкого круга случаев использования конструктор Popen (и функции-обёртки) принимает большое количество необязательных аргументов. Для большинства типовых случаев использования многие из этих аргументов можно безопасно оставить со значениями по умолчанию. Аргументы, которые чаще всего необходимы, это:

args требуется для всех вызовов и должен быть строкой или последовательностью аргументов программы. Передача последовательности аргументов обычно предпочтительнее, поскольку это позволяет модулю позаботиться об необходимой экранизации и цитировании аргументов (например, для разрешения пробелов в именах файлов). Если передаётся строка, то shell должен быть True (см. ниже), или же эта строка должна просто указывать имя выполняемой программы без указания каких-либо аргументов.

stdin, stdout и stderr задают стандартный ввод, стандартный вывод и стандартную ошибку выполняемой программы соответственно. Допустимыми значениями являются PIPE, DEVNULL, существующий дескриптор файла (положительное целое число), существующий объект файла с допустимым дескриптором файла и None. PIPE указывает на то, что должен быть создан новый канал для дочернего процесса. DEVNULL указывает, что будет использован специальный файл os.devnull. При значениях по умолчанию для None, перенаправление не произойдёт; дескрипторы файлов дочернего процесса будут унаследованы от родительского.

Кроме того, stderr может быть STDOUT, что указывает на то, что данные об ошибках (stderr) дочернего процесса должны быть сохранены в том же дескрипторе файла, что и stdout.

Если заданы encoding или errors, или text (также известный как universal_newlines) равно true, объекты файлов stdin, stdout и stderr будут открыты в текстовом режиме с использованием заданных в вызове encoding и errors или значений по умолчанию для io.TextIOWrapper.

Для stdin символы конца строки '\n' на вводе будут преобразованы в стандартный разделитель строк os.linesep. Для stdout и stderr все символы конца строки в выводе будут преобразованы в '\n'. Для получения дополнительной информации см. документацию класса io.TextIOWrapper, когда аргумент newline в его конструкторе None.

Если режим текста не используется, stdin, stdout и stderr будут открыты как двоичные потоки. Никакое кодирование или преобразование символов конца строки не выполняется.

Добавлен в версии 3.6: Добавлены параметры encoding и errors.

Добавлен в версии 3.7: Добавлен параметр text как псевдоним для universal_newlines.

Примечание

Атрибут newlines объектов файлов Popen.stdin, Popen.stdout и Popen.stderr не обновляются методом Popen.communicate().

Если shell True, указанная команда будет выполнена через оболочку. Это может быть полезно, если вы в основном используете Python для расширенного управления потоком по сравнению с большинством системных оболочек и хотите получить удобный доступ к другим функциям оболочки, таким как оболочечные конвейеры, подстановки имён файлов, расширения переменных среды и расширения ~ до домашнего каталога пользователя. Однако обратите внимание, что сам Python предлагает реализации многих функций, похожих на оболочку (в частности, glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser() и shutil).

Изменено в версии 3.3: Когда universal_newlines True, класс использует кодировку locale.getpreferredencoding(False) вместо locale.getpreferredencoding(). Более подробную информацию об этом изменении см. в классе io.TextIOWrapper.

Примечание

Перед использованием shell=True прочтите раздел Рекомендации по безопасности.

Эти опции, наряду со всеми другими, описаны более подробно в документации конструктора Popen.

Конструктор Popen

Базовое создание процесса и управление им в этом модуле реализовано классом Popen. Он предлагает большую гибкость, чтобы разработчики могли обрабатывать менее распространённые случаи, не покрытые функциями-обёртками.

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=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, group=None, extra_groups=None, user=None, umask=- 1, encoding=None, errors=None, text=None, pipesize=- 1, process_group=None)

Выполните дочернюю программу в новом процессе. В POSIX, класс использует поведение, подобное os.execvpe(), для выполнения дочерней программы. В Windows, класс использует функцию Windows CreateProcess(). Аргументы для Popen следующие.

args должно быть последовательностью аргументов программы или же одиночной строкой или объектом, подобным пути. По умолчанию, программа для выполнения — это первый элемент в args, если args является последовательностью. Если args — это строка, интерпретация зависит от платформы и описана ниже. См. аргументы shell и executable для дополнительных различий от поведения по умолчанию. Если не указано иное, рекомендуется передавать args как последовательность.

Предупреждение

Для максимальной надёжности используйте полный путь к исполняемому файлу. Для поиска неопределённого имени на PATH, используйте shutil.which(). На всех платформах рекомендуется использовать sys.executable для повторного запуска текущего интерпретатора Python и использовать формат командной строки -m для запуска установленного модуля.

Разрешение пути executable (или первого элемента args) зависит от платформы. Для POSIX см. os.execvpe(), и обратите внимание, что при разрешении или поиске пути исполняемого файла, cwd переопределяет текущую рабочую директорию, а env может переопределить переменную среды PATH. Для Windows см. документацию параметров lpApplicationName и lpCommandLine WinAPI CreateProcess, и обратите внимание, что при разрешении или поиске пути исполняемого файла с shell=False, cwd не переопределяет текущую рабочую директорию, а env не может переопределить переменную среды PATH. Использование полного пути избегает всех этих вариаций.

Пример передачи некоторых аргументов внешней программе как последовательности:

Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])

В POSIX, если args — это строка, строка интерпретируется как имя или путь к выполняемой программе. Однако это можно сделать только если не передавать аргументы программе.

Примечание

Может быть не очевидно, как разбить командную строку оболочки на последовательность аргументов, особенно в сложных случаях. shlex.split() может проиллюстрировать, как определить правильную токенизацию для args:

>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!

Обратите особое внимание, что опции (например, -input) и аргументы (например, eggs.txt), разделенные пробелами в оболочке, попадают в отдельные элементы списка, в то время как аргументы, требующие кавычек или обратного слеша при использовании в оболочке (например, имена файлов, содержащие пробелы или команда echo, показанная выше), являются отдельными элементами списка.

В Windows, если args — это последовательность, она будет преобразована в строку способом, описанным в Преобразование последовательности аргументов в строку в Windows. Это связано с тем, что основная функция CreateProcess() работает со строками.

Изменено в версии 3.6: Параметр args принимает объект, подобный пути, если shell равно False и последовательность, содержащую объекты, подобные пути, в POSIX.

Изменено в версии 3.8: Параметр args принимает объект, подобный пути, если shell равно False и последовательность, содержащую байты и объекты, подобные пути, в Windows.

Аргумент shell (по умолчанию False) указывает, следует ли использовать оболочку в качестве программы для выполнения. Если shell равно True, рекомендуется передавать args как строку, а не как последовательность.

В POSIX при shell=True, оболочка по умолчанию /bin/sh. Если args — это строка, строка указывает команду, которую нужно выполнить через оболочку. Это означает, что строка должна быть отформатирована точно так же, как она вводилась бы в командной строке оболочки. Это включает, например, кавычки или обратный слэш для имен файлов с пробелами. Если args — это последовательность, первый элемент указывает строку команды, а любые дополнительные элементы будут обрабатываться как дополнительные аргументы для самой оболочки. Это означает, что Popen выполняет эквивалент:

Popen(['/bin/sh', '-c', args[0], args[1], ...])

В Windows при shell=True, переменная среды COMSPEC указывает оболочку по умолчанию. Единственный случай, когда вам нужно указать shell=True в Windows, — это когда команда, которую вы хотите выполнить, встроена в оболочку (например, dir или copy). Вам не нужна shell=True для запуска пакетного файла или исполняемого файла консоли.

Примечание

Перед использованием shell=True ознакомьтесь с разделом «Соображения безопасности».

bufsize будет передан как соответствующий аргумент функции open() при создании объектов файлов stdin/stdout/stderr:

0 означает небуферизованный (чтение и запись — одна системная вызов и могут вернуть короткие данные)
1 означает буферизованный по строкам (используется только если text=True или universal_newlines=True)
любое другое положительное значение означает использование буфера примерно такого размера
отрицательное значение bufsize (по умолчанию) означает использование системного значения по умолчанию io.DEFAULT_BUFFER_SIZE.

Изменено в версии 3.3.1: bufsize теперь по умолчанию равен -1, чтобы включить буферизацию по умолчанию, что соответствует поведению, ожидаемому большинством кода. В версиях до Python 3.2.4 и 3.3.1 значение по умолчанию ошибочно было 0, что было небуферизованным и допускало короткие чтения. Это было непреднамеренно и не соответствовало поведению Python 2, как ожидалось большинством кода.

Аргумент executable указывает заменяющую программу для выполнения. Он очень редко нужен. При shell=False, executable заменяет программу для выполнения, указанную в args. Тем не менее, исходные args все равно передаются программе. Большинство программ обрабатывают программу, указанную в args, как имя команды, которое может отличаться от фактически исполняемой программы. В POSIX, имя args становится отображаемым именем исполняемого файла в таких утилитах, как ps. Если shell=True, в POSIX аргумент executable указывает заменяющую оболочку для значения по умолчанию /bin/sh.

Изменено в версии 3.6: Параметр executable принимает объект, подобный пути в POSIX.

Изменено в версии 3.8: Параметр executable принимает байты и объект, подобный пути в Windows.

Изменено в версии 3.11.3: Изменён порядок поиска оболочки Windows для shell=True. Текущая директория и %PATH% заменены на %COMSPEC% и %SystemRoot%\System32\cmd.exe. В результате, размещение вредоносной программы с именем cmd.exe в текущей директории больше не работает.

stdin, stdout и stderr соответственно задают стандартный вход, стандартный вывод и стандартную ошибку выполняемой программы. Допустимые значения — PIPE, DEVNULL, существующий дескриптор файла (положительное целое число), существующий объект файла с допустимым дескриптором файла и None. PIPE указывает на создание новой трубы к дочернему процессу. DEVNULL указывает на использование специального файла os.devnull. При стандартных настройках None, перенаправления не будет; дескрипторы файлов дочернего процесса будут унаследованы от родительского. Кроме того, stderr может быть STDOUT, что означает, что данные об ошибках приложения должны быть захвачены в тот же дескриптор файла, что и stdout.

Если preexec_fn имеет значение вызываемого объекта, этот объект будет вызван в дочернем процессе сразу перед выполнением дочернего процесса. (Только POSIX)

Предупреждение

Параметр preexec_fn НЕ БЕЗОПАСНО использовать при наличии потоков в вашем приложении. Дочерний процесс может заблокироваться до вызова exec.

Примечание

Если вам нужно изменить среду для дочернего процесса, используйте параметр env, а не делайте это в preexec_fn. Параметры start_new_session и process_group должны заменить код, использующий preexec_fn для вызова os.setsid() или os.setpgid() в дочернем процессе.

Изменено в версии 3.8: Параметр preexec_fn больше не поддерживается в подинтерпретаторах. Использование параметра в подинтерпретаторе вызывает RuntimeError. Новое ограничение может повлиять на приложения, развернутые в mod_wsgi, uWSGI и других встроенных средах.

Если close_fds имеет значение true, все дескрипторы файлов, кроме 0, 1 и 2, будут закрыты перед выполнением дочернего процесса. В противном случае, при close_fds равном false, дескрипторы файлов подчиняются своему флагу наследуемости, как описано в Наследование дескрипторов файлов.

В Windows, если close_fds имеет значение true, никакие дескрипторы не будут унаследованы дочерним процессом, если явно не переданы в элементе handle_list объекта STARTUPINFO.lpAttributeList или через стандартное перенаправление дескрипторов.

Изменено в версии 3.2: Значение по умолчанию для close_fds было изменено с False на указанное выше.

Изменено в версии 3.7: В Windows по умолчанию для close_fds было установлено значение True при перенаправлении стандартных дескрипторов. Теперь можно установить close_fds в True при перенаправлении стандартных дескрипторов.

pass_fds — это необязательная последовательность дескрипторов файлов, которые необходимо оставить открытыми между родительским и дочерним процессами. Передача pass_fds принудительно устанавливает close_fds в True. (Только POSIX)

Изменено в версии 3.2: Параметр pass_fds был добавлен.

Если cwd не None, функция изменяет текущую рабочую директорию на cwd перед выполнением дочернего процесса. cwd может быть строкой, байтовым объектом или объектом пути. В POSIX функция ищет executable (или первый элемент в args) относительно cwd, если путь к исполняемому файлу — это относительный путь.

Изменено в версии 3.6: Параметр cwd принимает объект пути в POSIX.

Изменено в версии 3.7: Параметр cwd принимает объект пути в Windows.

Изменено в версии 3.8: Параметр cwd принимает байтовый объект в Windows.

Если restore_signals имеет значение true (по умолчанию), все сигналы, которые Python установил в SIG_IGN, восстанавливаются до SIG_DFL в дочернем процессе перед выполнением exec. В настоящее время это включает сигналы SIGPIPE, SIGXFZ и SIGXFSZ. (Только POSIX)

Изменено в версии 3.2: Добавлен параметр restore_signals.

Если start_new_session имеет значение true, вызов setsid() будет выполнен в дочернем процессе перед выполнением дочернего процесса.

Доступность: POSIX

Изменено в версии 3.2: Добавлен параметр start_new_session.

Если process_group — положительное целое число, вызов setpgid(0, value) будет выполнен в дочернем процессе перед выполнением дочернего процесса.

Доступность: POSIX

Изменено в версии 3.11: Добавлен параметр process_group.

Если group не None, вызов setregid() будет выполнен в дочернем процессе перед выполнением дочернего процесса. Если предоставленное значение — строка, оно будет найдено с помощью grp.getgrnam(), и значение из gr_gid будет использовано. Если значение — целое число, оно будет передано в неизменном виде. (Только POSIX)

Доступность: POSIX

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

Если extra_groups не None, вызов setgroups() будет выполнен в дочернем процессе перед выполнением дочернего процесса. Строковые значения в extra_groups будут найдены с помощью grp.getgrnam(), и значения из gr_gid будут использованы. Целые значения будут переданы в неизменном виде. (Только POSIX)

Доступность: POSIX

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

Если user не None, вызов setreuid() будет выполнен в дочернем процессе перед выполнением дочернего процесса. Если предоставленное значение — строка, оно будет найдено с помощью pwd.getpwnam(), и значение из pw_uid будет использовано. Если значение — целое число, оно будет передано в неизменном виде. (Только POSIX)

Доступность: POSIX

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

Если umask не отрицательное число, вызов umask() будет выполнен в дочернем процессе перед выполнением дочернего процесса.

Доступность: POSIX

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

Если env не None, оно должно быть отображением, определяющим переменные среды для нового процесса; они используются вместо стандартного поведения наследования текущей среды процесса. Это отображение может быть из str в str на любой платформе или из bytes в bytes на платформах POSIX, аналогично os.environ или os.environb.

Примечание

Если указан env, он должен содержать все переменные, необходимые для выполнения программы. В Windows, для запуска side-by-side assembly, указанный env должен включать корректную SystemRoot.

Если заданы encoding или errors, или text имеет значение true, файлы stdin, stdout и stderr открываются в текстовом режиме с указанным encoding и errors, как описано выше в Часто используемые аргументы. Аргумент universal_newlines эквивалентен text и предоставлен для обратной совместимости. По умолчанию файлы открываются в двоичном режиме.

Новое в версии 3.6: Добавлены encoding и errors.

Новое в версии 3.7: Добавлен text как более читаемый псевдоним для universal_newlines.

Если задан startupinfo, он будет объектом STARTUPINFO, который передаётся в базовую функцию CreateProcess. creationflags, если задан, может быть одной или несколькими из следующих флагов:

CREATE_NEW_CONSOLE
CREATE_NEW_PROCESS_GROUP
ABOVE_NORMAL_PRIORITY_CLASS
BELOW_NORMAL_PRIORITY_CLASS
HIGH_PRIORITY_CLASS
IDLE_PRIORITY_CLASS
NORMAL_PRIORITY_CLASS
REALTIME_PRIORITY_CLASS
CREATE_NO_WINDOW
DETACHED_PROCESS
CREATE_DEFAULT_ERROR_MODE
CREATE_BREAKAWAY_FROM_JOB

pipesize можно использовать для изменения размера канала, когда PIPE используется для stdin, stdout или stderr. Размер канала изменяется только на платформах, которые поддерживают это (пока только Linux). Другие платформы игнорируют этот параметр.

Добавлено в версии 3.10: Параметр pipesize был добавлен.

Объекты Popen поддерживаются как менеджеры контекста с помощью оператора with: при выходе стандартные файловые дескрипторы закрываются, и процесс ожидает завершения.

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

Объекты Popen и другие функции в этом модуле, использующие его, поднимают событие аудита аудита subprocess.Popen с аргументами executable, args, cwd, и env. Значение для args может быть одной строкой или списком строк, в зависимости от платформы.

Изменено в версии 3.2: Добавлена поддержка менеджера контекста.

Изменено в версии 3.6: Деструктор Popen теперь выводит предупреждение ResourceWarning, если дочерний процесс всё ещё работает.

Изменено в версии 3.8: Popen может использовать os.posix_spawn() в некоторых случаях для повышения производительности. В Windows Subsystem для Linux и QEMU User Emulation конструктор Popen, использующий os.posix_spawn(), больше не поднимает исключение при ошибках, таких как отсутствие программы, но дочерний процесс завершается с ненулевым returncode.

Исключения

Исключения, возникающие в дочернем процессе до запуска новой программы, будут переброшены в родительский процесс.

Самое распространенное исключение — OSError. Оно возникает, например, при попытке выполнить несуществующий файл. Приложения должны быть готовы к исключениям OSError. Обратите внимание, что, когда shell=True, OSError будет поднято дочерним процессом только в том случае, если сам выбранный интерпретатор не был найден. Чтобы определить, не смог ли интерпретатор найти запрошенное приложение, необходимо проверить код возврата или вывод из дочернего процесса.

Исключение ValueError будет поднято, если Popen вызывается с неверными аргументами.

check_call() и check_output() поднимут исключение CalledProcessError, если вызываемый процесс возвращает ненулевой код возврата.

Все функции и методы, принимающие параметр timeout, такие как run() и Popen.communicate(), поднимут исключение TimeoutExpired, если таймаут истечет до завершения процесса.

Все исключения, определённые в этом модуле, наследуются от SubprocessError.

Добавлено в версии 3.3: Базовый класс SubprocessError был добавлен.

Объекты Popen

Экземпляры класса Popen имеют следующие методы:

Popen.poll(): Проверить, завершился ли дочерний процесс. Установить и вернуть атрибут returncode. В противном случае, возвращает None.

Popen.wait(timeout=None)

Подождать завершения дочернего процесса. Установить и вернуть атрибут returncode.

Если процесс не завершится через timeout секунд, будет вызвано исключение TimeoutExpired. Безопасно перехватывать это исключение и повторно пытаться подождать.

Примечание

Возможна блокировка при использовании stdout=PIPE или stderr=PIPE и если дочерний процесс генерирует достаточный объём данных в канал, который блокирует ожидание, пока буфер канала ОС не примет больше данных. При использовании каналов используйте Popen.communicate(), чтобы избежать этого.

Примечание

Если параметр timeout не None, то (на POSIX) функция реализована с помощью цикла busy-wait (неостанавливающий вызов и короткие паузы). Для асинхронного ожидания используйте модуль asyncio: см. asyncio.create_subprocess_exec.

Изменено в версии 3.3: Добавлен параметр timeout.

Popen.communicate(input=None, timeout=None)

Взаимодействие с процессом: отправка данных в stdin. Чтение данных из stdout и stderr до достижения конца файла. Ожидание завершения процесса и установка атрибута returncode. Необязательный аргумент input должен содержать данные, которые нужно отправить дочернему процессу, или None, если данные не нужно отправлять. Если потоки были открыты в текстовом режиме, input должен быть строкой. В противном случае — байтами.

communicate() возвращает кортеж (stdout_data, stderr_data). Данные будут строками, если потоки были открыты в текстовом режиме; иначе — байтами.

Обратите внимание, что если вам нужно отправить данные в stdin процесса, вам нужно создать объект Popen с stdin=PIPE. Аналогично, чтобы получить что-то кроме None в кортеже результата, вам также нужно указать stdout=PIPE и/или stderr=PIPE.

Если процесс не завершится через timeout секунд, будет вызвано исключение TimeoutExpired. Перехват этого исключения и повторная попытка взаимодействия не приведут к потере выходных данных.

Дочерний процесс не убивается при истечении таймаута, поэтому для корректного завершения приложение должно убить дочерний процесс и завершить взаимодействие:

proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()

Примечание

Считываемые данные буферизуются в памяти, поэтому не используйте этот метод, если размер данных большой или неограничен.

Изменено в версии 3.3: Добавлен параметр timeout.

Popen.send_signal(signal)

Отправляет сигнал signal дочернему процессу.

Не делает ничего, если процесс завершился.

Примечание

В Windows SIGTERM является алиасом для terminate(). CTRL_C_EVENT и CTRL_BREAK_EVENT могут быть отправлены процессам, запущенным с параметром creationflags, включающим CREATE_NEW_PROCESS_GROUP.

Popen.terminate(): Останавливает дочерний процесс. В POSIX операционных системах метод отправляет SIGTERM дочернему процессу. В Windows вызывается функция Win32 API TerminateProcess() для остановки дочернего процесса.

Popen.kill(): Убивает дочерний процесс. В POSIX операционных системах функция отправляет SIGKILL дочернему процессу. В Windows kill() является алиасом для terminate().

Класс также устанавливает следующие атрибуты для доступа. Их переопределение не поддерживается:

Popen.args: Аргумент args, как он был передан в Popen — последовательность аргументов программы или же единственная строка.

Введено в версии 3.3.

Popen.stdin: Если аргумент stdin был PIPE, этот атрибут — объект потока для записи, возвращаемый функцией open(). Если были указаны аргументы encoding или errors, или аргумент text или universal_newlines был True, поток является текстовым, в противном случае — байтовым. Если аргумент stdin не был PIPE, этот атрибут равен None.

Popen.stdout: Если аргумент stdout был PIPE, этот атрибут — объект потока для чтения, возвращаемый функцией open(). Чтение из потока предоставляет выходные данные дочернего процесса. Если были указаны аргументы encoding или errors, или аргумент text или universal_newlines был True, поток является текстовым, в противном случае — байтовым. Если аргумент stdout не был PIPE, этот атрибут равен None.

Popen.stderr: Если аргумент stderr был PIPE, этот атрибут — объект потока для чтения, возвращаемый функцией open(). Чтение из потока предоставляет выходные данные об ошибках дочернего процесса. Если были указаны аргументы encoding или errors, или аргумент text или universal_newlines был True, поток является текстовым, в противном случае — байтовым. Если аргумент stderr не был PIPE, этот атрибут равен None.

Предупреждение

Используйте communicate(), а не .stdin.write, .stdout.read или .stderr.read, чтобы избежать блокировок из-за заполнения буферов ОС и блокирования дочернего процесса.

Popen.pid

Идентификатор процесса дочернего процесса.

Обратите внимание, что если вы установили аргумент shell в True, это идентификатор процесса созданной оболочки.

Popen.returncode

Код возврата дочернего процесса. Изначально None, returncode устанавливается методом poll(), wait() или communicate(), если они обнаруживают завершение процесса.

Значение None указывает, что процесс ещё не завершился на момент последнего вызова метода.

Отрицательное значение -N указывает, что дочерний процесс был завершен сигналом N (только POSIX).

END_OF_DOCUMENT_MARKER

Windows Popen Helpers

Класс STARTUPINFO и следующие константы доступны только на Windows.

class subprocess.STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)

Частичная поддержка структуры Windows STARTUPINFO используется для создания объекта Popen. Следующие атрибуты можно установить, передав их в качестве ключевых аргументов.

Изменено в версии 3.7: Добавлена поддержка ключевых аргументов.

dwFlags

Поле бит, определяющее, используются ли определённые атрибуты STARTUPINFO при создании окна процесса.

si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW

hStdInput: Если dwFlags задаёт STARTF_USESTDHANDLES, этот атрибут — дескриптор стандартного ввода для процесса. Если STARTF_USESTDHANDLES не задан, по умолчанию для стандартного ввода используется буфер клавиатуры.

hStdOutput: Если dwFlags задаёт STARTF_USESTDHANDLES, этот атрибут — дескриптор стандартного вывода для процесса. В противном случае этот атрибут игнорируется, и по умолчанию для стандартного вывода используется буфер окна консоли.

hStdError: Если dwFlags задаёт STARTF_USESTDHANDLES, этот атрибут — дескриптор стандартной ошибки для процесса. В противном случае этот атрибут игнорируется, и по умолчанию для стандартной ошибки используется буфер окна консоли.

wShowWindow

Если dwFlags задаёт STARTF_USESHOWWINDOW, этот атрибут может принимать любые значения, которые могут быть указаны в параметре nCmdShow для функции ShowWindow, за исключением SW_SHOWDEFAULT. В противном случае этот атрибут игнорируется.

SW_HIDE предоставляется для этого атрибута. Он используется, когда функция Popen вызывается с параметром shell=True.

lpAttributeList

Словарь дополнительных атрибутов для создания процесса, как указано в STARTUPINFOEX, см. UpdateProcThreadAttribute.

Поддерживаемые атрибуты:

handle_list

Последовательность дескрипторов, которые будут унаследованы. close_fds должно быть True, если список не пустой.

Дескрипторы должны быть временно сделаны наследуемыми с помощью функции os.set_handle_inheritable() при передаче в конструктор Popen, иначе будет возбуждено исключение OSError с кодом Windows ошибки ERROR_INVALID_PARAMETER (87).

Предупреждение

В многопоточном процессе следует проявлять осторожность, чтобы избежать утечки дескрипторов, помеченных как наследуемые, при сочетании этой функции с одновременными вызовами других функций создания процессов, наследующих все дескрипторы, таких как os.system(). Это также относится к перенаправлению стандартных дескрипторов, которое временно создаёт наследуемые дескрипторы.

Добавлена в версии 3.7.

Константы Windows

Модуль subprocess предоставляет следующие константы.

subprocess.STD_INPUT_HANDLE: Устройство стандартного ввода. Изначально это буфер ввода консоли, CONIN$.

subprocess.STD_OUTPUT_HANDLE: Устройство стандартного вывода. Изначально это активный буфер экрана консоли, CONOUT$.

subprocess.STD_ERROR_HANDLE: Устройство стандартной ошибки. Изначально это активный буфер экрана консоли, CONOUT$.

subprocess.SW_HIDE: Скрывает окно. Будет активировано другое окно.

subprocess.STARTF_USESTDHANDLES: Указывает, что атрибуты STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput и STARTUPINFO.hStdError содержат дополнительную информацию.

subprocess.STARTF_USESHOWWINDOW: Указывает, что атрибут STARTUPINFO.wShowWindow содержит дополнительную информацию.

subprocess.CREATE_NEW_CONSOLE: Новый процесс получает новую консоль вместо наследования консоли родительского процесса (по умолчанию).

subprocess.CREATE_NEW_PROCESS_GROUP

Параметр Popen для указания создания новой группы процессов. Этот флаг необходим для использования os.kill() для подпроцесса.

Этот флаг игнорируется, если указан CREATE_NEW_CONSOLE.

subprocess.ABOVE_NORMAL_PRIORITY_CLASS: Параметр Popen для указания того, что новый процесс будет иметь приоритет выше среднего.

Добавлена в версии 3.7.

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

Добавлена в версии 3.7.

subprocess.HIGH_PRIORITY_CLASS: Параметр Popen для указания того, что новый процесс будет иметь высокий приоритет.

Добавлена в версии 3.7.

subprocess.IDLE_PRIORITY_CLASS: Параметр Popen для указания того, что новый процесс будет иметь приоритет простоя (низший).

Добавлена в версии 3.7.

subprocess.NORMAL_PRIORITY_CLASS: Параметр Popen для указания того, что новый процесс будет иметь нормальный приоритет (по умолчанию).

Добавлена в версии 3.7.

subprocess.REALTIME_PRIORITY_CLASS: Параметр Popen для указания того, что новый процесс будет иметь приоритет реального времени. Вам почти никогда не следует использовать REALTIME_PRIORITY_CLASS, потому что это прерывает системные потоки, управляющие вводом с мыши, вводом с клавиатуры и сбросом данных на диск. Этот класс может быть подходящим для приложений, которые «общаются» непосредственно с оборудованием или выполняют кратковременные задачи, которые должны иметь ограниченные прерывания.

Добавлена в версии 3.7.

subprocess.CREATE_NO_WINDOW: Параметр Popen для указания того, что новый процесс не будет создавать окно.

Добавлена в версии 3.7.

subprocess.DETACHED_PROCESS: Параметр Popen для указания того, что новый процесс не будет наследовать консоль родительского процесса. Это значение нельзя использовать с CREATE_NEW_CONSOLE.

Добавлена в версии 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE: Параметр Popen для указания того, что новый процесс не наследует режим ошибок вызывающего процесса. Вместо этого новый процесс получает режим ошибок по умолчанию. Эта функция особенно полезна для многопоточных оболочек, которые работают с отключенными ошибками.

Добавлена в версии 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB: Параметр Popen для указания того, что новый процесс не связан с задачей.

Добавлена в версии 3.7.

Старые высокоуровневые API

До Python 3.5 эти три функции составляли высокоуровневый API для subprocess. Теперь вы можете использовать run() во многих случаях, но много существующего кода использует эти функции.

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Выполняет команду, описанную в args. Ожидает завершения команды и возвращает атрибут returncode.

Код, которому нужно захватить stdout или stderr, должен использовать run() вместо этого:

run(...).returncode

Чтобы подавить stdout или stderr, передайте значение DEVNULL.

Указанные выше аргументы — лишь некоторые из общих. Полная сигнатура функции такая же, как у конструктора Popen — эта функция передает все предоставленные аргументы, кроме timeout, непосредственно этому интерфейсу.

Примечание

Не используйте stdout=PIPE или stderr=PIPE с этой функцией. Поток-потомок будет заблокирован, если он сгенерирует достаточно вывода в канал, чтобы заполнить буфер канала ОС, так как каналы не читаются.

Изменено в версии 3.3: Добавлен timeout.

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Выполняет команду с аргументами. Ожидает завершения команды. Если код возврата был равен нулю, возвращается, в противном случае возбуждается CalledProcessError. Объект CalledProcessError будет содержать код возврата в атрибуте returncode. Если check_call() не смог запустить процесс, он распространит исключение, которое было возбуждено.

Код, которому нужно захватить stdout или stderr, должен использовать run() вместо этого:

run(..., check=True)

Чтобы подавить stdout или stderr, передайте значение DEVNULL.

Примечание

Изменено в версии 3.3: Добавлен timeout.

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=None, timeout=None, text=None, **other_popen_kwargs)

Выполняет команду с аргументами и возвращает её вывод.

Если код возврата был не нулевым, возбуждается CalledProcessError. Объект CalledProcessError будет содержать код возврата в атрибуте returncode и любой вывод в атрибуте output.

Это эквивалентно:

run(..., check=True, stdout=PIPE).stdout

Указанные выше аргументы — лишь некоторые из общих. Полная сигнатура функции в значительной степени аналогична сигнатуре run() — большинство аргументов передаются непосредственно в этот интерфейс. Существует одно отличие в API от поведения run(): передача input=None будет работать так же, как input=b'' (или input='', в зависимости от других аргументов), а не использовать стандартный входной файл родительского процесса.

По умолчанию эта функция возвращает данные в виде кодированных байтов. Фактическая кодировка выходных данных может зависеть от вызываемой команды, поэтому декодирование в текст часто требует обработки на уровне приложения.

Это поведение может быть переопределено путём установки text, encoding, errors или universal_newlines в True как описано в Часто используемые аргументы и run().

Чтобы также захватить стандартную ошибку в результате, используйте stderr=subprocess.STDOUT:

>>> subprocess.check_output(
...     "ls non_existent_file; exit 0",
...     stderr=subprocess.STDOUT,
...     shell=True)
'ls: non_existent_file: No such file or directory\n'

Введено в версии 3.1.

Изменено в версии 3.3: Добавлен timeout.

Изменено в версии 3.4: Добавлена поддержка ключевого аргумента input.

Изменено в версии 3.6: Добавлены encoding и errors. Смотрите run() для деталей.

Введено в версии 3.7: Добавлен text как более читаемый псевдоним для universal_newlines.

Замена устаревших функций модулем subprocess

В этом разделе «a заменяется на b» означает, что b может быть использовано в качестве замены для a.

Примечание

Все функции «a» в этом разделе молчаливо терпят неудачу (в большей или меньшей степени), если выполняемая программа не найдена; замены «b» генерируют исключение OSError вместо этого.

Кроме того, замены с использованием check_output() потерпят неудачу с исключением CalledProcessError, если запрошенная операция возвращает код ошибки, отличный от нуля. Вывод по-прежнему доступен как атрибут output поднятого исключения.

В следующих примерах предполагается, что соответствующие функции уже импортированы из модуля subprocess.

Замена подстановки командной оболочки /bin/sh

output=$(mycmd myarg)

становится:

output = check_output(["mycmd", "myarg"])

Замена конвейера оболочки

output=$(dmesg | grep hda)

становится:

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]

Вызов p1.stdout.close() после запуска p2 важен для того, чтобы p1 получил SIGPIPE, если p2 завершится до завершения p1.

В качестве альтернативы для надёжного ввода можно напрямую использовать собственное обеспечение конвейера оболочки:

output=$(dmesg | grep hda)

становится:

output = check_output("dmesg | grep hda", shell=True)

Замена `os.system()`

sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)

Примечания:

Вызов программы через оболочку обычно не требуется.
Значение возврата call() закодировано иначе, чем у os.system().
Функция os.system() игнорирует сигналы SIGINT и SIGQUIT во время выполнения команды, но вызывающий код должен сделать это отдельно при использовании модуля subprocess.

Более реалистичный пример:

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)

Замена семейства `os.spawn`

Пример P_NOWAIT:

pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid

Пример P_WAIT:

retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])

Пример вектора:

os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])

Пример среды:

os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})

Замена `os.popen()`, `os.popen2()`, `os.popen3()`

(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)

(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)

(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

Обработка кода возврата выполняется следующим образом:

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")

Замена функций из модуля `popen2`

Примечание

Если аргумент cmd для функций popen2 является строкой, команда выполняется через /bin/sh. Если это список, команда выполняется напрямую.

(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

popen2.Popen3 и popen2.Popen4 работают в основном как subprocess.Popen, за исключением:

Popen генерирует исключение, если выполнение завершается ошибкой.
Аргумент capturestderr заменяется на аргумент stderr.
stdin=PIPE и stdout=PIPE должны быть указаны.
popen2 закрывает все дескрипторы файлов по умолчанию, но вы должны указать close_fds=True с Popen, чтобы гарантировать это поведение на всех платформах или в прошлых версиях Python.

Устаревшие функции вызова оболочки

Этот модуль также предоставляет следующие устаревшие функции из модуля 2.x commands. Эти операции неявно вызывают системную оболочку, и для этих функций недействительны описанные выше гарантии безопасности и согласованности обработки исключений.

subprocess.getstatusoutput(cmd, *, encoding=None, errors=None)

Возвращает (exitcode, output) выполнения cmd в оболочке.

Выполняет строку cmd в оболочке с Popen.check_output() и возвращает кортеж 2-элементов (exitcode, output). encoding и errors используются для декодирования вывода; см. примечания к Часто используемые аргументы для получения дополнительных сведений.

Конец строки новой строки удаляется из вывода. Код выхода команды может быть интерпретирован как код возврата subprocess. Пример:

>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
(1, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
(127, 'sh: /bin/junk: not found')
>>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '')

Доступность: Unix, Windows.

Изменено в версии 3.3.4: Добавлена поддержка Windows.

Функция теперь возвращает (exitcode, output) вместо (status, output), как это было в Python 3.3.3 и ранее. exitcode имеет то же значение, что и returncode.

Добавлена в версии 3.11: Добавлены аргументы encoding и errors.

subprocess.getoutput(cmd, *, encoding=None, errors=None)

Возвращает вывод (stdout и stderr) выполнения cmd в оболочке.

Как getstatusoutput(), за исключением того, что код выхода игнорируется, а возвращаемое значение — строка, содержащая вывод команды. Пример:

>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'

Доступность: Unix, Windows.

Изменено в версии 3.3.4: Добавлена поддержка Windows

Добавлена в версии 3.11: Добавлены аргументы encoding и errors.

Примечания

Преобразование последовательности аргументов в строку в Windows

В Windows последовательность args преобразуется в строку, которую можно проанализировать с использованием следующих правил (которые соответствуют правилам, используемым MS C runtime):

Аргументы разделяются пробелами, которые являются либо пробелами, либо табуляцией.
Строка, окружённая двойными кавычками, интерпретируется как один аргумент независимо от содержащихся в ней пробелов. В аргументе может быть вложена строка в кавычках.
Двойная кавычка, предшествующая обратной косой чертой, интерпретируется как буквальная двойная кавычка.
Обратные косые черты интерпретируются буквально, если не предшествуют двойной кавычке.
Если обратные косые черты непосредственно предшествуют двойной кавычке, каждая пара обратных косых черт интерпретируется как буквальная обратная косая черта. Если число обратных косых черт нечётное, последняя обратная косая черта экранирует следующую двойную кавычку, как описано в правиле 3.

См. также

shlex: Модуль, предоставляющий функции для разбора и экранирования командных строк.

Отключение использования `vfork()` или `posix_spawn()`

В Linux, subprocess по умолчанию использует системный вызов vfork() внутри, когда это безопасно, а не fork(). Это значительно повышает производительность.

Если вы когда-нибудь столкнётесь с, предположительно, необычной ситуацией, где вам нужно предотвратить использование vfork() Python, вы можете установить атрибут subprocess._USE_VFORK в значение false.

subprocess._USE_VFORK = False  # See CPython issue gh-NNNNNN.

Установка этого значения не влияет на использование posix_spawn(), которое может использовать vfork() внутри своей реализации libc. Есть аналогичный атрибут subprocess._USE_POSIX_SPAWN, если вам нужно предотвратить использование этого.

subprocess._USE_POSIX_SPAWN = False  # See CPython issue gh-NNNNNN.

Безопасно установить эти значения в false в любой версии Python. Они не будут иметь эффекта в более старых версиях, когда не поддерживаются. Не предполагайте, что атрибуты доступны для чтения. Несмотря на их названия, истинное значение не указывает на то, что соответствующая функция будет использоваться, а только на то, что она может быть.

Пожалуйста, подавайте вопросы всякий раз, когда вам нужно использовать эти частные настройки с способом воспроизведения возникшей проблемы. Ссылайтесь на эту проблему в комментарии в своём коде.

Добавлена в версии 3.8: _USE_POSIX_SPAWN

Добавлена в версии 3.11: _USE_VFORK

© 2001–2023 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.11/library/subprocess.html

subprocess — Управление дочерними процессами

Использование модуля subprocess

Часто используемые аргументы

Конструктор Popen

Исключения

Рекомендации по безопасности

Объекты Popen

Windows Popen Helpers

Константы Windows

Старые высокоуровневые API

Замена устаревших функций модулем subprocess

Замена подстановки командной оболочки /bin/sh

Замена конвейера оболочки

Замена os.system()

Замена семейства os.spawn

Замена os.popen(), os.popen2(), os.popen3()

Замена функций из модуля popen2

Устаревшие функции вызова оболочки

Примечания

Преобразование последовательности аргументов в строку в Windows

Отключение использования vfork() или posix_spawn()

Замена `os.system()`

Замена семейства `os.spawn`

Замена `os.popen()`, `os.popen2()`, `os.popen3()`

Замена функций из модуля `popen2`

Отключение использования `vfork()` или `posix_spawn()`