diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 56777384568..e09994ce7d5 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -212,9 +212,10 @@ This module defines one class called :class:`Popen`: :attr:`stdout`, :attr:`stdin` and :attr:`stderr` are not updated by the :meth:`communicate` method. - The *startupinfo* and *creationflags*, if given, will be passed to the - underlying CreateProcess() function. They can specify things such as appearance - of the main window and priority for the new process. (Windows only) + If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is + passed to the underlying ``CreateProcess`` function. + *creationflags*, if given, can be :data:`CREATE_NEW_CONSOLE` or + :data:`CREATE_NEW_PROCESS_GROUP`. (Windows only) Popen objects are supported as context managers via the :keyword:`with` statement, closing any open file descriptors on exit. @@ -482,6 +483,109 @@ The following attributes are also available: ``N`` (Unix only). +Windows Popen Helpers +--------------------- + +The :class:`STARTUPINFO` class and following constants are only available +on Windows. + +.. class:: STARTUPINFO() + + Partial support of the Windows + `STARTUPINFO `__ + structure is used for :class:`Popen` creation. + + .. attribute:: dwFlags + + A bit field that determines whether certain :class:`STARTUPINFO` members + are used when the process creates a window. :: + + si = subprocess.STARTUPINFO() + si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW + + .. attribute:: hStdInput + + If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is + the standard input handle for the process. If :data:`STARTF_USESTDHANDLES` + is not specified, the default for standard input is the keyboard buffer. + + .. attribute:: hStdOutput + + If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is + the standard output handle for the process. Otherwise, this member is + ignored and the default for standard output is the console window's + buffer. + + .. attribute:: hStdError + + If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is + the standard error handle for the process. Otherwise, this member is + ignored and the default for standard error is the console window's buffer. + + .. attribute:: wShowWindow + + If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this member + can be any of the values that can be specified in the ``nCmdShow`` + parameter for the + `ShowWindow `__ + function, except for ``SW_SHOWDEFAULT``. Otherwise, this member is + ignored. + + :data:`SW_HIDE` is provided for this attribute. It is used when + :class:`Popen` is called with ``shell=True``. + + +Constants +^^^^^^^^^ + +The :mod:`subprocess` module exposes the following constants. + +.. data:: STD_INPUT_HANDLE + + The standard input device. Initially, this is the console input buffer, + ``CONIN$``. + +.. data:: STD_OUTPUT_HANDLE + + The standard output device. Initially, this is the active console screen + buffer, ``CONOUT$``. + +.. data:: STD_ERROR_HANDLE + + The standard error device. Initially, this is the active console screen + buffer, ``CONOUT$``. + +.. data:: SW_HIDE + + Hides the window. Another window will be activated. + +.. data:: STARTF_USESTDHANDLES + + Specifies that the :attr:`STARTUPINFO.hStdInput`, + :attr:`STARTUPINFO.hStdOutput`, and :attr:`STARTUPINFO.hStdError` members + contain additional information. + +.. data:: STARTF_USESHOWWINDOW + + Specifies that the :attr:`STARTUPINFO.wShowWindow` member contains + additional information. + +.. data:: CREATE_NEW_CONSOLE + + The new process has a new console, instead of inheriting its parent's + console (the default). + + This flag is always set when :class:`Popen` is created with ``shell=True``. + +.. data:: CREATE_NEW_PROCESS_GROUP + + A :class:`Popen` ``creationflags`` parameter to specify that a new process + group will be created. This flag is necessary for using :func:`os.kill` + on the subprocess. + + This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified. + + .. _subprocess-replacements: Replacing Older Functions with the subprocess Module