python / python/cpython

`subprocess.run` docs should recommend copying `os.environ` on Windows

Offen
#120,836 5 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

docs topic-subprocess
Vorherrschende Sprache
Python
Sterne
77.2k
Forks
35.9k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

As described in https://stackoverflow.com/questions/78652758/, when passing custom environment variables to subprocess.run or subprocess.Popen on Windows, you will usually need to include the existing keys from os.environ in order to reliably run arbitrary processes (exactly which keys are required to be present depends on what the subprocess is doing).

The subprocess.Popen docs include a "Note" about this problem, but the subprocess.run docs omit it. Even the subprocess.Popen note is a bit vague, and only specifically mentions SystemRoot:

Note: If specified, env must provide any variables required for the program to execute. On Windows, in order to run a side-by-side assembly the specified env must include a valid SystemRoot.

The common documentation for the env parameter reads:

If env is not None, it must be a mapping that defines the environment variables for the new process; these are used instead of the default behavior of inheriting the current process’ environment. It is passed directly to Popen. This mapping can be str to str on any platform or bytes to bytes on POSIX platforms much like os.environ or os.environb.

Rather than re-using the existing subprocess.Popen note, my suggestion would be to add the following sentence to the above paragraph:

On Windows, many applications require specific environment variables (such as SystemRoot) to be set as expected in order to work correctly. Accordingly, it is recommended to start from os.environ.copy() when customing the subprocess environment on Windows, rather than starting from an empty dictionary (otherwise the executed subprocesses may fail with various Windows OS errors).

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne mit der gemeinsamen Dokumentation des Parameters env für subprocess.run und subprocess.Popen und vergleiche anschließend den vorhandenen Windows-Hinweis in der Popen-Dokumentation. Füge Hinweise dazu hinzu, dass man beim Anpassen der Umgebung eines Windows-Subprozesses mit os.environ.copy() beginnen sollte, und überprüfe, dass die aktualisierte Formulierung erforderliche Variablen wie SystemRoot eindeutig abdeckt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
45/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.