`subprocess` — Hantering av underprocesser¶

Källkod: Lib/subprocess.py

Med modulen subprocess kan du starta nya processer, ansluta till deras input/output/error pipes och få deras returkoder. Denna modul är tänkt att ersätta flera äldre moduler och funktioner:

os.system
os.spawn*

Information om hur modulen subprocess kan användas för att ersätta dessa moduler och funktioner finns i följande avsnitt.

Se även

PEP 324 – PEP föreslår subprocessmodulen

Tillgänglighet: not Android, not iOS, not WASI.

Denna modul stöds inte på mobile platforms eller WebAssembly platforms.

Använda modulen `subprocess`¶

Det rekommenderade tillvägagångssättet för att anropa underprocesser är att använda funktionen run() för alla användningsfall som den kan hantera. För mer avancerade användningsfall kan det underliggande Popen-gränssnittet användas direkt.

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

Kör kommandot som beskrivs av args. Vänta på att kommandot ska slutföras och returnera sedan en CompletedProcess-instans.

De argument som visas ovan är bara de vanligaste, som beskrivs nedan i Ofta använda argument (därav användningen av notation med endast nyckelord i den förkortade signaturen). Den fullständiga funktionssignaturen är i stort sett densamma som för Popen-konstruktören - de flesta av argumenten till denna funktion skickas vidare till det gränssnittet. (timeout, input, check och capture_output är inte det)

Om capture_output är true, kommer stdout och stderr att fångas. När det används skapas det interna Popen-objektet automatiskt med stdout och stderr båda inställda på PIPE. Argumenten stdout och stderr får inte anges samtidigt som capture_output. Om du vill fånga och kombinera båda strömmarna till en, sätt stdout till PIPE och stderr till STDOUT, istället för att använda capture_output.

En timeout kan anges i sekunder, den skickas internt vidare till Popen.communicate(). Om tidsgränsen går ut kommer barnprocessen att dödas och vänta. Undantaget TimeoutExpired kommer att aktiveras igen efter att barnprocessen har avslutats. Själva skapandet av den initiala processen kan inte avbrytas på många plattforms-API:er, så det är inte säkert att du ser ett timeout-undantag förrän åtminstone efter den tid som skapandet av processen tar.

Argumentet input skickas till Popen.communicate() och därmed till underprocessens stdin. Om det används måste det vara en byte-sekvens, eller en sträng om encoding eller errors är specificerat eller text är true. När den används skapas automatiskt det interna Popen-objektet med stdin satt till PIPE, och argumentet stdin får inte heller användas.

Om check är sant, och processen avslutas med en utgångskod som inte är noll, kommer ett CalledProcessError undantag att skapas. Attributen för det undantaget innehåller argumenten, utgångskoden och stdout och stderr om de fångades upp.

Om encoding eller errors anges, eller text är true, öppnas filobjekten för stdin, stdout och stderr i textläge med hjälp av angiven encoding och errors eller io.TextIOWrapper standard. Argumentet universal_newlines är likvärdigt med text och tillhandahålls för bakåtkompatibilitet. Som standard öppnas filobjekt i binärt läge.

Om env inte är None måste det vara en mappning som definierar miljövariablerna för den nya processen; dessa används i stället för standardbeteendet att ärva den aktuella processens miljö. Den skickas direkt till Popen. Denna mappning kan vara str till str på alla plattformar eller bytes till bytes på POSIX-plattformar, ungefär som os.environ eller os.environb.

Exempel:

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

Tillagd i version 3.5.

Ändrad i version 3.6: Parametrarna encoding och errors har lagts till

Ändrad i version 3.7: Parametern text har lagts till som ett mer begripligt alias för universal_newlines. Parametern capture_output har lagts till.

Ändrad i version 3.12: Ändrad sökordning för Windows shell för shell=True. Den aktuella katalogen och %PATH% ersätts med %COMSPEC% och %SystemRoot%\System32\cmd.exe. Som ett resultat fungerar det inte längre att släppa ett skadligt program med namnet cmd.exe i en aktuell katalog.

class subprocess.CompletedProcess¶

Returvärdet från run(), som representerar en process som har avslutats.

args¶: De argument som används för att starta processen. Detta kan vara en lista eller en sträng.

returncode¶

Avslutningsstatus för den underordnade processen. Vanligtvis innebär en exitstatus på 0 att den kördes framgångsrikt.

Ett negativt värde -N anger att barnet avslutades med signal N (endast POSIX).

stdout¶

Fångad stdout från den underordnade processen. En bytessekvens, eller en sträng om run() anropades med en kodning, fel, eller text=True. None om stdout inte fångades.

Om du körde processen med stderr=subprocess.STDOUT, kommer stdout och stderr att kombineras i detta attribut, och stderr kommer att vara None.

stderr¶: Fångade stderr från barnprocessen. En bytessekvens, eller en sträng om run() anropades med en kodning, fel, eller text=True. None om stderr inte fångades.

check_returncode()¶: Om returncode inte är noll, skapa en CalledProcessError.

Tillagd i version 3.5.

subprocess.DEVNULL¶: Specialvärde som kan användas som argument stdin, stdout eller stderr till Popen och som anger att specialfilen os.devnull ska användas.

Tillagd i version 3.3.

subprocess.PIPE¶: Specialvärde som kan användas som stdin-, stdout- eller stderr-argument till Popen och som anger att en pipe till standardströmmen ska öppnas. Mest användbart med Popen.communicate().

subprocess.STDOUT¶: Specialvärde som kan användas som stderr-argument till Popen och som anger att standardfel ska gå till samma handtag som standardutdata.

exception subprocess.SubprocessError¶: Basklass för alla andra undantag från denna modul.

Tillagd i version 3.3.

exception subprocess.TimeoutExpired¶

Underklass till SubprocessError, som uppstår när en timeout löper ut i väntan på en underordnad process.

cmd¶: Kommando som användes för att starta barnprocessen.

timeout¶: Timeout i sekunder.

output¶: Utdata från barnprocessen om den fångades upp av run() eller check_output(). I annat fall, None. Detta är alltid bytes när någon utdata fångades oavsett inställningen text=True. Det kan förbli None istället för b'' när ingen utdata observerades.

stdout¶: Alias för utdata, för symmetri med stderr.

stderr¶: Stderr-utdata från barnprocessen om den fångades upp av run(). Annars, None. Detta är alltid bytes när stderr-utdata fångades upp oavsett inställningen text=True. Det kan förbli None istället för b'' när ingen stderr-utmatning observerades.

Tillagd i version 3.3.

Ändrad i version 3.5: attributen stdout och stderr har lagts till

exception subprocess.CalledProcessError¶

Underklass till SubprocessError, som uppstår när en process som körs av check_call(), check_output() eller run() (med check=True) returnerar en utgångsstatus som inte är noll.

returncode¶: Avslutningsstatus för den underordnade processen. Om processen avslutades på grund av en signal, kommer detta att vara det negativa signalnumret.

cmd¶: Kommando som användes för att starta barnprocessen.

output¶: Utdata från barnprocessen om den fångades upp av run() eller check_output(). I annat fall, None.

stdout¶: Alias för utdata, för symmetri med stderr.

stderr¶: Stderr-utdata från barnprocessen om den fångades upp av run(). I annat fall, None.

Ändrad i version 3.5: attributen stdout och stderr har lagts till

Ofta använda argument¶

För att stödja en mängd olika användningsfall accepterar Popen-konstruktören (och bekvämlighetsfunktionerna) ett stort antal valfria argument. För de flesta typiska användningsfall kan många av dessa argument lämnas med sina standardvärden. De argument som oftast behövs är:

args krävs för alla anrop och ska vara en sträng eller en sekvens av programargument. Att ange en sekvens av argument är i allmänhet att föredra, eftersom det gör att modulen kan ta hand om eventuell escaping och citering av argument (t.ex. för att tillåta mellanslag i filnamn). Om du skickar en enda sträng måste antingen shell vara True (se nedan) eller så måste strängen helt enkelt namnge det program som ska köras utan att ange några argument.

stdin, stdout och stderr anger det exekverade programmets standardinmatnings-, standardutmatnings- respektive standardfelsfilhandtag. Giltiga värden är None, PIPE, DEVNULL, en befintlig filbeskrivare (ett positivt heltal) och ett befintligt file object med en giltig filbeskrivare. Med standardinställningarna None sker ingen omdirigering. PIPE anger att en ny pipe till underordnade filer ska skapas. DEVNULL anger att specialfilen os.devnull ska användas. Dessutom kan stderr vara STDOUT, vilket indikerar att stderr-data från den underordnade processen ska samlas in i samma filhandtag som för stdout.

Om encoding eller errors anges, eller text (även känd som universal_newlines) är true, öppnas filobjekten stdin, stdout och stderr i textläge med hjälp av de encoding och errors som anges i anropet eller standardvärdena för io.TextIOWrapper.

För stdin konverteras radavslutningstecken '\n' i indata till standardradavskiljaren os.linesep. För stdout och stderr kommer alla radavslut i utdata att konverteras till '\n'. Mer information finns i dokumentationen för klassen io.TextIOWrapper när argumentet newline till dess konstruktör är None.

Om textläge inte används kommer stdin, stdout och stderr att öppnas som binära strömmar. Ingen kodning eller konvertering av radavslut utförs.

Ändrad i version 3.6: Parametrarna encoding och errors har lagts till.

Ändrad i version 3.7: Parametern text har lagts till som ett alias för universal_newlines.

Anteckning

Attributet newlines för filobjekten Popen.stdin, Popen.stdout och Popen.stderr uppdateras inte av metoden Popen.communicate().

Om shell är True kommer det angivna kommandot att utföras via skalet. Detta kan vara användbart om du använder Python främst för det förbättrade kontrollflöde det erbjuder jämfört med de flesta systemskal och fortfarande vill ha bekväm tillgång till andra skalfunktioner som shell pipes, filnamn wildcards, expansion av miljövariabler och expansion av ~ till en användares hemkatalog. Observera dock att Python själv erbjuder implementeringar av många shell-liknande funktioner (i synnerhet glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser() och shutil).

Ändrad i version 3.3: När universal_newlines är True använder klassen kodningen locale.getpreferredencoding(False) istället för locale.getpreferredencoding(). Se klassen io.TextIOWrapper för mer information om denna ändring.

Anteckning

Läs avsnittet Säkerhetsöverväganden innan du använder shell=True.

Dessa alternativ, tillsammans med alla andra alternativ, beskrivs mer i detalj i dokumentationen för Popen-konstruktören.

Popen Konstruktör¶

Den underliggande skapandet och hanteringen av processer i den här modulen hanteras av klassen Popen. Den erbjuder stor flexibilitet så att utvecklare kan hantera de mindre vanliga fall som inte täcks av bekvämlighetsfunktionerna.

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

Exekverar ett underordnat program i en ny process. På POSIX använder klassen os.execvpe()-liknande beteende för att exekvera det underordnade programmet. På Windows använder klassen Windows-funktionen CreateProcess(). Argumenten till Popen är följande.

args bör vara en sekvens av programargument eller en enskild sträng eller path-like object. Som standard är det program som ska köras det första objektet i args om args är en sekvens. Om args är en sträng är tolkningen plattformsberoende och beskrivs nedan. Se argumenten shell och executable för ytterligare skillnader från standardbeteendet. Om inget annat anges rekommenderas det att args skickas som en sekvens.

Varning

För maximal tillförlitlighet bör du använda en fullständigt kvalificerad sökväg för den körbara filen. För att söka efter ett okvalificerat namn på PATH, använd shutil.which(). På alla plattformar är det rekommenderade sättet att skicka sys.executable för att starta den aktuella Python-tolken igen och använda kommandoradsformatet -m för att starta en installerad modul.

Upplösning av sökvägen till executable (eller det första objektet i args) är plattformsberoende. För POSIX, se os.execvpe(), och notera att när sökvägen till den körbara filen ska lösas eller sökas, åsidosätter cwd den aktuella arbetskatalogen och env kan åsidosätta miljövariabeln PATH. För Windows, se dokumentationen för parametrarna lpApplicationName och lpCommandLine i WinAPI CreateProcess, och notera att när sökvägen till den körbara filen upplöses eller söks med shell=False, åsidosätter inte cwd den aktuella arbetskatalogen och env kan inte åsidosätta miljövariabeln PATH. Genom att använda en fullständig sökväg undviks alla dessa variationer.

Ett exempel på att skicka några argument till ett externt program som en sekvens är:

Popen(["/usr/bin/git","commit","-m","Fixar en bugg."])

Om args är en sträng på POSIX tolkas strängen som namnet på eller sökvägen till det program som ska köras. Detta kan dock bara göras om man inte skickar argument till programmet.

Anteckning

Det kanske inte är självklart hur ett skalkommando ska delas upp i en sekvens av argument, särskilt i komplexa fall. shlex.split() kan illustrera hur man bestämmer rätt tokenisering för 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!

Observera särskilt att alternativ (t.ex. -input) och argument (t.ex. eggs.txt) som separeras med blanksteg i skalet hamnar i separata listelement, medan argument som kräver citering eller backslash-escaping när de används i skalet (t.ex. filnamn som innehåller blanksteg eller kommandot echo som visas ovan) är enskilda listelement.

I Windows, om args är en sekvens, kommer den att konverteras till en sträng på ett sätt som beskrivs i Konvertera en argumentsekvens till en sträng i Windows. Detta beror på att den underliggande CreateProcess() arbetar med strängar.

Ändrad i version 3.6: args parametern accepterar en path-like object om shell är False och en sekvens som innehåller sökvägsliknande objekt på POSIX.

Ändrad i version 3.8: args parameter accepterar en path-like object om shell är False och en sekvens som innehåller byte och sökvägsliknande objekt på Windows.

Argumentet shell (som har False som standard) anger om skalet ska användas som det program som ska köras. Om shell är True rekommenderas att args skickas som en sträng i stället för som en sekvens.

På POSIX med shell=True är standardvärdet för skalet /bin/sh. Om args är en sträng anger strängen det kommando som ska köras via skalet. Detta innebär att strängen måste formateras exakt som den skulle ha formaterats när den skrivs in vid skalets prompt. Detta inkluderar t.ex. citering eller backslash-escaping av filnamn med mellanslag. Om args är en sekvens anger det första elementet kommandosträngen, och alla ytterligare element behandlas som ytterligare argument till själva skalet. Det vill säga, Popen gör motsvarande som:

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

I Windows med shell=True anger miljövariabeln COMSPEC standardskalet. Den enda gången du behöver ange shell=True i Windows är när kommandot du vill köra är inbyggt i skalet (t.ex. dir eller copy). Du behöver inte shell=True för att köra en batchfil eller en konsolbaserad körbar fil.

Anteckning

Läs avsnittet Säkerhetsöverväganden innan du använder shell=True.

bufsize kommer att anges som motsvarande argument till funktionen open() när du skapar pipe-filobjekten stdin/stdout/stderr:

0 betyder obuffrad (läsning och skrivning är ett systemanrop och kan returnera kort)
1 betyder radbuffrad (endast användbar om text=True eller universal_newlines=True)
alla andra positiva värden innebär att en buffert av ungefär den storleken används
negativ bufsize (standard) innebär att systemets standard io.DEFAULT_BUFFER_SIZE kommer att användas.

Ändrad i version 3.3.1: bufsize har nu standardvärdet -1 för att aktivera buffring som standard för att matcha det beteende som den mesta koden förväntar sig. I versioner före Python 3.2.4 och 3.3.1 var standardvärdet felaktigt 0, vilket var obuffrat och tillät korta läsningar. Detta var oavsiktligt och matchade inte beteendet i Python 2 som de flesta koder förväntade sig.

Argumentet executable anger ett ersättningsprogram som ska köras. Det behövs mycket sällan. När shell=False ersätter executable det program som ska köras och som anges av args. Den ursprungliga args skickas dock fortfarande till programmet. De flesta program behandlar det program som anges av args som kommandonamnet, vilket kan skilja sig från det program som faktiskt körs. På POSIX blir args-namnet visningsnamnet för den körbara filen i verktyg som ps. Om shell=True, på POSIX, anger argumentet executable ett ersättningsskal för standard /bin/sh.

Ändrad i version 3.6: Parametern executable accepterar en path-like object på POSIX.

Ändrad i version 3.8: Parametern executable accepterar en byte och path-like object på Windows.

Ändrad i version 3.12: Ändrad sökordning för Windows shell för shell=True. Den aktuella katalogen och %PATH% ersätts med %COMSPEC% och %SystemRoot%\System32\cmd.exe. Som ett resultat fungerar det inte längre att släppa ett skadligt program med namnet cmd.exe i en aktuell katalog.

stdin, stdout och stderr anger det exekverade programmets standardinmatnings-, standardutmatnings- respektive standardfelsfilhandtag. Giltiga värden är None, PIPE, DEVNULL, en befintlig filbeskrivare (ett positivt heltal) och ett befintligt file object med en giltig filbeskrivare. Med standardinställningarna None sker ingen omdirigering. PIPE anger att en ny pipe till underordnade filer ska skapas. DEVNULL anger att specialfilen os.devnull ska användas. Dessutom kan stderr vara STDOUT, vilket indikerar att stderr-data från applikationerna ska samlas in i samma filhandtag som för stdout.

Om preexec_fn är inställt på ett anropbart objekt kommer detta objekt att anropas i barnprocessen strax innan barnprocessen körs. (Endast POSIX)

Varning

Parametern preexec_fn är INTE SÄKER att använda om det finns trådar i programmet. Barnprocessen kan fastna i ett dödläge innan exec anropas.

Anteckning

Om du behöver ändra miljön för barnet använder du parametern env i stället för att göra det i en preexec_fn. Parametrarna start_new_session och process_group bör ersätta kod som använder preexec_fn för att anropa os.setsid() eller os.setpgid() i det underordnade programmet.

Ändrad i version 3.8: Parametern preexec_fn stöds inte längre i undertolkar. Användningen av parametern i en undertolk ger upphov till RuntimeError. Den nya begränsningen kan påverka program som distribueras i mod_wsgi, uWSGI och andra inbäddade miljöer.

Om close_fds är true kommer alla filbeskrivare utom 0, 1 och 2 att stängas innan barnprocessen körs. Annars, när close_fds är false, följer filbeskrivare sin ärftliga flagga enligt beskrivningen i Arv av filbeskrivare.

Om close_fds är true i Windows kommer inga handtag att ärvas av barnprocessen om de inte uttryckligen skickas i elementet handle_list i STARTUPINFO.lpAttributeList, eller genom standardomdirigering av handtag.

Ändrad i version 3.2: Standardvärdet för close_fds ändrades från False till det som beskrivs ovan.

Ändrad i version 3.7: I Windows ändrades standardvärdet för close_fds från False till True när standardhandtagen omdirigerades. Det är nu möjligt att ställa in close_fds till True när standardhandtagen omdirigeras.

pass_fds är en valfri sekvens av filbeskrivare som ska hållas öppna mellan förälder och barn. Om du tillhandahåller någon pass_fds tvingas close_fds att vara True. (Endast POSIX)

Ändrad i version 3.2: Parametern pass_fds har lagts till.

Om cwd inte är None ändrar funktionen arbetskatalogen till cwd innan den exekverar underobjektet. cwd kan vara en sträng, byte eller path-like-objekt. På POSIX letar funktionen efter executable (eller efter det första objektet i args) i förhållande till cwd om sökvägen till den exekverbara filen är en relativ sökväg.

Ändrad i version 3.6: cwd parametern accepterar en path-like object på POSIX.

Ändrad i version 3.7: Parametern cwd accepterar en path-like object på Windows.

Ändrad i version 3.8: cwd-parametern accepterar ett bytes-objekt i Windows.

Om restore_signals är true (standard) återställs alla signaler som Python har satt till SIG_IGN till SIG_DFL i barnprocessen före exekveringen. För närvarande inkluderar detta signalerna SIGPIPE, SIGXFZ och SIGXFSZ. (Endast POSIX)

Ändrad i version 3.2: restore_signals lades till.

Om start_new_session är true kommer systemanropet setsid() att göras i barnprocessen innan subprocessen körs.

Tillgänglighet: POSIX

Ändrad i version 3.2: start_new_session lades till.

Om process_group är ett icke-negativt heltal kommer systemanropet setpgid(0, value) att göras i barnprocessen innan subprocessen körs.

Tillgänglighet: POSIX

Ändrad i version 3.11: process_group har lagts till.

Om group inte är None kommer systemanropet setregid() att göras i barnprocessen innan subprocessen körs. Om det angivna värdet är en sträng, kommer det att sökas upp via grp.getgrnam() och värdet i gr_gid kommer att användas. Om värdet är ett heltal kommer det att skickas ordagrant. (endast POSIX)

Tillgänglighet: POSIX

Tillagd i version 3.9.

Om extra_groups inte är None, kommer systemanropet setgroups() att göras i barnprocessen innan subprocessen körs. Strängar som anges i extra_groups kommer att sökas upp via grp.getgrnam() och värdena i gr_gid kommer att användas. Heltalsvärden kommer att skickas ordagrant. (Endast POSIX)

Tillgänglighet: POSIX

Tillagd i version 3.9.

Om user inte är None, kommer systemanropet setreuid() att göras i barnprocessen innan subprocessen körs. Om det angivna värdet är en sträng, kommer det att sökas upp via pwd.getpwnam() och värdet i pw_uid kommer att användas. Om värdet är ett heltal kommer det att skickas ordagrant. (Endast POSIX)

Tillgänglighet: POSIX

Tillagd i version 3.9.

Om umask inte är negativ, kommer systemanropet umask() att göras i barnprocessen innan subprocessen körs.

Tillgänglighet: POSIX

Tillagd i version 3.9.

Om env inte är None måste det vara en mappning som definierar miljövariablerna för den nya processen; dessa används i stället för standardbeteendet att ärva den aktuella processens miljö. Denna mappning kan vara str till str på alla plattformar eller bytes till bytes på POSIX-plattformar, ungefär som os.environ eller os.environb.

Anteckning

Om env anges måste den innehålla alla variabler som krävs för att programmet ska kunna köras. För att kunna köra en side-by-side assembly i Windows måste den angivna env inkludera en giltig SystemRoot.

Om encoding eller errors anges, eller text är true, öppnas filobjekten stdin, stdout och stderr i textläge med angiven encoding och errors, enligt beskrivningen ovan i Ofta använda argument. Argumentet universal_newlines är likvärdigt med text och tillhandahålls för bakåtkompatibilitet. Som standard öppnas filobjekt i binärt läge.

Tillagd i version 3.6: kodning och fel har lagts till.

Tillagd i version 3.7: text lades till som ett mer läsbart alias för universal_newlines.

Om startupinfo anges kommer det att vara ett STARTUPINFO-objekt som skickas till den underliggande funktionen CreateProcess.

Om creationflags anges kan det vara en eller flera av följande flaggor:

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 kan användas för att ändra storleken på pipen när PIPE används för stdin, stdout eller stderr. Storleken på röret ändras endast på plattformar som stöder detta (endast Linux i skrivande stund). Andra plattformar ignorerar denna parameter.

Ändrad i version 3.10: Parametern pipesize har lagts till.

Popen-objekt stöds som kontexthanterare via with-satsen: vid avslutning stängs standardfilbeskrivare och processen inväntas.

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

Popen och de andra funktionerna i denna modul som använder den skapar en auditing event subprocess.Popen med argumenten executable, args, cwd och env. Värdet för args kan vara en enda sträng eller en lista med strängar, beroende på plattform.

Ändrad i version 3.2: Stöd för kontexthanterare har lagts till.

Ändrad i version 3.6: Popen-destruktorn avger nu en ResourceWarning-varning om barnprocessen fortfarande körs.

Ändrad i version 3.8: Popen kan använda os.posix_spawn() i vissa fall för bättre prestanda. I Windows Subsystem for Linux och QEMU User Emulation ger Popen-konstruktören som använder os.posix_spawn() inte längre upphov till ett undantag vid fel som att programmet saknas, men barnprocessen misslyckas med en returncode som inte är noll.

Undantag¶

Undantag som uppstår i den underordnade processen innan det nya programmet har börjat exekveras kommer att uppstå på nytt i den överordnade processen.

Det vanligaste undantaget är OSError. Detta inträffar t.ex. när man försöker exekvera en icke-existerande fil. Program bör förbereda sig för OSError-undantag. Observera att när shell=True, kommer OSError att utlösas av det underordnade programmet endast om det valda skalet inte hittades. För att avgöra om skalet misslyckades med att hitta den begärda applikationen är det nödvändigt att kontrollera returkoden eller utdata från subprocessen.

Ett ValueError kommer att uppstå om Popen anropas med ogiltiga argument.

check_call() och check_output() ger upphov till CalledProcessError om den anropade processen returnerar en returkod som inte är noll.

Alla funktioner och metoder som accepterar en timeout-parameter, t.ex. run() och Popen.communicate(), ger upphov till TimeoutExpired om timeouten löper ut innan processen avslutas.

Undantag som definieras i denna modul ärver alla från SubprocessError.

Tillagd i version 3.3: Basklassen SubprocessError lades till.

Säkerhetsöverväganden¶

Till skillnad från vissa andra popen-funktioner kommer detta bibliotek inte att implicit välja att anropa ett systemskal. Detta innebär att alla tecken, inklusive metatecken i skalet, kan skickas vidare till underordnade processer på ett säkert sätt. Om skalet anropas explicit, via shell=True, är det applikationens ansvar att se till att alla blanksteg och metatecken citeras på rätt sätt för att undvika shell injection-sårbarheter. På vissa plattformar är det möjligt att använda shlex.quote() för denna escaping.

På Windows kan batchfiler (*.bat eller *.cmd) startas av operativsystemet i ett systemskal oavsett vilka argument som skickas till detta bibliotek. Detta kan resultera i att argumenten tolkas enligt skalets regler, men utan någon escaping som Python lägger till. Om du avsiktligt startar en batchfil med argument från opålitliga källor, överväg att skicka shell=True för att tillåta Python att undkomma specialtecken. Se gh-114539 för ytterligare diskussion.

Popen Objekt¶

Instanser av klassen Popen har följande metoder:

Popen.poll()¶: Kontrollera om underordnad process har avslutats. Ställ in och returnera returncode attribut. Annars returneras None.

Popen.wait(timeout=None)¶

Vänta på att underordnad process avslutas. Ställ in och returnera returncode attribut.

Om processen inte har avslutats efter timeout sekunder, uppstår ett TimeoutExpired-undantag. Det är säkert att fånga upp detta undantag och försöka vänta igen.

Anteckning

Detta leder till dödläge när man använder stdout=PIPE eller stderr=PIPE och barnprocessen genererar tillräckligt med utdata till en pipe så att den blockeras i väntan på att OS-pipe-bufferten ska ta emot mer data. Använd Popen.communicate() när du använder pipes för att undvika detta.

Anteckning

När parametern timeout inte är None, implementeras funktionen (på POSIX) med hjälp av en busy loop (icke-blockerande anrop och korta viloperioder). Använd modulen asyncio för en asynkron väntan: se asyncio.create_subprocess_exec.

Ändrad i version 3.3: timeout har lagts till.

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

Interagera med processen: Skicka data till stdin. Läs data från stdout och stderr, tills slutet av filen nås. Vänta på att processen avslutas och ställ in attributet returncode. Det valfria argumentet input ska vara data som ska skickas till den underordnade processen, eller None, om inga data ska skickas till den underordnade processen. Om strömmarna öppnades i textläge måste input vara en sträng. Annars måste det vara bytes.

communicate() returnerar en tupel (stdout_data, stderr_data). Data kommer att vara strängar om strömmarna öppnades i textläge; annars bytes.

Observera att om du vill skicka data till processens stdin måste du skapa Popen-objektet med stdin=PIPE. På samma sätt måste du också ange stdout=PIPE och/eller stderr=PIPE för att få något annat än None i resultattupeln.

Om processen inte avslutas efter timeout sekunder, kommer ett TimeoutExpired undantag att uppstå. Om detta undantag fångas upp och kommunikationen försöker på nytt förloras inte någon utdata.

Barnprocessen dödas inte om timeouten går ut, så för att rensa upp ordentligt bör en väluppfostrad applikation döda barnprocessen och avsluta kommunikationen:

proc = underprocess.Popen(...)
försök:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()

Anteckning

De data som läses buffras i minnet, så använd inte den här metoden om datastorleken är stor eller obegränsad.

Ändrad i version 3.3: timeout har lagts till.

Popen.send_signal(signal)¶

Sänder signalen signal till barnet.

Gör ingenting om processen är klar.

Anteckning

I Windows är SIGTERM ett alias för terminate(). CTRL_C_EVENT och CTRL_BREAK_EVENT kan skickas till processer som startats med en creationflags-parameter som inkluderar CREATE_NEW_PROCESS_GROUP.

Popen.terminate()¶: Stoppar det underordnade programmet. På POSIX-operativsystem skickar metoden SIGTERM till den underordnade enheten. På Windows anropas Win32 API-funktionen TerminateProcess() för att stoppa den underordnade.

Popen.kill()¶: Dödar barnet. På POSIX-operativsystem skickar funktionen SIGKILL till barnet. På Windows är kill() ett alias för terminate().

Följande attribut ställs också in av klassen så att du kan komma åt dem. Att tilldela dem nya värden stöds inte:

Popen.args¶: Argumentet args som det skickades till Popen – en sekvens av programargument eller en enda sträng.

Tillagd i version 3.3.

Popen.stdin¶: Om stdin-argumentet var PIPE, är detta attribut ett skrivbart strömobjekt som returneras av open(). Om argumenten encoding eller errors specificerades eller om argumentet text eller universal_newlines var True, är strömmen en textström, annars är den en byte-ström. Om argumentet stdin inte var PIPE, är detta attribut None.

Popen.stdout¶: Om argumentet stdout var PIPE, är detta attribut ett läsbart strömobjekt som returneras av open(). Läsning från strömmen ger utdata från barnprocessen. Om argumenten encoding eller errors specificerades eller om argumentet text eller universal_newlines var True, är strömmen en textström, annars är den en byte-ström. Om argumentet stdout inte var PIPE, är detta attribut None.

Popen.stderr¶: Om argumentet stderr var PIPE, är detta attribut ett läsbart strömobjekt som returneras av open(). Läsning från strömmen ger felutmatning från underordnad process. Om argumenten encoding eller errors specificerades eller om argumentet text eller universal_newlines var True, är strömmen en textström, annars är den en byte-ström. Om argumentet stderr inte var PIPE, är detta attribut None.

Varning

Använd communicate() i stället för .stdin.write, .stdout.read eller .stderr.read för att undvika dödlägen på grund av att någon av de andra OS-pipebuffertarna fylls och blockerar barnprocessen.

Popen.pid¶

Process-ID för den underordnade processen.

Observera att om du anger argumentet shell till True, är detta process-ID för det skapade skalet.

Popen.returncode¶

Barnets returkod. Ursprungligen None, returncode` sätts av ett anrop till metoderna poll(), wait(), eller communicate() om de upptäcker att processen har avslutats.

Ett värde på None anger att processen ännu inte hade avslutats vid tidpunkten för det senaste metodanropet.

Ett negativt värde -N anger att barnet avslutades med signal N (endast POSIX).

Windows Popen Hjälpmedel¶

Klassen STARTUPINFO och följande konstanter är endast tillgängliga i Windows.

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

Delvis stöd för Windows STARTUPINFO-struktur används för skapande av Popen. Följande attribut kan ställas in genom att skicka dem som argument med endast nyckelord.

Ändrad i version 3.7: Stöd för argument med enbart nyckelord har lagts till.

dwFlags¶

Ett bitfält som avgör om vissa STARTUPINFO-attribut ska användas när processen skapar ett fönster.

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

hStdInput¶: Om dwFlags anger STARTF_USESTDHANDLES, är detta attribut processens standardinmatningshandtag. Om STARTF_USESTDHANDLES inte anges, är standardinmatningen tangentbordsbufferten.

hStdOutput¶: Om dwFlags anger STARTF_USESTDHANDLES, är detta attribut processens standardutdatahandtag. I annat fall ignoreras attributet och standardvärdet för standardutdata är konsolfönstrets buffert.

hStdError¶: Om dwFlags specificerar STARTF_USESTDHANDLES, är detta attribut processens standardfelhandtag. Annars ignoreras detta attribut och standardvärdet för standardfel är konsolfönstrets buffert.

wShowWindow¶

Om dwFlags anger STARTF_USESHOWWINDOW, kan detta attribut vara vilket som helst av de värden som kan anges i parametern nCmdShow för funktionen ShowWindow, utom SW_SHOWDEFAULT. I annat fall ignoreras detta attribut.

SW_HIDE tillhandahålls för detta attribut. Det används när Popen anropas med shell=True.

lpAttributeList¶

En ordlista med ytterligare attribut för skapande av processer som anges i STARTUPINFOEX, se UpdateProcThreadAttribute.

Attribut som stöds:

handtag_lista

Sekvens av handtag som kommer att ärvas. close_fds måste vara true om den inte är tom.

Handtagen måste tillfälligt göras ärftliga genom os.set_handle_inheritable() när de skickas till Popen-konstruktören, annars kommer OSError att uppstå med Windows-felet ERROR_INVALID_PARAMETER (87).

Varning

I en flertrådad process bör du vara försiktig så att du inte läcker handtag som är markerade som ärvbara när du kombinerar den här funktionen med samtidiga anrop till andra processskapande funktioner som ärver alla handtag, t.ex. os.system(). Detta gäller även för standardhandleomdirigering, som tillfälligt skapar ärftliga handtag.

Tillagd i version 3.7.

Windows-konstanter¶

Modulen subprocess innehåller följande konstanter.

subprocess.STD_INPUT_HANDLE¶: Standardinmatningsenheten. Ursprungligen är detta konsolens inmatningsbuffert, CONIN$.

subprocess.STD_OUTPUT_HANDLE¶: Standardutmatningsenheten. Initialt är detta den aktiva konsolskärmsbufferten, CONOUT$.

subprocess.STD_ERROR_HANDLE¶: Enheten för standardfel. Ursprungligen är detta den aktiva konsolskärmsbufferten, CONOUT$.

subprocess.SW_HIDE¶: Döljer fönstret. Ett annat fönster kommer att aktiveras.

subprocess.STARTF_USESTDHANDLES¶: Anger att attributen STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput och STARTUPINFO.hStdError innehåller ytterligare information.

subprocess.STARTF_USESHOWWINDOW¶: Anger att attributet STARTUPINFO.wShowWindow innehåller ytterligare information.

subprocess.STARTF_FORCEONFEEDBACK¶: En parameter i STARTUPINFO.dwFlags som anger att muspekaren Working in Background ska visas när en process startas. Detta är standardbeteendet för GUI-processer.

Tillagd i version 3.13.

subprocess.STARTF_FORCEOFFFEEDBACK¶: En STARTUPINFO.dwFlags-parameter för att ange att muspekaren inte ska ändras när en process startas.

Tillagd i version 3.13.

subprocess.CREATE_NEW_CONSOLE¶: Den nya processen har en ny konsol, istället för att ärva sin förälders konsol (standard).

subprocess.CREATE_NEW_PROCESS_GROUP¶

En Popen creationflags parameter för att ange att en ny processgrupp skall skapas. Denna flagga är nödvändig för att använda os.kill() på subprocessen.

Denna flagga ignoreras om CREATE_NEW_CONSOLE anges.

subprocess.ABOVE_NORMAL_PRIORITY_CLASS¶: En Popen creationflags parameter för att ange att en ny process skall ha en prioritet över genomsnittet.

Tillagd i version 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS¶: En Popen creationflags parameter för att ange att en ny process kommer att ha en prioritet under genomsnittet.

Tillagd i version 3.7.

subprocess.HIGH_PRIORITY_CLASS¶: En Popen creationflags parameter för att ange att en ny process skall ha hög prioritet.

Tillagd i version 3.7.

subprocess.IDLE_PRIORITY_CLASS¶: En Popen creationflags parameter för att ange att en ny process skall ha en idle (lägsta) prioritet.

Tillagd i version 3.7.

subprocess.NORMAL_PRIORITY_CLASS¶: En Popen creationflags parameter för att ange att en ny process skall ha normal prioritet. (standard)

Tillagd i version 3.7.

subprocess.REALTIME_PRIORITY_CLASS¶: En Popen creationflags parameter för att ange att en ny process skall ha realtidsprioritet. Du bör nästan aldrig använda REALTIME_PRIORITY_CLASS, eftersom detta avbryter systemtrådar som hanterar musinmatning, tangentbordsinmatning och diskspolning i bakgrunden. Den här klassen kan vara lämplig för program som ”pratar” direkt med maskinvara eller som utför korta uppgifter som bör ha begränsade avbrott.

Tillagd i version 3.7.

subprocess.CREATE_NO_WINDOW¶: En Popen creationflags parameter för att ange att en ny process inte kommer att skapa ett fönster.

Tillagd i version 3.7.

subprocess.DETACHED_PROCESS¶: En Popen creationflags-parameter för att ange att en ny process inte ska ärva sin förälders konsol. Detta värde kan inte användas med CREATE_NEW_CONSOLE.

Tillagd i version 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE¶: En Popen creationflags parameter för att ange att en ny process inte ärver den anropande processens felläge. Istället får den nya processen standardfelsläget. Denna funktion är särskilt användbar för flertrådiga skalprogram som körs med hårda fel inaktiverade.

Tillagd i version 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB¶: En Popen creationflags parameter för att ange att en ny process inte associeras med jobbet.

Tillagd i version 3.7.

Äldre API på hög nivå¶

Före Python 3.5 utgjorde dessa tre funktioner API:et på hög nivå för subprocess. Du kan nu använda run() i många fall, men massor av befintlig kod anropar dessa funktioner.

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

Kör kommandot som beskrivs av args. Vänta tills kommandot är klart och returnera sedan attributet returncode.

Kod som behöver fånga stdout eller stderr bör använda run() istället:

run(...).returncode

För att undertrycka stdout eller stderr, ange ett värde på DEVNULL.

De argument som visas ovan är bara några vanliga. Den fullständiga funktionssignaturen är densamma som för Popen-konstruktören - den här funktionen skickar alla medföljande argument utom timeout direkt till gränssnittet.

Anteckning

Använd inte stdout=PIPE eller stderr=PIPE med denna funktion. Barnprocessen blockeras om den genererar tillräckligt med utdata till en pipe för att fylla OS-pipe-bufferten eftersom pipes inte läses från.

Ändrad i version 3.3: timeout har lagts till.

Ändrad i version 3.12: Ändrad sökordning för Windows shell för shell=True. Den aktuella katalogen och %PATH% ersätts med %COMSPEC% och %SystemRoot%\System32\cmd.exe. Som ett resultat fungerar det inte längre att släppa ett skadligt program med namnet cmd.exe i en aktuell katalog.

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

Kör kommandot med argument. Vänta på att kommandot ska slutföras. Om returkoden var noll så returnera, annars skapa CalledProcessError. Objektet CalledProcessError kommer att ha returkoden i attributet returncode. Om check_call() inte kunde starta processen kommer det undantag som togs upp att spridas.

Kod som behöver fånga stdout eller stderr bör använda run() istället:

run(..., check=True)

För att undertrycka stdout eller stderr, ange ett värde på DEVNULL.

De argument som visas ovan är bara några vanliga. Den fullständiga funktionssignaturen är densamma som för Popen-konstruktören - den här funktionen skickar alla medföljande argument utom timeout direkt till gränssnittet.

Anteckning

Använd inte stdout=PIPE eller stderr=PIPE med denna funktion. Barnprocessen blockeras om den genererar tillräckligt med utdata till en pipe för att fylla OS-pipe-bufferten eftersom pipes inte läses från.

Ändrad i version 3.3: timeout har lagts till.

Ändrad i version 3.12: Ändrad sökordning för Windows shell för shell=True. Den aktuella katalogen och %PATH% ersätts med %COMSPEC% och %SystemRoot%\System32\cmd.exe. Som ett resultat fungerar det inte längre att släppa ett skadligt program med namnet cmd.exe i en aktuell katalog.

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

Kör kommandot med argument och returnera dess utdata.

Om returkoden var en annan än noll genereras ett CalledProcessError. Objektet CalledProcessError kommer att ha returkoden i attributet returncode och eventuell utdata i attributet output.

Detta är likvärdigt med:

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

De argument som visas ovan är bara några vanliga. Den fullständiga funktionssignaturen är i stort sett densamma som för run() - de flesta argument skickas direkt till det gränssnittet. En API-avvikelse från run()-beteendet finns: om man skickar input=None kommer det att bete sig på samma sätt som input=b'' (eller input='', beroende på andra argument) i stället för att använda förälderns standardinmatningsfilhandtag.

Som standard returnerar denna funktion data som kodade bytes. Den faktiska kodningen av utdata kan bero på vilket kommando som anropas, så avkodningen till text måste ofta hanteras på programnivå.

Detta beteende kan åsidosättas genom att text, encoding, errors eller universal_newlines sätts till True enligt beskrivningen i Ofta använda argument och run().

För att även fånga upp standardfel i resultatet, använd 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'

Tillagd i version 3.1.

Ändrad i version 3.3: timeout har lagts till.

Ändrad i version 3.4: Stöd för nyckelordsargumentet input har lagts till.

Ändrad i version 3.6: encoding och errors har lagts till. Se run() för detaljer.

Tillagd i version 3.7: text lades till som ett mer läsbart alias för universal_newlines.

Ändrad i version 3.12: Ändrad sökordning för Windows shell för shell=True. Den aktuella katalogen och %PATH% ersätts med %COMSPEC% och %SystemRoot%\System32\cmd.exe. Som ett resultat fungerar det inte längre att släppa ett skadligt program med namnet cmd.exe i en aktuell katalog.

Ersätta äldre funktioner med modulen `subprocess`¶

I detta avsnitt betyder ”a blir b” att b kan användas som ersättning för a.

Anteckning

Alla ”a”-funktioner i detta avsnitt misslyckas (mer eller mindre) tyst om det exekverade programmet inte kan hittas; ”b”-ersättningarna ger istället OSError.

Dessutom kommer de ersättningar som använder check_output() att misslyckas med en CalledProcessError om den begärda operationen ger en returkod som inte är noll. Utdata är fortfarande tillgänglig som attributet output för det undantag som uppstått.

I följande exempel antar vi att de relevanta funktionerna redan har importerats från modulen subprocess.

Ersätter /bin/sh substitution av skalkommando¶

output=$(mycmd myarg)

blir:

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

Byte av skalpipeline¶

output=$(dmesg | grep hda)

blir:

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close() # Tillåt p1 att ta emot ett SIGPIPE om p2 avslutas.
output = p2.communicate()[0]

Anropet p1.stdout.close() efter att p2 har startats är viktigt för att p1 ska få ett SIGPIPE om p2 avslutas före p1.

Alternativt kan skalets eget pipeline-stöd fortfarande användas direkt för betrodd inmatning:

output=$(dmesg | grep hda)

blir:

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

Ersätter `os.system()`¶

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

Anteckningar:

Att anropa programmet via skalet är vanligtvis inte nödvändigt.
Returvärdet för call() är kodat på ett annat sätt än för os.system().
Funktionen os.system() ignorerar SIGINT- och SIGQUIT-signaler medan kommandot körs, men den som anropar måste göra detta separat när modulen subprocess används.

Ett mer realistiskt exempel skulle kunna se ut så här:

försök:
    retcode = call("mycmd" + " myarg", shell=True)
    om retcode < 0:
        print("Barnet avslutades av en signal", -retcode, file=sys.stderr)
    i annat fall
        print("Barnet återvände", retcode, file=sys.stderr)
except OSError as e:
    print("Exekveringen misslyckades:", e, file=sys.stderr)

Ersätter `os.spawn`-familjen¶

P_NOWAIT exempel:

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

P_WAIT exempel:

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

Vektor exempel:

os.spawnvp(os.P_NOWAIT, sökväg, args)
==>
Popen([sökväg] + args[1:])

Exempel på miljö:

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

Ersätter `os.popen()`¶

Hanteringen av returkoden översätts på följande sätt:

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
om rc inte är None och rc >> 8:
    print("Det uppstod några fel")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
om process.wait() != 0:
    print("Det uppstod några fel")

Äldre funktioner för Shell-inkallning¶

Den här modulen innehåller också följande äldre funktioner från 2.x-modulen kommandon. Dessa funktioner anropar implicit systemets skal och ingen av de garantier som beskrivs ovan beträffande säkerhet och konsekvens i undantagshanteringen gäller för dessa funktioner.

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

Returnerar (exitcode, output) av att köra cmd i ett skal.

Exekvera strängen cmd i ett skal med Popen.check_output() och returnera en 2-tupel (exitcode, output). encoding och errors används för att avkoda utdata; se noterna om Ofta använda argument för mer information.

En efterföljande ny rad tas bort från utdata. Exitkoden för kommandot kan tolkas som returkoden för subprocessen. Exempel:

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

Tillgänglighet: Unix, Windows.

Ändrad i version 3.3.4: Stöd för Windows har lagts till.

Funktionen returnerar nu (exitcode, output) istället för (status, output) som den gjorde i Python 3.3.3 och tidigare. exitcode har samma värde som returncode.

Ändrad i version 3.11: Parametrarna encoding och errors har lagts till.

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

Returnera utdata (stdout och stderr) från körning av cmd i ett skal.

Som getstatusoutput(), förutom att utgångskoden ignoreras och returvärdet är en sträng som innehåller kommandots utdata. Exempel:

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

Tillgänglighet: Unix, Windows.

Ändrad i version 3.3.4: Windows-stöd har lagts till

Ändrad i version 3.11: Parametrarna encoding och errors har lagts till.

Anteckningar¶

Timeout-beteende¶

När parametern timeout används i funktioner som run(), Popen.wait(), eller Popen.communicate(), bör användare vara medvetna om följande beteenden:

Fördröjning av processskapande: Själva skapandet av den initiala processen kan inte avbrytas på många plattforms-API:er. Detta innebär att även om du anger en timeout är det inte säkert att du ser ett timeout-undantag förrän efter minst den tid som processskapandet tar.
Extremt små timeout-värden: Om du anger mycket små timeout-värden (t.ex. några millisekunder) kan det leda till nästan omedelbara TimeoutExpired-undantag eftersom skapandet av processer och schemaläggning av system i sig kräver tid.

Konvertera en argumentsekvens till en sträng i Windows¶

I Windows konverteras en args-sekvens till en sträng som kan analyseras med hjälp av följande regler (som motsvarar de regler som används av MS C runtime):

Argumenten avgränsas av ett vitt utrymme, som antingen är ett mellanslag eller en tabb.
En sträng som omges av dubbla citattecken tolkas som ett enda argument, oavsett om det finns blanksteg eller inte. En citerad sträng kan vara inbäddad i ett argument.
Ett dubbelt citationstecken som föregås av ett backslash tolkas som ett bokstavligt dubbelt citationstecken.
Bakåtstreck tolkas bokstavligt, såvida de inte omedelbart föregår ett dubbelt citattecken.
Om bindestreck omedelbart föregår ett dubbelt citattecken tolkas varje par av bindestreck som ett bokstavligt bindestreck. Om antalet backslash är udda, undgår den sista backslashen nästa dubbla citattecken enligt regel 3.

Se även

shlex: Modul som tillhandahåller funktioner för att analysera och escapa kommandorader.

Avaktivera användning av `posix_spawn()`¶

På Linux använder subprocess som standard systemanropet vfork() internt när det är säkert att göra det istället för fork(). Detta förbättrar prestandan avsevärt.

subprocess._USE_POSIX_SPAWN = False # Se CPython-problem gh-NNNNNN.

Det är säkert att sätta detta till false på alla Python-versioner. Det kommer inte att ha någon effekt på äldre eller nyare versioner där det inte stöds. Anta inte att attributet är tillgängligt för läsning. Trots namnet innebär ett true-värde inte att motsvarande funktion kommer att användas, bara att den kan komma att användas.

Skicka in frågor varje gång du måste använda dessa privata knoppar med ett sätt att reproducera problemet du såg. Länk till det problemet från en kommentar i din kod.

Tillagd i version 3.8: _USE_POSIX_SPAWN

`subprocess` — Hantering av underprocesser¶

Använda modulen `subprocess`¶

Ofta använda argument¶

Popen Konstruktör¶

Undantag¶

Säkerhetsöverväganden¶

Popen Objekt¶

Windows Popen Hjälpmedel¶

Windows-konstanter¶

Äldre API på hög nivå¶

Ersätta äldre funktioner med modulen `subprocess`¶

Ersätter /bin/sh substitution av skalkommando¶

Byte av skalpipeline¶

Ersätter `os.system()`¶

Ersätter `os.spawn`-familjen¶

Ersätter `os.popen()`¶

Äldre funktioner för Shell-inkallning¶

Anteckningar¶

Timeout-beteende¶

Konvertera en argumentsekvens till en sträng i Windows¶

Avaktivera användning av `posix_spawn()`¶

Innehåll

Föregående ämne

Nästa ämne

Denna sidan

subprocess — Hantering av underprocesser¶

Använda modulen subprocess¶

Ofta använda argument¶

Popen Konstruktör¶

Undantag¶

Säkerhetsöverväganden¶

Popen Objekt¶

Windows Popen Hjälpmedel¶

Windows-konstanter¶

Äldre API på hög nivå¶

Ersätta äldre funktioner med modulen subprocess¶

Ersätter /bin/sh substitution av skalkommando¶

Byte av skalpipeline¶

Ersätter os.system()¶

Ersätter os.spawn-familjen¶

Ersätter os.popen()¶

Äldre funktioner för Shell-inkallning¶

Anteckningar¶

Timeout-beteende¶

Konvertera en argumentsekvens till en sträng i Windows¶

Avaktivera användning av posix_spawn()¶

`subprocess` — Hantering av underprocesser¶

Använda modulen `subprocess`¶

Ersätta äldre funktioner med modulen `subprocess`¶

Ersätter `os.system()`¶

Ersätter `os.spawn`-familjen¶

Ersätter `os.popen()`¶

Avaktivera användning av `posix_spawn()`¶