`subprocess` — Subprocess-Verwaltung¶

Quellcode: Lib/subprocess.py

Das Modul subprocess ermöglicht das Erzeugen neuer Prozesse, die Verbindung zu deren Ein-/Ausgabe-/Fehler-Pipes und das Abrufen ihrer Rückgabecodes. Dieses Modul soll mehrere ältere Module und Funktionen ersetzen.

os.system
os.spawn*

Informationen darüber, wie das Modul subprocess diese Module und Funktionen ersetzen kann, finden Sie in den folgenden Abschnitten.

Siehe auch

PEP 324 – PEP zur Einreichung des subprocess-Moduls

Verfügbarkeit: nicht Android, nicht iOS, nicht WASI.

Dieses Modul wird auf mobilen Plattformen oder WebAssembly-Plattformen nicht unterstützt.

Verwendung des `subprocess`-Moduls¶

Der empfohlene Ansatz zur Invokation von Subprozessen ist die Verwendung der Funktion run() für alle Anwendungsfälle, die sie abdecken kann. Für fortgeschrittenere Anwendungsfälle kann die zugrunde liegende Schnittstelle Popen direkt verwendet werden.

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)¶

Führt den durch args beschriebenen Befehl aus. Wartet, bis der Befehl abgeschlossen ist, und gibt dann eine Instanz von CompletedProcess zurück.

Die oben gezeigten Argumente sind lediglich die gebräuchlichsten und werden unten unter Häufig verwendete Argumente beschrieben (daher die Verwendung von Keyword-Only-Notation in der abgekürzten Signatur). Die vollständige Funktionssignatur ist weitgehend dieselbe wie die des Konstruktors von Popen – die meisten Argumente dieser Funktion werden an diese Schnittstelle weitergereicht. (timeout, input, check und capture_output nicht.)

Wenn capture_output true ist, werden stdout und stderr erfasst. Wenn es verwendet wird, wird das interne Popen-Objekt automatisch mit stdout und stderr auf PIPE gesetzt erstellt. Die Argumente stdout und stderr dürfen nicht gleichzeitig mit capture_output angegeben werden. Wenn Sie beide Streams erfassen und kombinieren möchten, setzen Sie stdout auf PIPE und stderr auf STDOUT, anstatt capture_output zu verwenden.

Ein timeout kann in Sekunden angegeben werden, er wird intern an Popen.communicate() weitergegeben. Wenn der Timeout abläuft, wird der Kindprozess beendet und darauf gewartet. Die Ausnahme TimeoutExpired wird erneut ausgelöst, nachdem der Kindprozess beendet wurde. Die anfängliche Prozesserstellung selbst kann auf vielen plattformspezifischen APIs nicht unterbrochen werden, daher ist keine Garantie dafür vorhanden, dass Sie eine Timeout-Ausnahme sehen, bevor die Prozesserstellung zumindest so lange gedauert hat.

Das Argument input wird an Popen.communicate() und damit an stdin des Subprozesses übergeben. Wenn es verwendet wird, muss es eine Byte-Sequenz sein, oder eine Zeichenkette, wenn encoding oder errors angegeben sind oder text true ist. Bei Verwendung wird das interne Popen-Objekt automatisch mit stdin auf PIPE gesetzt erstellt, und das Argument stdin darf nicht ebenfalls verwendet werden.

Wenn check true ist und der Prozess mit einem von Null verschiedenen Exit-Code beendet wird, wird eine Ausnahme CalledProcessError ausgelöst. Attribute dieser Ausnahme enthalten die Argumente, den Exit-Code und stdout und stderr, wenn sie erfasst wurden.

Wenn encoding oder errors angegeben sind oder text true ist, werden die Datei-Objekte für stdin, stdout und stderr im Textmodus geöffnet, wobei die angegebene encoding und errors oder die Standardwerte für io.TextIOWrapper verwendet werden. Das Argument universal_newlines ist äquivalent zu text und dient der Rückwärtskompatibilität. Standardmäßig werden Datei-Objekte im Binärmodus geöffnet.

Wenn env nicht None ist, muss es eine Abbildung sein, die die Umgebungsvariablen für den neuen Prozess definiert; diese werden anstelle des Standardverhaltens des Erbens der Umgebung des aktuellen Prozesses verwendet. Sie wird direkt an Popen übergeben. Diese Abbildung kann str zu str auf jeder Plattform oder bytes zu bytes auf POSIX-Plattformen sein, ähnlich wie os.environ oder os.environb.

Beispiele

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

Hinzugefügt in Version 3.5.

Geändert in Version 3.6: Parameter encoding und errors hinzugefügt

Geändert in Version 3.7: Parameter text hinzugefügt, als verständlichere Alias für universal_newlines. Parameter capture_output hinzugefügt.

Geändert in Version 3.12: Reihenfolge der Windows-Shell-Suche für shell=True geändert. Das aktuelle Verzeichnis und %PATH% werden durch %COMSPEC% und %SystemRoot%\System32\cmd.exe ersetzt. Infolgedessen funktioniert das Ablegen eines bösartigen Programms namens cmd.exe in einem aktuellen Verzeichnis nicht mehr.

class subprocess.CompletedProcess¶

Der Rückgabewert von run(), der einen abgeschlossenen Prozess darstellt.

args¶: Die Argumente, die zum Starten des Prozesses verwendet wurden. Dies kann eine Liste oder eine Zeichenkette sein.

returncode¶

Exit-Status des Kindprozesses. Normalerweise zeigt ein Exit-Status von 0 an, dass er erfolgreich ausgeführt wurde.

Ein negativer Wert -N zeigt an, dass der Kindprozess durch das Signal N beendet wurde (nur POSIX).

stdout¶

Erfasste stdout des Kindprozesses. Eine Byte-Sequenz oder eine Zeichenkette, wenn run() mit einer Kodierung, Fehlern oder text=True aufgerufen wurde. None, wenn stdout nicht erfasst wurde.

Wenn der Prozess mit stderr=subprocess.STDOUT ausgeführt wurde, werden stdout und stderr in diesem Attribut kombiniert und stderr ist None.

stderr¶: Erfasste stderr des Kindprozesses. Eine Byte-Sequenz oder eine Zeichenkette, wenn run() mit einer Kodierung, Fehlern oder text=True aufgerufen wurde. None, wenn stderr nicht erfasst wurde.

check_returncode()¶: Wenn returncode ungleich Null ist, löst eine CalledProcessError-Ausnahme aus.

Hinzugefügt in Version 3.5.

subprocess.DEVNULL¶: Spezialwert, der als Argument für stdin, stdout oder stderr für Popen verwendet werden kann und anzeigt, dass die spezielle Datei os.devnull verwendet wird.

Hinzugefügt in Version 3.3.

subprocess.PIPE¶: Spezialwert, der als Argument für stdin, stdout oder stderr für Popen verwendet werden kann und anzeigt, dass eine Pipe zum Standardstream geöffnet werden soll. Am nützlichsten mit Popen.communicate().

subprocess.STDOUT¶: Spezialwert, der als Argument für stderr für Popen verwendet werden kann und anzeigt, dass Standard-Fehler in dasselbe Handle wie Standard-Ausgabe geleitet werden sollen.

exception subprocess.SubprocessError¶: Basisklasse für alle anderen Ausnahmen aus diesem Modul.

Hinzugefügt in Version 3.3.

exception subprocess.TimeoutExpired¶

Unterklasse von SubprocessError, ausgelöst, wenn ein Timeout beim Warten auf einen Kindprozess abläuft.

cmd¶: Befehl, der zum Erzeugen des Kindprozesses verwendet wurde.

timeout¶: Timeout in Sekunden.

output¶: Ausgabe des Kindprozesses, wenn sie von run() oder check_output() erfasst wurde. Andernfalls None. Dies ist immer bytes, wenn jegliche Ausgabe erfasst wurde, unabhängig von der Einstellung text=True. Es kann None anstelle von b'' bleiben, wenn keine Ausgabe beobachtet wurde.

stdout¶: Alias für output, zur Symmetrie mit stderr.

stderr¶: Stderr-Ausgabe des Kindprozesses, wenn sie von run() erfasst wurde. Andernfalls None. Dies ist immer bytes, wenn stderr-Ausgabe erfasst wurde, unabhängig von der Einstellung text=True. Es kann None anstelle von b'' bleiben, wenn keine stderr-Ausgabe beobachtet wurde.

Hinzugefügt in Version 3.3.

Geändert in Version 3.5: Attribute stdout und stderr hinzugefügt

exception subprocess.CalledProcessError¶

Unterklasse von SubprocessError, ausgelöst, wenn ein von check_call(), check_output() oder run() (mit check=True) ausgeführter Prozess einen von Null verschiedenen Exit-Status zurückgibt.

returncode¶: Exit-Status des Kindprozesses. Wenn der Prozess aufgrund eines Signals beendet wurde, ist dies die negative Signalnummer.

cmd¶: Befehl, der zum Erzeugen des Kindprozesses verwendet wurde.

output¶: Ausgabe des Kindprozesses, wenn sie von run() oder check_output() erfasst wurde. Andernfalls None.

stdout¶: Alias für output, zur Symmetrie mit stderr.

stderr¶: Stderr-Ausgabe des Kindprozesses, wenn sie von run() erfasst wurde. Andernfalls None.

Geändert in Version 3.5: Attribute stdout und stderr hinzugefügt

Häufig verwendete Argumente¶

Um eine Vielzahl von Anwendungsfällen zu unterstützen, akzeptiert der Konstruktor von Popen (und die Komfortfunktionen) eine große Anzahl optionaler Argumente. Für die meisten typischen Anwendungsfälle können viele dieser Argumente sicher bei ihren Standardwerten belassen werden. Die am häufigsten benötigten Argumente sind:

args ist für alle Aufrufe erforderlich und sollte eine Zeichenkette oder eine Sequenz von Programmargumenten sein. Die Angabe einer Argumentsequenz wird generell bevorzugt, da sie es dem Modul ermöglicht, die notwendige Maskierung und Anführungszeichen für Argumente zu übernehmen (z. B. um Leerzeichen in Dateinamen zu erlauben). Wenn eine einzelne Zeichenkette übergeben wird, muss entweder shell auf True gesetzt sein (siehe unten) oder die Zeichenkette muss einfach den Namen des auszuführenden Programms ohne Angabe von Argumenten enthalten.

stdin, stdout und stderr geben die Standardeingabe-, Standardausgabe- und Standardfehlerausgabe-Dateihandles des ausgeführten Programms an. Gültige Werte sind None, PIPE, DEVNULL, ein vorhandener Dateideskriptor (eine positive Ganzzahl) und ein vorhandenes Datei-Objekt mit einem gültigen Dateideskriptor. Mit den Standardeinstellungen von None erfolgt keine Umleitung. PIPE zeigt an, dass eine neue Pipe zum Kindprozess erstellt werden soll. DEVNULL zeigt an, dass die spezielle Datei os.devnull verwendet wird. Zusätzlich kann stderr STDOUT sein, was anzeigt, dass die stderr-Daten vom Kindprozess in dasselbe Datei-Handle wie für stdout erfasst werden sollen.

Wenn encoding oder errors angegeben sind oder text (auch bekannt als universal_newlines) true ist, werden die Datei-Objekte stdin, stdout und stderr im Textmodus unter Verwendung der in der Funktion angegebenen encoding und errors oder der Standardwerte für io.TextIOWrapper geöffnet.

Für stdin werden Zeilenumbruchzeichen '\n' in der Eingabe in den Standardzeilenabstand os.linesep umgewandelt. Für stdout und stderr werden alle Zeilenumbrüche in der Ausgabe in '\n' umgewandelt. Weitere Informationen finden Sie in der Dokumentation der Klasse io.TextIOWrapper, wenn das Argument newline für deren Konstruktor None ist.

Wenn der Textmodus nicht verwendet wird, werden stdin, stdout und stderr als Binärströme geöffnet. Es wird keine Kodierungs- oder Zeilenumbruchkonvertierung durchgeführt.

Geändert in Version 3.6: Parameter encoding und errors hinzugefügt.

Geändert in Version 3.7: Parameter text als Alias für universal_newlines hinzugefügt.

Hinweis

Die Attribute newlines der Datei-Objekte Popen.stdin, Popen.stdout und Popen.stderr werden von der Methode Popen.communicate() nicht aktualisiert.

Wenn shell true ist, wird der angegebene Befehl über die Shell ausgeführt. Dies kann nützlich sein, wenn Sie Python hauptsächlich wegen der verbesserten Kontrollflussmöglichkeiten nutzen, die es im Vergleich zu den meisten System-Shells bietet, und dennoch bequemen Zugriff auf andere Shell-Funktionen wie Shell-Pipes, Dateinamen-Wildcards, Umgebungsvariablen-Erweiterung und die Erweiterung von ~ zum Home-Verzeichnis eines Benutzers wünschen. Beachten Sie jedoch, dass Python selbst Implementierungen vieler Shell-ähnlicher Funktionen bietet (insbesondere glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser() und shutil).

Geändert in Version 3.3: Wenn universal_newlines True ist, verwendet die Klasse die Kodierung locale.getpreferredencoding(False) anstelle von locale.getpreferredencoding(). Weitere Informationen zu dieser Änderung finden Sie in der Klasse io.TextIOWrapper.

Hinweis

Lesen Sie den Abschnitt Sicherheitsaspekte, bevor Sie shell=True verwenden.

Diese Optionen sowie alle anderen Optionen werden in der Dokumentation des Konstruktors Popen detaillierter beschrieben.

Popen Konstruktor¶

Die zugrunde liegende Prozess-Erstellung und -Verwaltung in diesem Modul wird von der Klasse Popen gehandhabt. Sie bietet viel Flexibilität, damit Entwickler die weniger üblichen Fälle behandeln können, die nicht von den Komfortfunktionen abgedeckt werden.

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)¶

Führt ein Kindprogramm in einem neuen Prozess aus. Unter POSIX verwendet die Klasse ein Verhalten ähnlich dem von os.execvpe(), um das Kindprogramm auszuführen. Unter Windows verwendet die Klasse die Windows-Funktion CreateProcess(). Die Argumente für Popen sind wie folgt.

args sollte eine Sequenz von Programmargumenten sein oder ein einzelner String oder ein Pfad-ähnliches Objekt. Standardmäßig ist das auszuführende Programm das erste Element in args, wenn args eine Sequenz ist. Wenn args ein String ist, ist die Interpretation plattformabhängig und wird unten beschrieben. Siehe die Argumente shell und executable für zusätzliche Unterschiede zum Standardverhalten. Sofern nicht anders angegeben, wird empfohlen, args als Sequenz zu übergeben.

Warnung

Für maximale Zuverlässigkeit verwenden Sie einen vollständig qualifizierten Pfad für die ausführbare Datei. Um einen nicht qualifizierten Namen auf der PATH-Umgebungsvariable zu suchen, verwenden Sie shutil.which(). Auf allen Plattformen ist die Übergabe von sys.executable der empfohlene Weg, um den aktuellen Python-Interpreter erneut zu starten und das Befehlszeilenformat -m zu verwenden, um ein installiertes Modul zu starten.

Die Auflösung des Pfads von executable (oder des ersten Elements von args) ist plattformabhängig. Für POSIX siehe os.execvpe(), und beachten Sie, dass bei der Auflösung oder Suche nach dem Pfad der ausführbaren Datei cwd das aktuelle Arbeitsverzeichnis überschreibt und env die PATH-Umgebungsvariable überschreiben kann. Für Windows siehe die Dokumentation der Parameter lpApplicationName und lpCommandLine der WinAPI-Funktion CreateProcess, und beachten Sie, dass bei der Auflösung oder Suche nach dem Pfad der ausführbaren Datei mit shell=False cwd das aktuelle Arbeitsverzeichnis nicht überschreibt und env die PATH-Umgebungsvariable nicht überschreiben kann. Die Verwendung eines vollständigen Pfads vermeidet all diese Variationen.

Ein Beispiel für die Übergabe einiger Argumente an ein externes Programm als Sequenz ist

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

Unter POSIX wird der String als Name oder Pfad des auszuführenden Programms interpretiert, wenn args ein String ist. Dies kann jedoch nur geschehen, wenn keine Argumente an das Programm übergeben werden.

Hinweis

Es ist möglicherweise nicht offensichtlich, wie ein Shell-Befehl in eine Sequenz von Argumenten zerlegt wird, insbesondere in komplexen Fällen. shlex.split() kann verdeutlichen, wie die korrekte Tokenisierung für args bestimmt wird.

>>> 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!

Beachten Sie insbesondere, dass Optionen (wie z.B. -input) und Argumente (wie z.B. eggs.txt), die durch Leerzeichen in der Shell getrennt sind, separate Listenelemente bilden, während Argumente, die in der Shell Anführungszeichen oder Backslash-Escapes erfordern (wie z.B. Dateinamen mit Leerzeichen oder der oben gezeigte echo-Befehl), einzelne Listenelemente sind.

Unter Windows wird args, wenn es sich um eine Sequenz handelt, in einer Weise in einen String konvertiert, die unter Konvertieren einer Argumentsequenz in einen String unter Windows beschrieben wird. Dies liegt daran, dass die zugrunde liegende Funktion CreateProcess() mit Strings arbeitet.

Geändert in Version 3.6: Der Parameter args akzeptiert ein Pfad-ähnliches Objekt, wenn shell False ist, und eine Sequenz, die Pfad-ähnliche Objekte enthält, unter POSIX.

Geändert in Version 3.8: Der Parameter args akzeptiert ein Pfad-ähnliches Objekt, wenn shell False ist, und eine Sequenz, die Bytes und Pfad-ähnliche Objekte enthält, unter Windows.

Das Argument shell (Standardwert ist False) gibt an, ob die Shell als auszuführendes Programm verwendet werden soll. Wenn shell True ist, wird empfohlen, args als String und nicht als Sequenz zu übergeben.

Unter POSIX mit shell=True ist die Standard-Shell /bin/sh. Wenn args ein String ist, gibt der String den über die Shell auszuführenden Befehl an. Das bedeutet, dass der String genau so formatiert sein muss, wie er an der Shell-Eingabeaufforderung eingegeben würde. Dies beinhaltet beispielsweise das Quoting oder Backslash-Escaping von Dateinamen mit Leerzeichen. Wenn args eine Sequenz ist, gibt das erste Element den Befehlsstring an, und alle zusätzlichen Elemente werden als zusätzliche Argumente für die Shell selbst behandelt. Das heißt, Popen führt das Äquivalent zu

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

Unter Windows mit shell=True gibt die Umgebungsvariable COMSPEC die Standard-Shell an. Die einzige Situation, in der Sie shell=True unter Windows angeben müssen, ist, wenn der auszuführende Befehl in die Shell integriert ist (z.B. dir oder copy). Sie benötigen shell=True nicht, um eine Batch-Datei oder eine konsolenbasierte ausführbare Datei auszuführen.

Hinweis

Lesen Sie den Abschnitt Sicherheitsaspekte, bevor Sie shell=True verwenden.

bufsize wird als entsprechendes Argument an die Funktion open() übergeben, wenn die Pipe-Dateiobjekte für stdin/stdout/stderr erstellt werden.

0 bedeutet unbuffered (Lesen und Schreiben sind ein Systemaufruf und können kurz zurückgegeben werden)
1 bedeutet zeilenweise buffered (nur verwendbar, wenn text=True oder universal_newlines=True ist)
Jeder andere positive Wert bedeutet, dass ein Puffer von ungefähr dieser Größe verwendet wird.
Ein negativer bufsize-Wert (der Standard) bedeutet, dass der Standardwert des Systems von io.DEFAULT_BUFFER_SIZE verwendet wird.

Geändert in Version 3.3.1: bufsize hat jetzt standardmäßig -1, um das Buffering standardmäßig zu aktivieren, um dem Verhalten zu entsprechen, das die meisten Codes erwarten. In Versionen vor Python 3.2.4 und 3.3.1 war der Standardwert fälschlicherweise 0, was unbuffered war und kurze Lesevorgänge erlaubte. Dies war unbeabsichtigt und entsprach nicht dem Verhalten von Python 2, wie es die meisten Codes erwarteten.

Das Argument executable gibt ein Ersatzprogramm an, das ausgeführt werden soll. Es wird sehr selten benötigt. Wenn shell=False ist, ersetzt executable das durch args angegebene Programm. Das ursprüngliche args wird jedoch immer noch an das Programm übergeben. Die meisten Programme behandeln das durch args angegebene Programm als Befehlsnamen, der dann vom tatsächlich ausgeführten Programm abweichen kann. Unter POSIX wird der Name args zum Anzeigenamen für die ausführbare Datei in Dienstprogrammen wie ps. Wenn shell=True ist, gibt unter POSIX das Argument executable eine Ersatz-Shell für die Standard-Shell /bin/sh an.

Geändert in Version 3.6: Der Parameter executable akzeptiert ein Pfad-ähnliches Objekt unter POSIX.

Geändert in Version 3.8: Der Parameter executable akzeptiert ein Bytes-Objekt und ein Pfad-ähnliches Objekt unter Windows.

Geändert in Version 3.12: Reihenfolge der Windows-Shell-Suche für shell=True geändert. Das aktuelle Verzeichnis und %PATH% werden durch %COMSPEC% und %SystemRoot%\System32\cmd.exe ersetzt. Infolgedessen funktioniert das Ablegen eines bösartigen Programms namens cmd.exe in einem aktuellen Verzeichnis nicht mehr.

stdin, stdout und stderr geben die Standardeingabe-, Standardausgabe- und Standardfehlerausgabe-Deskriptoren des ausgeführten Programms an. Gültige Werte sind None, PIPE, DEVNULL, ein vorhandener Dateideskriptor (eine positive Ganzzahl) und ein vorhandenes Datei-Objekt mit einem gültigen Dateideskriptor. Mit den Standardeinstellungen von None erfolgt keine Umleitung. PIPE bedeutet, dass eine neue Pipe zum Kind erstellt werden soll. DEVNULL bedeutet, dass die spezielle Datei os.devnull verwendet wird. Zusätzlich kann stderr STDOUT sein, was bedeutet, dass die stderr-Daten der Anwendungen in denselben Dateideskriptor wie für stdout erfasst werden sollen.

Wenn preexec_fn auf ein aufrufbares Objekt gesetzt ist, wird dieses Objekt im Kindprozess aufgerufen, kurz bevor das Kind ausgeführt wird. (Nur POSIX)

Warnung

Der Parameter preexec_fn ist NICHT SICHER in Gegenwart von Threads in Ihrer Anwendung zu verwenden. Der Kindprozess könnte blockieren, bevor exec aufgerufen wird.

Hinweis

Wenn Sie die Umgebung für das Kind ändern müssen, verwenden Sie den Parameter env anstelle der Durchführung in einem preexec_fn. Die Parameter start_new_session und process_group sollten den Code ersetzen, der preexec_fn zum Aufrufen von os.setsid() oder os.setpgid() im Kind verwendet.

Geändert in Version 3.8: Der Parameter preexec_fn wird in Subinterpretern nicht mehr unterstützt. Die Verwendung des Parameters in einem Subinterpreter löst eine RuntimeError aus. Diese neue Einschränkung kann Anwendungen betreffen, die in mod_wsgi, uWSGI und anderen eingebetteten Umgebungen bereitgestellt werden.

Wenn close_fds wahr ist, werden alle Dateideskriptoren außer 0, 1 und 2 vor der Ausführung des Kindprozesses geschlossen. Andernfalls, wenn close_fds falsch ist, befolgen Dateideskriptoren ihr erblichkeitsfähiges Flag, wie unter Vererbung von Dateideskriptoren beschrieben.

Unter Windows werden bei close_fds = True keine Handles vom Kindprozess geerbt, es sei denn, sie werden explizit in der handle_list des Elements STARTUPINFO.lpAttributeList übergeben oder durch Standard-Handle-Umleitung.

Geändert in Version 3.2: Der Standardwert für close_fds wurde von False auf das oben Beschriebene geändert.

Geändert in Version 3.7: Unter Windows wurde der Standardwert für close_fds von False auf True geändert, wenn die Standard-Handles umgeleitet werden. Es ist nun möglich, close_fds auf True zu setzen, wenn die Standard-Handles umgeleitet werden.

pass_fds ist eine optionale Sequenz von Dateideskriptoren, die zwischen Eltern- und Kindprozess offen gehalten werden sollen. Die Angabe eines pass_fds erzwingt, dass close_fds auf True gesetzt wird. (Nur POSIX)

Geändert in Version 3.2: Der Parameter pass_fds wurde hinzugefügt.

Wenn cwd nicht None ist, ändert die Funktion das Arbeitsverzeichnis in cwd, bevor das Kind ausgeführt wird. cwd kann ein String, Bytes oder ein Pfad-ähnliches Objekt sein. Unter POSIX sucht die Funktion nach executable (oder nach dem ersten Element in args) relativ zu cwd, wenn der Pfad der ausführbaren Datei ein relativer Pfad ist.

Geändert in Version 3.6: Der Parameter cwd akzeptiert ein Pfad-ähnliches Objekt unter POSIX.

Geändert in Version 3.7: Der Parameter cwd akzeptiert ein Pfad-ähnliches Objekt unter Windows.

Geändert in Version 3.8: Der Parameter cwd akzeptiert ein Bytes-Objekt unter Windows.

Wenn restore_signals wahr ist (Standardwert), werden alle Signale, die von Python auf SIG_IGN gesetzt wurden, im Kindprozess vor der Ausführung des exec auf SIG_DFL zurückgesetzt. Derzeit gehören dazu die Signale SIGPIPE, SIGXFZ und SIGXFSZ. (Nur POSIX)

Geändert in Version 3.2: restore_signals wurde hinzugefügt.

Wenn start_new_session wahr ist, wird der Systemaufruf setsid() im Kindprozess vor der Ausführung des Subprozesses ausgeführt.

Verfügbarkeit: POSIX

Geändert in Version 3.2: start_new_session wurde hinzugefügt.

Wenn process_group eine nicht-negative Ganzzahl ist, wird der Systemaufruf setpgid(0, value) im Kindprozess vor der Ausführung des Subprozesses ausgeführt.

Verfügbarkeit: POSIX

Geändert in Version 3.11: process_group wurde hinzugefügt.

Wenn group nicht None ist, wird der Systemaufruf setregid() im Kindprozess vor der Ausführung des Subprozesses ausgeführt. Wenn der angegebene Wert ein String ist, wird er über grp.getgrnam() nachgeschlagen und der Wert in gr_gid verwendet. Wenn der Wert eine Ganzzahl ist, wird er unverändert übergeben. (Nur POSIX)

Verfügbarkeit: POSIX

Hinzugefügt in Version 3.9.

Wenn extra_groups nicht None ist, wird der Systemaufruf setgroups() im Kindprozess vor der Ausführung des Subprozesses ausgeführt. Strings, die in extra_groups angegeben sind, werden über grp.getgrnam() nachgeschlagen und die Werte in gr_gid verwendet. Ganzzahlige Werte werden unverändert übergeben. (Nur POSIX)

Verfügbarkeit: POSIX

Hinzugefügt in Version 3.9.

Wenn user nicht None ist, wird der Systemaufruf setreuid() im Kindprozess vor der Ausführung des Subprozesses ausgeführt. Wenn der angegebene Wert ein String ist, wird er über pwd.getpwnam() nachgeschlagen und der Wert in pw_uid verwendet. Wenn der Wert eine Ganzzahl ist, wird er unverändert übergeben. (Nur POSIX)

Verfügbarkeit: POSIX

Hinzugefügt in Version 3.9.

Wenn umask nicht negativ ist, wird der Systemaufruf umask() im Kindprozess vor der Ausführung des Subprozesses ausgeführt.

Verfügbarkeit: POSIX

Hinzugefügt in Version 3.9.

Wenn env nicht None ist, muss es eine Zuordnung sein, die die Umgebungsvariablen für den neuen Prozess definiert; diese werden anstelle des Standardverhaltens des Ererbens der Umgebung des aktuellen Prozesses verwendet. Diese Zuordnung kann str zu str auf jeder Plattform oder bytes zu bytes auf POSIX-Plattformen sein, ähnlich wie os.environ oder os.environb.

Hinweis

Wenn angegeben, muss env alle Variablen enthalten, die für die Ausführung des Programms erforderlich sind. Unter Windows muss die angegebene env eine gültige %SystemRoot% enthalten, um eine Side-by-Side-Assembly ausführen zu können.

Wenn encoding oder errors angegeben sind oder text wahr ist, werden die Datei-Objekte stdin, stdout und stderr im Textmodus mit dem angegebenen encoding und errors geöffnet, wie oben unter Häufig verwendete Argumente beschrieben. Das Argument universal_newlines ist äquivalent zu text und dient der Abwärtskompatibilität. Standardmäßig werden Datei-Objekte im Binärmodus geöffnet.

Hinzugefügt in Version 3.6: encoding und errors wurden hinzugefügt.

Hinzugefügt in Version 3.7: text wurde als besser lesbare Abkürzung für universal_newlines hinzugefügt.

Wenn angegeben, ist startupinfo ein STARTUPINFO-Objekt, das an die zugrunde liegende Funktion CreateProcess übergeben wird.

Wenn angegeben, kann creationflags eines oder mehrere der folgenden Flags sein:

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 kann verwendet werden, um die Größe der Pipe zu ändern, wenn PIPE für stdin, stdout oder stderr verwendet wird. Die Größe der Pipe wird nur auf Plattformen geändert, die dies unterstützen (zum Zeitpunkt des Schreibens nur Linux). Andere Plattformen ignorieren diesen Parameter.

Geändert in Version 3.10: Der Parameter pipesize wurde hinzugefügt.

Popen-Objekte werden als Kontextmanager über die with-Anweisung unterstützt: beim Beenden werden die Standard-Dateideskriptoren geschlossen und der Prozess wird abgewartet.

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

Popen und die anderen Funktionen in diesem Modul, die es verwenden, lösen ein Auditing-Ereignis subprocess.Popen mit den Argumenten executable, args, cwd und env aus. Der Wert für args kann je nach Plattform ein einzelner String oder eine Liste von Strings sein.

Geändert in Version 3.2: Kontextmanager-Unterstützung hinzugefügt.

Geändert in Version 3.6: Der Popen-Destruktor gibt nun eine ResourceWarning-Warnung aus, wenn der Kindprozess noch läuft.

Geändert in Version 3.8: Popen kann in einigen Fällen os.posix_spawn() für bessere Leistung verwenden. Unter Windows Subsystem for Linux und QEMU User Emulation lösen Popen-Konstruktoren, die os.posix_spawn() verwenden, keine Ausnahmen mehr bei Fehlern wie fehlendem Programm aus, sondern der Kindprozess schlägt mit einem nicht-null returncode fehl.

Ausnahmen¶

Im Kindprozess, bevor das neue Programm mit der Ausführung begonnen hat, ausgelöste Ausnahmen werden im Elternprozess erneut ausgelöst.

Die häufigste Ausnahme ist OSError. Dies tritt beispielsweise auf, wenn versucht wird, eine nicht existierende Datei auszuführen. Anwendungen sollten auf OSError-Ausnahmen vorbereitet sein. Beachten Sie, dass unter shell=True OSError vom Kind nur ausgelöst wird, wenn die ausgewählte Shell selbst nicht gefunden wurde. Um festzustellen, ob die Shell die angeforderte Anwendung nicht finden konnte, muss der Rückgabecode oder die Ausgabe des Subprozesses überprüft werden.

Eine ValueError wird ausgelöst, wenn Popen mit ungültigen Argumenten aufgerufen wird.

check_call() und check_output() lösen eine CalledProcessError aus, wenn der aufgerufene Prozess einen nicht-null Rückgabecode zurückgibt.

Alle Funktionen und Methoden, die einen timeout-Parameter akzeptieren, wie z.B. run() und Popen.communicate(), lösen eine TimeoutExpired aus, wenn das Timeout abläuft, bevor der Prozess beendet wird.

In diesem Modul definierte Ausnahmen erben alle von SubprocessError.

Hinzugefügt in Version 3.3: Die Basisklasse SubprocessError wurde hinzugefügt.

Sicherheitsaspekte¶

Im Gegensatz zu einigen anderen Popen-Funktionen ruft diese Bibliothek nicht implizit eine System-Shell auf. Das bedeutet, dass alle Zeichen, einschließlich Shell-Metazeichen, sicher an Kindprozesse übergeben werden können. Wenn die Shell explizit über shell=True aufgerufen wird, liegt es in der Verantwortung der Anwendung sicherzustellen, dass alle Leerzeichen und Metazeichen ordnungsgemäß maskiert werden, um Shell-Injection-Schwachstellen zu vermeiden. Auf einigen Plattformen ist es möglich, shlex.quote() für dieses Maskieren zu verwenden.

Unter Windows können Batch-Dateien (*.bat oder *.cmd) vom Betriebssystem in einer System-Shell gestartet werden, unabhängig von den an diese Bibliothek übergebenen Argumenten. Dies könnte dazu führen, dass Argumente gemäß Shell-Regeln geparst werden, aber ohne jegliche Maskierung durch Python. Wenn Sie absichtlich eine Batch-Datei mit Argumenten aus nicht vertrauenswürdigen Quellen starten, sollten Sie shell=True übergeben, damit Python Sonderzeichen maskieren kann. Weitere Diskussionen finden Sie unter gh-114539.

Popen-Objekte¶

Instanzen der Popen-Klasse haben die folgenden Methoden

Popen.poll()¶: Prüft, ob der Kindprozess beendet wurde. Setzt und gibt das Attribut returncode zurück. Andernfalls wird None zurückgegeben.

Popen.wait(timeout=None)¶

Wartet auf die Beendigung des Kindprozesses. Setzt und gibt das Attribut returncode zurück.

Wenn der Prozess nach timeout Sekunden nicht beendet wird, wird eine TimeoutExpired-Ausnahme ausgelöst. Es ist sicher, diese Ausnahme abzufangen und den Wartevorgang erneut zu versuchen.

Hinweis

Dies führt zu einem Deadlock, wenn stdout=PIPE oder stderr=PIPE verwendet wird und der Kindprozess genügend Ausgabe in eine Pipe erzeugt, so dass er blockiert und auf die Annahme weiterer Daten durch den OS-Pipe-Puffer wartet. Verwenden Sie Popen.communicate(), wenn Sie Pipes verwenden, um dies zu vermeiden.

Hinweis

Wenn der Parameter timeout nicht None ist, dann wird die Funktion (unter POSIX) mithilfe einer Busy-Loop-Schleife implementiert (nicht-blockierender Aufruf und kurze Schlafpausen). Verwenden Sie das Modul asyncio für ein asynchrones Warten: siehe asyncio.create_subprocess_exec.

Geändert in Version 3.3: timeout wurde hinzugefügt.

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

Interagiert mit dem Prozess: Sendet Daten an stdin. Liest Daten von stdout und stderr, bis das Dateiende erreicht ist. Wartet auf die Beendigung des Prozesses und setzt das Attribut returncode. Das optionale Argument input sind die Daten, die an den Kindprozess gesendet werden sollen, oder None, wenn keine Daten gesendet werden sollen. Wenn Streams im Textmodus geöffnet wurden, muss input ein String sein. Andernfalls muss es Bytes sein.

communicate() gibt ein Tupel (stdout_data, stderr_data) zurück. Die Daten sind Strings, wenn die Streams im Textmodus geöffnet wurden; andernfalls Bytes.

Beachten Sie, dass Sie, wenn Sie Daten an stdin des Prozesses senden möchten, das Popen-Objekt mit stdin=PIPE erstellen müssen. Ebenso müssen Sie, um etwas anderes als None im Ergebnis-Tupel zu erhalten, auch stdout=PIPE und/oder stderr=PIPE angeben.

Wenn der Prozess nach timeout Sekunden nicht beendet wird, wird eine TimeoutExpired-Ausnahme ausgelöst. Das Abfangen dieser Ausnahme und das erneute Versuchen der Kommunikation gehen keine Ausgaben verloren.

Der Kindprozess wird nicht beendet, wenn das Timeout abläuft. Daher sollte eine gut funktionierende Anwendung den Kindprozess beenden und die Kommunikation abschließen, um eine ordnungsgemäße Bereinigung zu gewährleisten.

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

Hinweis

Die gelesenen Daten werden im Speicher gepuffert, daher sollten Sie diese Methode nicht verwenden, wenn die Datengröße groß oder unbegrenzt ist.

Geändert in Version 3.3: timeout wurde hinzugefügt.

Popen.send_signal(signal)¶

Sendet das Signal signal an den Kindprozess.

Tut nichts, wenn der Prozess abgeschlossen wurde.

Hinweis

Unter Windows ist SIGTERM ein Alias für terminate(). CTRL_C_EVENT und CTRL_BREAK_EVENT können an Prozesse gesendet werden, die mit dem Parameter creationflags gestartet wurden, der CREATE_NEW_PROCESS_GROUP enthält.

Popen.terminate()¶: Stoppt den Kindprozess. Unter POSIX-Betriebssystemen sendet die Methode SIGTERM an den Kindprozess. Unter Windows wird die Win32 API-Funktion TerminateProcess() aufgerufen, um den Kindprozess zu stoppen.

Popen.kill()¶: Beendet den Kindprozess. Unter POSIX-Betriebssystemen sendet die Funktion SIGKILL an den Kindprozess. Unter Windows ist kill() ein Alias für terminate().

Die folgenden Attribute werden ebenfalls von der Klasse für Sie zugänglich gesetzt. Das erneute Zuweisen zu neuen Werten wird nicht unterstützt

Popen.args¶: Das Argument args, wie es an Popen übergeben wurde – eine Sequenz von Programmargumenten oder eine einzelne Zeichenkette.

Hinzugefügt in Version 3.3.

Popen.stdin¶: Wenn das Argument stdin PIPE war, ist dieses Attribut ein beschreibbares Stream-Objekt, wie es von open() zurückgegeben wird. Wenn die Argumente encoding oder errors angegeben wurden oder das Argument text oder universal_newlines True war, ist der Stream ein Text-Stream, andernfalls ein Byte-Stream. Wenn das Argument stdin nicht PIPE war, ist dieses Attribut None.

Popen.stdout¶: Wenn das Argument stdout PIPE war, ist dieses Attribut ein lesbares Stream-Objekt, wie es von open() zurückgegeben wird. Das Lesen aus dem Stream liefert die Ausgabe des Kindprozesses. Wenn die Argumente encoding oder errors angegeben wurden oder das Argument text oder universal_newlines True war, ist der Stream ein Text-Stream, andernfalls ein Byte-Stream. Wenn das Argument stdout nicht PIPE war, ist dieses Attribut None.

Popen.stderr¶: Wenn das Argument stderr PIPE war, ist dieses Attribut ein lesbares Stream-Objekt, wie es von open() zurückgegeben wird. Das Lesen aus dem Stream liefert die Fehlerausgabe des Kindprozesses. Wenn die Argumente encoding oder errors angegeben wurden oder das Argument text oder universal_newlines True war, ist der Stream ein Text-Stream, andernfalls ein Byte-Stream. Wenn das Argument stderr nicht PIPE war, ist dieses Attribut None.

Warnung

Verwenden Sie communicate() anstelle von .stdin.write, .stdout.read oder .stderr.read, um Deadlocks zu vermeiden, die dadurch entstehen, dass einer der anderen OS-Pipe-Puffer überfüllt ist und den Kindprozess blockiert.

Popen.pid¶

Die Prozess-ID des Kindprozesses.

Beachten Sie, dass, wenn Sie das Argument shell auf True setzen, dies die Prozess-ID der gestarteten Shell ist.

Popen.returncode¶

Der Rückgabecode des Kindprozesses. Anfangs None, wird returncode durch einen Aufruf der Methoden poll(), wait() oder communicate() gesetzt, wenn diese erkennen, dass der Prozess beendet wurde.

Ein Wert von None zeigt an, dass der Prozess zum Zeitpunkt des letzten Methodenaufrufs noch nicht beendet war.

Ein negativer Wert -N zeigt an, dass der Kindprozess durch das Signal N beendet wurde (nur POSIX).

Windows Popen-Helfer¶

Die Klasse STARTUPINFO und die folgenden Konstanten sind nur unter Windows verfügbar.

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

Teilweise Unterstützung der Windows-Struktur STARTUPINFO wird für die Erstellung von Popen verwendet. Die folgenden Attribute können durch Übergabe als Keyword-only-Argumente gesetzt werden.

Geändert in Version 3.7: Unterstützung für Keyword-only-Argumente wurde hinzugefügt.

dwFlags¶

Ein Bitfeld, das bestimmt, ob bestimmte Attribute von STARTUPINFO verwendet werden, wenn der Prozess ein Fenster erstellt.

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

hStdInput¶: Wenn dwFlags STARTF_USESTDHANDLES angibt, ist dieses Attribut der Standard-Input-Handle für den Prozess. Wenn STARTF_USESTDHANDLES nicht angegeben ist, ist der Standard für den Standard-Input der Tastaturpuffer.

hStdOutput¶: Wenn dwFlags STARTF_USESTDHANDLES angibt, ist dieses Attribut der Standard-Output-Handle für den Prozess. Andernfalls wird dieses Attribut ignoriert und der Standard für die Standardausgabe ist der Puffer des Konsolenfensters.

hStdError¶: Wenn dwFlags STARTF_USESTDHANDLES angibt, ist dieses Attribut der Standard-Fehler-Handle für den Prozess. Andernfalls wird dieses Attribut ignoriert und der Standard für die Standardfehlerausgabe ist der Puffer des Konsolenfensters.

wShowWindow¶

Wenn dwFlags STARTF_USESHOWWINDOW angibt, kann dieses Attribut einen der Werte enthalten, die im Parameter nCmdShow für die Funktion ShowWindow angegeben werden können, mit Ausnahme von SW_SHOWDEFAULT. Andernfalls wird dieses Attribut ignoriert.

SW_HIDE wird für dieses Attribut bereitgestellt. Es wird verwendet, wenn Popen mit shell=True aufgerufen wird.

lpAttributeList¶

Ein Wörterbuch mit zusätzlichen Attributen für die Prozesserstellung, wie in STARTUPINFOEX angegeben, siehe UpdateProcThreadAttribute.

Unterstützte Attribute

handle_list

Sequenz von Handles, die vererbt werden. close_fds muss true sein, wenn die Sequenz nicht leer ist.

Die Handles müssen vor der Übergabe an den Popen-Konstruktor vorübergehend durch os.set_handle_inheritable() vererbbar gemacht werden, andernfalls wird eine OSError mit dem Windows-Fehler ERROR_INVALID_PARAMETER (87) ausgelöst.

Warnung

In einem Multithread-Prozess ist Vorsicht geboten, um das Auslaufen von Handles zu vermeiden, die als vererbbar markiert sind, wenn diese Funktion mit gleichzeitigen Aufrufen anderer Prozesserstellungsfunktionen kombiniert wird, die alle Handles erben, wie z. B. os.system(). Dies gilt auch für die Standard-Handle-Umleitung, die temporär vererbbare Handles erstellt.

Hinzugefügt in Version 3.7.

Windows-Konstanten¶

Das Modul subprocess stellt die folgenden Konstanten bereit.

subprocess.STD_INPUT_HANDLE¶: Das Standard-Eingabegerät. Anfangs ist dies der Konsolen-Eingabepuffer, CONIN$.

subprocess.STD_OUTPUT_HANDLE¶: Das Standard-Ausgabegerät. Anfangs ist dies der aktive Konsolenbildschirmpuffer, CONOUT$.

subprocess.STD_ERROR_HANDLE¶: Das Standard-Fehlergerät. Anfangs ist dies der aktive Konsolenbildschirmpuffer, CONOUT$.

subprocess.SW_HIDE¶: Verbirgt das Fenster. Ein anderes Fenster wird aktiviert.

subprocess.STARTF_USESTDHANDLES¶: Gibt an, dass die Attribute STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput und STARTUPINFO.hStdError zusätzliche Informationen enthalten.

subprocess.STARTF_USESHOWWINDOW¶: Gibt an, dass das Attribut STARTUPINFO.wShowWindow zusätzliche Informationen enthält.

subprocess.STARTF_FORCEONFEEDBACK¶: Ein Parameter für STARTUPINFO.dwFlags, der angibt, dass der Mauszeiger "Working in Background" angezeigt wird, während ein Prozess gestartet wird. Dies ist das Standardverhalten für GUI-Prozesse.

Hinzugefügt in Version 3.13.

subprocess.STARTF_FORCEOFFFEEDBACK¶: Ein Parameter für STARTUPINFO.dwFlags, der angibt, dass der Mauszeiger beim Starten eines Prozesses nicht geändert wird.

Hinzugefügt in Version 3.13.

subprocess.CREATE_NEW_CONSOLE¶: Der neue Prozess hat eine neue Konsole anstelle der Übernahme der Konsole des Elternprozesses (Standard).

subprocess.CREATE_NEW_PROCESS_GROUP¶

Ein Parameter für creationflags in Popen, der angibt, dass eine neue Prozessgruppe erstellt wird. Dieses Flag ist für die Verwendung von os.kill() auf dem Subprozess erforderlich.

Dieses Flag wird ignoriert, wenn CREATE_NEW_CONSOLE angegeben ist.

subprocess.ABOVE_NORMAL_PRIORITY_CLASS¶: Ein Parameter für creationflags in Popen, der angibt, dass ein neuer Prozess eine überdurchschnittliche Priorität haben wird.

Hinzugefügt in Version 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS¶: Ein Parameter für creationflags in Popen, der angibt, dass ein neuer Prozess eine unterdurchschnittliche Priorität haben wird.

Hinzugefügt in Version 3.7.

subprocess.HIGH_PRIORITY_CLASS¶: Ein Parameter für creationflags in Popen, der angibt, dass ein neuer Prozess eine hohe Priorität haben wird.

Hinzugefügt in Version 3.7.

subprocess.IDLE_PRIORITY_CLASS¶: Ein Parameter für creationflags in Popen, der angibt, dass ein neuer Prozess eine Leerlauf-Priorität (niedrigste) haben wird.

Hinzugefügt in Version 3.7.

subprocess.NORMAL_PRIORITY_CLASS¶: Ein Parameter für creationflags in Popen, der angibt, dass ein neuer Prozess eine normale Priorität haben wird. (Standard)

Hinzugefügt in Version 3.7.

subprocess.REALTIME_PRIORITY_CLASS¶: Ein Parameter für creationflags in Popen, der angibt, dass ein neuer Prozess Echtzeit-Priorität haben wird. Sie sollten REALTIME_PRIORITY_CLASS fast nie verwenden, da dies System-Threads unterbricht, die die Maus- und Tastatureingabe sowie die Hintergrund-Festplattenspülung verwalten. Diese Klasse kann für Anwendungen geeignet sein, die direkt mit Hardware "sprechen" oder kurze Aufgaben ausführen, die nur geringe Unterbrechungen erfahren sollen.

Hinzugefügt in Version 3.7.

subprocess.CREATE_NO_WINDOW¶: Ein Parameter für creationflags in Popen, der angibt, dass ein neuer Prozess kein Fenster erstellt.

Hinzugefügt in Version 3.7.

subprocess.DETACHED_PROCESS¶: Ein creationflags-Parameter für Popen, um anzugeben, dass ein neuer Prozess die Konsole seines Elternprozesses nicht erbt. Dieser Wert kann nicht mit CREATE_NEW_CONSOLE verwendet werden.

Hinzugefügt in Version 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE¶: Ein creationflags-Parameter für Popen, um anzugeben, dass ein neuer Prozess den Fehlerbehandlungsmodus des aufrufenden Prozesses nicht erbt. Stattdessen erhält der neue Prozess den Standard-Fehlerbehandlungsmodus. Diese Funktion ist besonders nützlich für multithreaded Shell-Anwendungen, die mit deaktivierten Hard Errors laufen.

Hinzugefügt in Version 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB¶: Ein creationflags-Parameter für Popen, um anzugeben, dass ein neuer Prozess nicht mit dem Job verknüpft ist.

Hinzugefügt in Version 3.7.

Ältere High-Level-API¶

Vor Python 3.5 umfassten diese drei Funktionen die High-Level-API für subprocess. Sie können jetzt run() in vielen Fällen verwenden, aber viel existierender Code ruft diese Funktionen auf.

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

Führt den durch args beschriebenen Befehl aus. Wartet, bis der Befehl abgeschlossen ist, und gibt dann das Attribut returncode zurück.

Code, der stdout oder stderr erfassen muss, sollte stattdessen run() verwenden.

run(...).returncode

Um stdout oder stderr zu unterdrücken, übergeben Sie den Wert DEVNULL.

Die oben gezeigten Argumente sind nur einige gängige. Die vollständige Funktionssignatur ist dieselbe wie die des Konstruktors Popen – diese Funktion übergibt alle bereitgestellten Argumente außer timeout direkt an diese Schnittstelle.

Hinweis

Verwenden Sie mit dieser Funktion nicht stdout=PIPE oder stderr=PIPE. Der Kindprozess blockiert, wenn er genügend Ausgabe an ein Pipe generiert, um den Puffer der Pipe des Betriebssystems zu füllen, da die Pipes nicht gelesen werden.

Geändert in Version 3.3: timeout wurde hinzugefügt.

Geändert in Version 3.12: Reihenfolge der Windows-Shell-Suche für shell=True geändert. Das aktuelle Verzeichnis und %PATH% werden durch %COMSPEC% und %SystemRoot%\System32\cmd.exe ersetzt. Infolgedessen funktioniert das Ablegen eines bösartigen Programms namens cmd.exe in einem aktuellen Verzeichnis nicht mehr.

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

Führt den Befehl mit Argumenten aus. Wartet, bis der Befehl abgeschlossen ist. Wenn der Rückgabecode null war, dann kehre zurück, andernfalls löse eine CalledProcessError aus. Das Objekt CalledProcessError hat den Rückgabecode im Attribut returncode. Wenn check_call() den Prozess nicht starten konnte, wird die ausgelöste Ausnahme weitergegeben.

Code, der stdout oder stderr erfassen muss, sollte stattdessen run() verwenden.

run(..., check=True)

Um stdout oder stderr zu unterdrücken, übergeben Sie den Wert DEVNULL.

Die oben gezeigten Argumente sind nur einige gängige. Die vollständige Funktionssignatur ist dieselbe wie die des Konstruktors Popen – diese Funktion übergibt alle bereitgestellten Argumente außer timeout direkt an diese Schnittstelle.

Hinweis

Verwenden Sie mit dieser Funktion nicht stdout=PIPE oder stderr=PIPE. Der Kindprozess blockiert, wenn er genügend Ausgabe an ein Pipe generiert, um den Puffer der Pipe des Betriebssystems zu füllen, da die Pipes nicht gelesen werden.

Geändert in Version 3.3: timeout wurde hinzugefügt.

Geändert in Version 3.12: Reihenfolge der Windows-Shell-Suche für shell=True geändert. Das aktuelle Verzeichnis und %PATH% werden durch %COMSPEC% und %SystemRoot%\System32\cmd.exe ersetzt. Infolgedessen funktioniert das Ablegen eines bösartigen Programms namens cmd.exe in einem aktuellen Verzeichnis nicht mehr.

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)¶

Führt den Befehl mit Argumenten aus und gibt seine Ausgabe zurück.

Wenn der Rückgabecode nicht null war, wird eine CalledProcessError ausgelöst. Das Objekt CalledProcessError hat den Rückgabecode im Attribut returncode und die Ausgabe im Attribut output.

Dies ist äquivalent zu

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

Die oben gezeigten Argumente sind nur einige gängige. Die vollständige Funktionssignatur ist weitgehend dieselbe wie die von run() – die meisten Argumente werden direkt an diese Schnittstelle weitergegeben. Eine Abweichung im API-Verhalten von run() besteht: Das Übergeben von input=None verhält sich gleich wie input=b'' (oder input='', abhängig von anderen Argumenten), anstatt den Standardeingabe-Dateihandle des Elternprozesses zu verwenden.

Standardmäßig gibt diese Funktion die Daten als kodierte Bytes zurück. Die tatsächliche Kodierung der Ausgabedaten kann vom aufgerufenen Befehl abhängen, daher muss die Dekodierung in Text oft auf Anwendungsebene erfolgen.

Dieses Verhalten kann durch Setzen von text, encoding, errors oder universal_newlines auf True überschrieben werden, wie in Häufig verwendete Argumente und run() beschrieben.

Um auch Standardfehler in das Ergebnis zu erfassen, verwenden Sie 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'

Hinzugefügt in Version 3.1.

Geändert in Version 3.3: timeout wurde hinzugefügt.

Geändert in Version 3.4: Die Unterstützung für das Schlüsselwortargument input wurde hinzugefügt.

Geändert in Version 3.6: encoding und errors wurden hinzugefügt. Siehe run() für Details.

Hinzugefügt in Version 3.7: text wurde als besser lesbare Abkürzung für universal_newlines hinzugefügt.

Geändert in Version 3.12: Reihenfolge der Windows-Shell-Suche für shell=True geändert. Das aktuelle Verzeichnis und %PATH% werden durch %COMSPEC% und %SystemRoot%\System32\cmd.exe ersetzt. Infolgedessen funktioniert das Ablegen eines bösartigen Programms namens cmd.exe in einem aktuellen Verzeichnis nicht mehr.

Ersetzen älterer Funktionen durch das Modul `subprocess`¶

In diesem Abschnitt bedeutet "a wird zu b", dass b als Ersatz für a verwendet werden kann.

Hinweis

Alle "a"-Funktionen in diesem Abschnitt schlagen (mehr oder weniger) lautlos fehl, wenn das ausgeführte Programm nicht gefunden werden kann; die "b"-Entsprechungen lösen stattdessen OSError aus.

Darüber hinaus schlagen die Ersetzungen, die check_output() verwenden, mit einer CalledProcessError fehl, wenn der angeforderte Vorgang einen Rückgabecode ungleich null erzeugt. Die Ausgabe ist weiterhin als Attribut output der ausgelösten Ausnahme verfügbar.

In den folgenden Beispielen wird davon ausgegangen, dass die relevanten Funktionen bereits aus dem Modul subprocess importiert wurden.

Ersetzen von /bin/sh Shell-Befehlssubstitution¶

output=$(mycmd myarg)

wird zu

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

Ersetzen von Shell-Pipelines¶

output=$(dmesg | grep hda)

wird zu

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]

Der Aufruf p1.stdout.close() nach dem Start von p2 ist wichtig, damit p1 ein SIGPIPE erhält, falls p2 vor p1 beendet wird.

Alternativ kann für vertrauenswürdige Eingaben die Pipeline-Unterstützung der Shell selbst direkt verwendet werden

output=$(dmesg | grep hda)

wird zu

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

Ersetzen von `os.system()`¶

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

Hinweise

Das Aufrufen des Programms über die Shell ist normalerweise nicht erforderlich.
Der Rückgabewert von call() wird anders kodiert als der von os.system().
Die Funktion os.system() ignoriert SIGINT und SIGQUIT Signale, während der Befehl läuft, aber der Aufrufer muss dies separat tun, wenn er das Modul subprocess verwendet.

Ein realistischeres Beispiel würde so aussehen

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)

Ersetzen der `os.spawn`-Familie¶

P_NOWAIT Beispiel

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

P_WAIT Beispiel

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

Vektor-Beispiel

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

Umgebung-Beispiel

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

Ersetzen von `os.popen()`¶

Die Handhabung des Rückgabecodes übersetzt sich wie folgt

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")

Legacy Shell Invocation Functions¶

Dieses Modul stellt auch die folgenden Legacy-Funktionen aus dem 2.x commands-Modul zur Verfügung. Diese Operationen rufen implizit die System-Shell auf, und keine der oben genannten Garantien bezüglich Sicherheit und Konsistenz der Fehlerbehandlung gilt für diese Funktionen.

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

Gibt (exitcode, output) der Ausführung von cmd in einer Shell zurück.

Führt den String cmd in einer Shell mit check_output() aus und gibt ein 2-Tupel (exitcode, output) zurück. encoding und errors werden zum Dekodieren der Ausgabe verwendet; siehe die Hinweise zu Häufig verwendete Argumente für weitere Details.

Ein abschließender Zeilenumbruch wird von der Ausgabe gestrippt. Der Exit-Code für den Befehl kann als Rückgabecode von subprocess interpretiert werden. Beispiel

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

Verfügbarkeit: Unix, Windows.

Geändert in Version 3.3.4: Die Unterstützung für Windows wurde hinzugefügt.

Die Funktion gibt nun (exitcode, output) anstelle von (status, output) zurück, wie sie in Python 3.3.3 und früher der Fall war. exitcode hat denselben Wert wie returncode.

Geändert in Version 3.11: Die Parameter encoding und errors wurden hinzugefügt.

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

Gibt die Ausgabe (stdout und stderr) der Ausführung von cmd in einer Shell zurück.

Wie getstatusoutput(), nur dass der Exit-Code ignoriert wird und der Rückgabewert ein String ist, der die Ausgabe des Befehls enthält. Beispiel

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

Verfügbarkeit: Unix, Windows.

Geändert in Version 3.3.4: Windows-Unterstützung hinzugefügt

Geändert in Version 3.11: Die Parameter encoding und errors wurden hinzugefügt.

Hinweise¶

Timeout-Verhalten¶

Bei Verwendung des Parameters timeout in Funktionen wie run(), Popen.wait() oder Popen.communicate() sollten Benutzer die folgenden Verhaltensweisen beachten

Verzögerung bei der Prozesserstellung: Die anfängliche Prozesserstellung selbst kann auf vielen Plattform-APIs nicht unterbrochen werden. Das bedeutet, dass auch bei Angabe eines Timeouts keine Timeout-Ausnahme garantiert wird, bevor die Prozesserstellung abgeschlossen ist.
Extrem kleine Timeout-Werte: Das Festlegen sehr kleiner Timeout-Werte (z. B. einige Millisekunden) kann zu fast sofortigen TimeoutExpired-Ausnahmen führen, da die Prozesserstellung und die Systemplanung naturgemäß Zeit benötigen.

Konvertierung einer Argumentsequenz in einen String unter Windows¶

Unter Windows wird eine args-Sequenz in einen String konvertiert, der nach folgenden Regeln geparst werden kann (die den Regeln der MS C-Laufzeit entsprechen)

Argumente werden durch Leerzeichen begrenzt, bei denen es sich um ein Leerzeichen oder einen Tabulator handelt.
Ein in doppelte Anführungszeichen eingeschlossener String wird als einzelnes Argument interpretiert, unabhängig von den darin enthaltenen Leerzeichen. Ein in Anführungszeichen eingeschlossener String kann in ein Argument eingebettet werden.
Ein doppeltes Anführungszeichen, dem ein Backslash vorangestellt ist, wird als wörtliches doppeltes Anführungszeichen interpretiert.
Backslashes werden wörtlich interpretiert, es sei denn, sie stehen unmittelbar vor einem doppelten Anführungszeichen.
Wenn Backslashes einem doppelten Anführungszeichen unmittelbar vorangestellt sind, wird jedes Paar von Backslashes als wörtlicher Backslash interpretiert. Wenn die Anzahl der Backslashes ungerade ist, maskiert der letzte Backslash das nächste doppelte Anführungszeichen wie in Regel 3 beschrieben.

Siehe auch

shlex: Modul, das Funktionen zum Parsen und Escapen von Befehlszeilen bereitstellt.

Deaktivieren der Verwendung von `posix_spawn()`¶

Unter Linux verwendet subprocess intern den Systemaufruf vfork(), wenn dies sicher möglich ist, anstatt fork(). Dies verbessert die Leistung erheblich.

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

Es ist sicher, dies auf jeder Python-Version auf falsch zu setzen. Es hat keine Auswirkung auf ältere oder neuere Versionen, bei denen es nicht unterstützt wird. Gehen Sie nicht davon aus, dass das Attribut zum Lesen verfügbar ist. Trotz des Namens zeigt ein wahrer Wert nicht an, dass die entsprechende Funktion verwendet wird, sondern nur, dass sie verwendet werden könnte.

Bitte reichen Sie Probleme ein, wenn Sie diese privaten Knöpfe verwenden müssen, mit einer Möglichkeit, das aufgetretene Problem zu reproduzieren. Verlinken Sie von einem Kommentar in Ihrem Code auf dieses Problem.

Hinzugefügt in Version 3.8: _USE_POSIX_SPAWN

`subprocess` — Subprocess-Verwaltung¶

Verwendung des `subprocess`-Moduls¶

Häufig verwendete Argumente¶

Popen Konstruktor¶

Ausnahmen¶

Sicherheitsaspekte¶

Popen-Objekte¶

Windows Popen-Helfer¶

Windows-Konstanten¶

Ältere High-Level-API¶

Ersetzen älterer Funktionen durch das Modul `subprocess`¶

Ersetzen von /bin/sh Shell-Befehlssubstitution¶

Ersetzen von Shell-Pipelines¶

Ersetzen von `os.system()`¶

Ersetzen der `os.spawn`-Familie¶

Ersetzen von `os.popen()`¶

Legacy Shell Invocation Functions¶

Hinweise¶

Timeout-Verhalten¶

Konvertierung einer Argumentsequenz in einen String unter Windows¶

Deaktivieren der Verwendung von `posix_spawn()`¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

subprocess — Subprocess-Verwaltung¶

Verwendung des subprocess-Moduls¶

Häufig verwendete Argumente¶

Popen Konstruktor¶

Ausnahmen¶

Sicherheitsaspekte¶

Popen-Objekte¶

Windows Popen-Helfer¶

Windows-Konstanten¶

Ältere High-Level-API¶

Ersetzen älterer Funktionen durch das Modul subprocess¶

Ersetzen von /bin/sh Shell-Befehlssubstitution¶

Ersetzen von Shell-Pipelines¶

Ersetzen von os.system()¶

Ersetzen der os.spawn-Familie¶

Ersetzen von os.popen()¶

Legacy Shell Invocation Functions¶

Hinweise¶

Timeout-Verhalten¶

Konvertierung einer Argumentsequenz in einen String unter Windows¶

Deaktivieren der Verwendung von posix_spawn()¶

`subprocess` — Subprocess-Verwaltung¶

Verwendung des `subprocess`-Moduls¶

Ersetzen älterer Funktionen durch das Modul `subprocess`¶

Ersetzen von `os.system()`¶

Ersetzen der `os.spawn`-Familie¶

Ersetzen von `os.popen()`¶

Deaktivieren der Verwendung von `posix_spawn()`¶