diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -214,9 +214,10 @@ :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. @@ -551,6 +552,100 @@ ``N`` (Unix only). +Windows Popen Helpers +--------------------- + +.. class:: STARTUPINFO() + + Partial support of the Windows + `STARTUPINFO `__ + structure is used for :class:`Popen` creation. + +.. attribute:: STARTUPINFO.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:: STARTUPINFO.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:: STARTUPINFO.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:: STARTUPINFO.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:: STARTUPINFO.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``. + +.. 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