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 и 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, файлы для stdin, stdout и stderr открываются в текстовом режиме с указанным 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.12: Изменён порядок поиска оболочки 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.

END_OF_DOCUMENT_MARKER

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 не были получены.

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

Изменён в версии 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 соответственно задают стандартный ввод, стандартный вывод и стандартную ошибку выполняемой программы. Допустимые значения — None, PIPE, DEVNULL, существующий дескриптор файла (положительное целое число) и существующий объект файла с допустимым дескриптором файла. При значениях по умолчанию для None, перенаправление не произойдёт. PIPE указывает на то, что должен быть создан новый канал для дочернего процесса. DEVNULL указывает, что будет использоваться специальный файл os.devnull. Кроме того, 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)

END_OF_DOCUMENT_MARKER

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

stdin, stdout и stderr соответственно задают стандартные входные, стандартные выходные и стандартные ошибки исполняемой программы файлы-дескрипторы. Допустимые значения — None, PIPE, DEVNULL, существующий дескриптор файла (положительное целое число) и существующий объект файла с действительным дескриптором файла. При стандартных настройках None, перенаправление не произойдёт. PIPE указывает на создание новой трубы с дочерним процессом. DEVNULL указывает на использование специального файла os.devnull. Кроме того, stderr может быть STDOUT, что указывает на захват данных stderr приложения в тот же дескриптор файла, что и 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 было изменено с False на True при перенаправлении стандартных дескрипторов. Теперь можно установить close_fds в значение True при перенаправлении стандартных дескрипторов.

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

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

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

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

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

Изменено в версии 3.8: Параметр cwd принимает объект типа bytes в 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 for 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) функция реализуется с помощью цикла с проверкой (неблокирующий вызов и короткие задержки). Используйте модуль 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

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

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

Popen.returncode

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

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

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

END_OF_DOCUMENT_MARKER

Справочные данные по Windows Popen

Класс 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.

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

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.

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

Примечание

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

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

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.

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

Замена устаревших функций модулем 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.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(), когда это безопасно. Это значительно улучшает производительность.

Если вы когда-либо столкнётесь с, предположительно, очень необычной ситуацией, где вам нужно запретить Python использовать vfork(), вы можете установить атрибут 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. Они не повлияют на более старые версии, если не поддерживаются. Не предполагайте, что атрибуты доступны для чтения. Несмотря на их названия, значение true не означает, что соответствующая функция будет использована, а только то, что она может быть.

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

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

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

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

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

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

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

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

Исключения

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

Объекты Popen

Справочные данные по Windows Popen

Константы 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()`