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

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

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

os.system
os.spawn*

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

См.также

PEP 324 – PEP предлагает модуль подпроцесса

Availability: это не Emscripten, это был не я.

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

Использование модуля 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 и stdin равны PIPE. Аргументы stdout и stderr могут не передаваться одновременно с capture_output. Если вы хотите захватить и объединить оба потока в один, установите для stdout значение PIPE, а для stderr значение STDOUT, вместо использования capture_output.

Тайм-аут может быть указан в секундах, он внутренне передается в 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 на любой платформе или байт в байт на платформах 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: Добавлены параметры кодировки и ошибок

Изменено в версии 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

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

Если вы запустили процесс с 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

Псевдоним для вывода, для симметрии с 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

Псевдоним для вывода, для симметрии с 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, если аргументом новой строки для его конструктора является None.

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

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

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

Примечание

Атрибут newlines объектов file 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 для получения дополнительной информации об этом изменении.

Примечание

Прочтите раздел Security Considerations перед использованием shell=True.

Эти параметры, наряду со всеми другими параметрами, более подробно описаны в документации конструктора 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 должен быть последовательностью аргументов программы, либо отдельной строкой, либо path-like object. По умолчанию программа для выполнения является первым элементом в args, если args является последовательностью. Если args является строкой, интерпретация зависит от платформы и описана ниже. Дополнительные отличия от поведения по умолчанию приведены в аргументах shell и executable. Если не указано иное, рекомендуется передавать args в виде последовательности.

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

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

Определение пути к исполняемому файлу (или первому элементу 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 принимает значение path-like object, если значение shell равно False, и последовательность, содержащую объекты, подобные пути, в POSIX.

Изменено в версии 3.8: параметр args принимает значение path-like object, если значение 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 для запуска пакетного файла или консольного исполняемого файла.

Примечание

Прочтите раздел Security Considerations перед использованием shell=True.

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

  • 0 означает небуферизованный (чтение и запись являются одним системным вызовом и могут возвращать короткие значения)

  • 1 означает, что строка буферизована (используется только в том случае, если text=True или universal_newlines=True)

  • любое другое положительное значение означает использование буфера примерно такого же размера

  • отрицательный размер буфера (значение по умолчанию) означает системное значение ввода-вывода по умолчанию.Будет использоваться значение 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 принимает значение path-like object в POSIX.

Изменено в версии 3.8: параметр executable принимает значение в байтах и path-like object в Windows.

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

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

Если для параметра 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 может быть строкой, байтами или path-like объектом. В POSIX функция ищет исполняемый файл (или первый элемент в args) относительно cwd, если путь к исполняемому файлу является относительным.

Изменено в версии 3.6: параметр cwd принимает значение path-like object в POSIX.

Изменено в версии 3.7: параметр cwd принимает значение path-like object в Windows.

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

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

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

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

Availability: POSIX

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

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

Availability: POSIX

Изменено в версии 3.11: была добавлена process_group.

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

Availability: POSIX

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

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

Availability: POSIX

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

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

Availability: POSIX

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

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

Availability: POSIX

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

Если значение env не равно None, то это должно быть сопоставление, которое определяет переменные среды для нового процесса; они используются вместо поведения по умолчанию при наследовании среды текущего процесса. Это сопоставление может быть str в str на любой платформе или байт в байт на платформах 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: были добавлены кодировка и ошибки.

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

Если задано, startupinfo будет объектом STARTUPINFO, который передается базовой функции CreateProcess.

Если задан параметр creationflags, это может быть один или несколько из следующих флагов:

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

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

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

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

Создает auditing event subprocess.Popen с аргументами executable, args, cwd, env.

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

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

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

Исключения

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

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

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

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

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

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

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

Соображения безопасности

В отличие от некоторых других функций popen, эта библиотека не будет неявно вызывать системную оболочку. Это означает, что все символы, включая метасимволы оболочки, могут быть безопасно переданы дочерним процессам. Если оболочка вызывается явно, через shell=True, приложение обязано обеспечить, чтобы все пробелы и метасимволы были заключены в соответствующие кавычки, чтобы избежать уязвимостей shell injection. В some platforms для этого экранирования можно использовать shlex.quote().

В Windows пакетные файлы (*.bat или *.cmd) могут запускаться операционной системой в системной оболочке независимо от аргументов, передаваемых этой библиотеке. Это может привести к тому, что аргументы будут обрабатываться в соответствии с правилами оболочки, но без какого-либо экранирования, добавляемого Python. Если вы намеренно запускаете пакетный файл с аргументами из ненадежных источников, рассмотрите возможность передачи shell=True, чтобы Python мог экранировать специальные символы. Смотрите gh-114539 для дополнительного обсуждения.

Всплывающие объекты

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

Popen.poll()

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

Popen.wait(timeout=None)

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

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

Примечание

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

Примечание

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

Изменено в версии 3.3: был добавлен тайм-аут.

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

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

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

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

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

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

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

Примечание

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

Изменено в версии 3.3: был добавлен тайм-аут.

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, то этот атрибут является доступным для чтения объектом stream, который возвращается с помощью open(). Чтение из потока обеспечивает вывод дочернего процесса. Если были указаны аргументы encoding или errors или аргумент text или universal_newlines был равен True, то поток является текстовым потоком, в противном случае это поток байтов. Если аргумент stdout не был PIPE, то этот атрибут равен None.

Popen.stderr

Если аргументом stderr было PIPE, то этот атрибут является доступным для чтения объектом stream, который возвращается с помощью 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).

Помощники по открытию окон

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

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

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

Изменено в версии 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.

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

список обработчиков

Последовательность дескрипторов, которые будут унаследованы. 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

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

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

subprocess.ABOVE_NORMAL_PRIORITY_CLASS

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

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

subprocess.BELOW_NORMAL_PRIORITY_CLASS

A Popen creationflags параметр, указывающий, что новый процесс будет иметь приоритет ниже среднего.

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

subprocess.HIGH_PRIORITY_CLASS

A Popen creationflags параметр, указывающий, что новый процесс будет иметь высокий приоритет.

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

subprocess.IDLE_PRIORITY_CLASS

A Popen creationflags параметр, указывающий, что новый процесс будет иметь самый низкий приоритет в режиме ожидания.

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

subprocess.NORMAL_PRIORITY_CLASS

A Popen creationflags параметр, указывающий, что новый процесс будет иметь обычный приоритет. (по умолчанию)

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

subprocess.REALTIME_PRIORITY_CLASS

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

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

subprocess.CREATE_NO_WINDOW

A Popen creationflags параметр, указывающий, что новый процесс не будет создавать окно.

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

subprocess.DETACHED_PROCESS

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

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

subprocess.CREATE_DEFAULT_ERROR_MODE

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

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

subprocess.CREATE_BREAKAWAY_FROM_JOB

Параметр Popen creationflags, указывающий, что новый процесс не связан с заданием.

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

Более старый высокоуровневый API

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

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

Запустите команду, описанную в args. Дождитесь завершения команды, затем верните атрибут returncode.

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

run(...).returncode

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

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

Примечание

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

Изменено в версии 3.3: был добавлен тайм-аут.

Изменено в версии 3.11.3: Изменен порядок поиска в командной строке 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() не удалось запустить процесс, он распространит возникшее исключение.

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

run(..., check=True)

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

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

Примечание

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

Изменено в версии 3.3: был добавлен тайм-аут.

Изменено в версии 3.11.3: Изменен порядок поиска в командной строке 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: был добавлен тайм-аут.

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

Изменено в версии 3.6: были добавлены кодировка и ошибки. Подробности смотрите в run().

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

Изменено в версии 3.11.3: Изменен порядок поиска в командной строке 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"])

Замена трубопровода shell

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.

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

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). кодировка и ошибки используются для декодирования выходных данных; более подробную информацию смотрите в примечаниях к Часто используемые аргументы.

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

>>> 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, '')

Availability: Unix, Windows.

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

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

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

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

Возвращает выходные данные (stdout и stderr) выполнения cmd в командной строке.

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

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

Availability: Unix, Windows.

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

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

Записи

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

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

  1. Аргументы разделяются пробелом, который является либо пробелом, либо символом табуляции.

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

  3. Двойная кавычка, перед которой стоит обратная косая черта, интерпретируется как буквальная двойная кавычка.

  4. Обратные косые черты интерпретируются буквально, если только они не стоят непосредственно перед двойными кавычками.

  5. Если обратные косые черты непосредственно предшествуют двойным кавычкам, каждая пара обратных косых черт интерпретируется как буквальная обратная косая черта. Если количество обратных косых черт нечетное, последняя обратная косая черта не попадает в следующую двойную кавычку, как описано в правиле 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

concurrent.futures — Запуск параллельных задач
sched — Планировщик событий
Вернуться на верх