cpython: 609ca9d71aba (original) (raw)

Mercurial > cpython

changeset 69698:609ca9d71aba 3.1

Fix #11961. Document STARTUPINFO and creation flag options. [#11961]

Brian Curtin brian@python.org
date	Fri, 29 Apr 2011 22:17:51 -0500
parents	c4a9149d467f
children	cd68b3031f00
files	Doc/library/subprocess.rst
diffstat	1 files changed, 98 insertions(+), 3 deletions(-)[+] [-] Doc/library/subprocess.rst 101

line wrap: on

line diff

--- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -171,9 +171,9 @@ This module defines one class called :cl :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. (Windows only)

.. data:: PIPE @@ -428,6 +428,101 @@ The following attributes are also availa 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 <http://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx>__
structure is used for :class:Popen creation. +
.. attribute:: dwFlags +

 A bit field that determines whether certain :class:`STARTUPINFO` members[](#l1.34)

 are used when the process creates a window. ::[](#l1.35)

    si = subprocess.STARTUPINFO()[](#l1.37)

    si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW[](#l1.38)

.. attribute:: hStdInput +

 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is[](#l1.42)

 the standard input handle for the process. If :data:`STARTF_USESTDHANDLES`[](#l1.43)

 is not specified, the default for standard input is the keyboard buffer.[](#l1.44)

.. attribute:: hStdOutput +

 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is[](#l1.48)

 the standard output handle for the process. Otherwise, this member is[](#l1.49)

 ignored and the default for standard output is the console window's[](#l1.50)

```
 buffer.[](#l1.51)
```

.. attribute:: hStdError +

 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this member is[](#l1.55)

 the standard error handle for the process. Otherwise, this member is[](#l1.56)

 ignored and the default for standard error is the console window's buffer.[](#l1.57)

.. attribute:: wShowWindow +

 If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this member[](#l1.61)

 can be any of the values that can be specified in the ``nCmdShow``[](#l1.62)

```
 parameter for the[](#l1.63)
```

 `ShowWindow <http://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx>`__[](#l1.64)

 function, except for ``SW_SHOWDEFAULT``. Otherwise, this member is[](#l1.65)

```
 ignored.[](#l1.66)
```

 :data:`SW_HIDE` is provided for this attribute. It is used when[](#l1.68)

 :class:`Popen` is called with ``shell=True``.[](#l1.69)

+ + +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. +

+ .. _subprocess-replacements: Replacing Older Functions with the subprocess Module