cpython-lru_cache-weakref: Doc/library/subprocess.rst annotate

annotate Doc/library/subprocess.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	bbdb90bf2692
children	7a69b4077afb

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 :mod:`subprocess` --- Subprocess management
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ===========================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 .. module:: subprocess
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 :synopsis: Subprocess management.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 The :mod:`subprocess` module allows you to spawn new processes, connect to their
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 input/output/error pipes, and obtain their return codes. This module intends to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 replace several other, older modules and functions, such as::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 os.system
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 os.spawn*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 os.popen*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 popen2.*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 commands.*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 Information about how the :mod:`subprocess` module can be used to replace these
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 modules and functions can be found in the following sections.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25
47862 e68fe90f15ab Add a link to PEP 324. Georg Brandl <georg@python.org> parents: 47805 diff changeset	26 .. seealso::
e68fe90f15ab Add a link to PEP 324. Georg Brandl <georg@python.org> parents: 47805 diff changeset	27
e68fe90f15ab Add a link to PEP 324. Georg Brandl <georg@python.org> parents: 47805 diff changeset	28 :pep:`324` -- PEP proposing the subprocess module
e68fe90f15ab Add a link to PEP 324. Georg Brandl <georg@python.org> parents: 47805 diff changeset	29
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 Using the subprocess Module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 ---------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	34 The recommended approach to invoking subprocesses is to use the following
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	35 convenience functions for all use cases they can handle. For more advanced
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	36 use cases, the underlying :class:`Popen` interface can be used directly.
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	37
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	38
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	39 .. function:: call(args, *, stdin=None, stdout=None, stderr=None, shell=False)
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	40
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	41 Run the command described by args. Wait for command to complete, then
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	42 return the :attr:`returncode` attribute.
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	43
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	44 The arguments shown above are merely the most common ones, described below
73141 2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	45 in :ref:`frequently-used-arguments` (hence the slightly odd notation in
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	46 the abbreviated signature). The full function signature is the same as
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	47 that of the :class:`Popen` constructor - this functions passes all
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	48 supplied arguments directly through to that interface.
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	49
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	50 Examples::
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	51
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	52 >>> subprocess.call(["ls", "-l"])
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	53 0
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	54
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	55 >>> subprocess.call("exit 1", shell=True)
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	56 1
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	57
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	58 .. warning::
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	59
73141 2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	60 Invoking the system shell with ``shell=True`` can be a security hazard
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	61 if combined with untrusted input. See the warning under
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	62 :ref:`frequently-used-arguments` for details.
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	63
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	64 .. note::
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	65
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	66 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	67 the pipes are not being read in the current process, the child
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	68 process may block if it generates enough output to a pipe to fill up
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	69 the OS pipe buffer.
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	70
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	71
73141 2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	72 .. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False)
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	73
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	74 Run command with arguments. Wait for command to complete. If the return
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	75 code was zero then return, otherwise raise :exc:`CalledProcessError`. The
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	76 :exc:`CalledProcessError` object will have the return code in the
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	77 :attr:`returncode` attribute.
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	78
73141 2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	79 The arguments shown above are merely the most common ones, described below
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	80 in :ref:`frequently-used-arguments` (hence the slightly odd notation in
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	81 the abbreviated signature). The full function signature is the same as
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	82 that of the :class:`Popen` constructor - this functions passes all
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	83 supplied arguments directly through to that interface.
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	84
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	85 Examples::
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	86
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	87 >>> subprocess.check_call(["ls", "-l"])
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	88 0
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	89
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	90 >>> subprocess.check_call("exit 1", shell=True)
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	91 Traceback (most recent call last):
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	92 ...
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	93 subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	94
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	95 .. versionadded:: 2.5
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	96
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	97 .. warning::
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	98
73141 2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	99 Invoking the system shell with ``shell=True`` can be a security hazard
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	100 if combined with untrusted input. See the warning under
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	101 :ref:`frequently-used-arguments` for details.
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	102
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	103 .. note::
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	104
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	105 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	106 the pipes are not being read in the current process, the child
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	107 process may block if it generates enough output to a pipe to fill up
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	108 the OS pipe buffer.
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	109
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	110
73141 2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	111 .. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False)
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	112
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	113 Run command with arguments and return its output as a byte string.
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	114
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	115 If the return code was non-zero it raises a :exc:`CalledProcessError`. The
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	116 :exc:`CalledProcessError` object will have the return code in the
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	117 :attr:`returncode` attribute and any output in the :attr:`output`
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	118 attribute.
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	119
73141 2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	120 The arguments shown above are merely the most common ones, described below
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	121 in :ref:`frequently-used-arguments` (hence the slightly odd notation in
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	122 the abbreviated signature). The full function signature is largely the
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	123 same as that of the :class:`Popen` constructor, except that stdout is
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	124 not permitted as it is used internally. All other supplied arguments are
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	125 passed directly through to the :class:`Popen` constructor.
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	126
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	127 Examples::
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	128
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	129 >>> subprocess.check_output(["echo", "Hello World!"])
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	130 'Hello World!\n'
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	131
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	132 >>> subprocess.check_output("exit 1", shell=True)
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	133 Traceback (most recent call last):
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	134 ...
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	135 subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	136
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	137 To also capture standard error in the result, use
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	138 ``stderr=subprocess.STDOUT``::
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	139
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	140 >>> subprocess.check_output(
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	141 ... "ls non_existent_file; exit 0",
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	142 ... stderr=subprocess.STDOUT,
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	143 ... shell=True)
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	144 'ls: non_existent_file: No such file or directory\n'
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	145
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	146 .. versionadded:: 2.7
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	147
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	148 .. warning::
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	149
73141 2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	150 Invoking the system shell with ``shell=True`` can be a security hazard
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	151 if combined with untrusted input. See the warning under
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	152 :ref:`frequently-used-arguments` for details.
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	153
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	154 .. note::
2a2df6a72ccb Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it) Nick Coghlan <ncoghlan@gmail.com> parents: 73133 diff changeset	155
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	156 Do not use ``stderr=PIPE`` with this function. As the pipe is not being
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	157 read in the current process, the child process may block if it
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	158 generates enough output to the pipe to fill up the OS pipe buffer.
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	159
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	160
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	161 .. data:: PIPE
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	162
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	163 Special value that can be used as the stdin, stdout or stderr argument
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	164 to :class:`Popen` and indicates that a pipe to the standard stream should be
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	165 opened.
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	166
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	167
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	168 .. data:: STDOUT
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	169
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	170 Special value that can be used as the stderr argument to :class:`Popen` and
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	171 indicates that standard error should go into the same handle as standard
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	172 output.
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	173
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	174
78477 9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	175 .. exception:: CalledProcessError
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	176
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	177 Exception raised when a process run by :func:`check_call` or
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	178 :func:`check_output` returns a non-zero exit status.
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	179
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	180 .. attribute:: returncode
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	181
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	182 Exit status of the child process.
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	183
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	184 .. attribute:: cmd
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	185
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	186 Command that was used to spawn the child process.
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	187
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	188 .. attribute:: output
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	189
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	190 Output of the child process if this exception is raised by
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	191 :func:`check_output`. Otherwise, ``None``.
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	192
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	193
9c99f31a9c2a Issue #15501: Document exception classes in subprocess module. Andrew Svetlov <andrew.svetlov@gmail.com> parents: 78144 diff changeset	194
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	195 .. _frequently-used-arguments:
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	196
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	197 Frequently Used Arguments
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	198 ^^^^^^^^^^^^^^^^^^^^^^^^^
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	199
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	200 To support a wide variety of use cases, the :class:`Popen` constructor (and
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	201 the convenience functions) accept a large number of optional arguments. For
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	202 most typical use cases, many of these arguments can be safely left at their
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	203 default values. The arguments that are most commonly needed are:
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	204
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	205 args is required for all calls and should be a string, or a sequence of
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	206 program arguments. Providing a sequence of arguments is generally
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	207 preferred, as it allows the module to take care of any required escaping
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	208 and quoting of arguments (e.g. to permit spaces in file names). If passing
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	209 a single string, either shell must be :const:`True` (see below) or else
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	210 the string must simply name the program to be executed without specifying
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	211 any arguments.
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	212
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	213 stdin, stdout and stderr specify the executed program's standard input,
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	214 standard output and standard error file handles, respectively. Valid values
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	215 are :data:`PIPE`, an existing file descriptor (a positive integer), an
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	216 existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	217 to the child should be created. With the default settings of ``None``, no
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	218 redirection will occur; the child's file handles will be inherited from the
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	219 parent. Additionally, stderr can be :data:`STDOUT`, which indicates that
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	220 the stderr data from the child process should be captured into the same file
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	221 handle as for stdout.
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	222
78596 8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it. R David Murray <rdmurray@bitdance.com> parents: 78477 diff changeset	223 .. index::
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it. R David Murray <rdmurray@bitdance.com> parents: 78477 diff changeset	224 single: universal newlines; subprocess module
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it. R David Murray <rdmurray@bitdance.com> parents: 78477 diff changeset	225
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	226 When stdout or stderr are pipes and universal_newlines is
78596 8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it. R David Murray <rdmurray@bitdance.com> parents: 78477 diff changeset	227 ``True`` then all line endings will be converted to ``'\n'`` as described
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it. R David Murray <rdmurray@bitdance.com> parents: 78477 diff changeset	228 for the :term:`universal newlines` `'U'`` mode argument to :func:`open`.
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	229
79032 820032281f49 #15789: mention shell-like parts of the stdlib in the subprocess docs. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78774 diff changeset	230 If shell is ``True``, the specified command will be executed through
820032281f49 #15789: mention shell-like parts of the stdlib in the subprocess docs. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78774 diff changeset	231 the shell. This can be useful if you are using Python primarily for the
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	232 enhanced control flow it offers over most system shells and still want
79032 820032281f49 #15789: mention shell-like parts of the stdlib in the subprocess docs. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78774 diff changeset	233 convenient access to other shell features such as shell pipes, filename
820032281f49 #15789: mention shell-like parts of the stdlib in the subprocess docs. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78774 diff changeset	234 wildcards, environment variable expansion, and expansion of ``~`` to a
820032281f49 #15789: mention shell-like parts of the stdlib in the subprocess docs. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78774 diff changeset	235 user's home directory. However, note that Python itself offers
820032281f49 #15789: mention shell-like parts of the stdlib in the subprocess docs. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78774 diff changeset	236 implementations of many shell-like features (in particular, :mod:`glob`,
820032281f49 #15789: mention shell-like parts of the stdlib in the subprocess docs. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78774 diff changeset	237 :mod:`fnmatch`, :func:`os.walk`, :func:`os.path.expandvars`,
820032281f49 #15789: mention shell-like parts of the stdlib in the subprocess docs. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78774 diff changeset	238 :func:`os.path.expanduser`, and :mod:`shutil`).
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	239
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	240 .. warning::
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	241
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	242 Executing shell commands that incorporate unsanitized input from an
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	243 untrusted source makes a program vulnerable to `shell injection
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	244 <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_,
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	245 a serious security flaw which can result in arbitrary command execution.
79663 bbdb90bf2692 Backport from 3.2: Fix placement of shell=True warning in subprocess.Popen() docs. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79659 diff changeset	246 For this reason, the use of ``shell=True`` is strongly discouraged
bbdb90bf2692 Backport from 3.2: Fix placement of shell=True warning in subprocess.Popen() docs. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79659 diff changeset	247 in cases where the command string is constructed from external input::
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	248
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	249 >>> from subprocess import call
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	250 >>> filename = input("What file would you like to display?\n")
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	251 What file would you like to display?
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	252 non_existent; rm -rf / #
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	253 >>> call("cat " + filename, shell=True) # Uh-oh. This will end badly...
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	254
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	255 ``shell=False`` disables all shell based features, but does not suffer
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	256 from this vulnerability; see the Note in the :class:`Popen` constructor
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	257 documentation for helpful hints in getting ``shell=False`` to work.
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	258
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	259 These options, along with all of the other options, are described in more
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	260 detail in the :class:`Popen` constructor documentation.
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	261
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	262
74164 eea6b76eb2fc fix Constuctor/Constructor typo; thanks to Anthon van der Neut from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 73141 diff changeset	263 Popen Constructor
74173 43808e022444 fix "Title underline too short" sphinx warning Sandro Tosi <sandro.tosi@gmail.com> parents: 74164 diff changeset	264 ^^^^^^^^^^^^^^^^^
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	265
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	266 The underlying process creation and management in this module is handled by
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	267 the :class:`Popen` class. It offers a lot of flexibility so that developers
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	268 are able to handle the less common cases not covered by the convenience
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	269 functions.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
79659 f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	272 .. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, \
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	273 stderr=None, preexec_fn=None, close_fds=False, shell=False, \
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	274 cwd=None, env=None, universal_newlines=False, \
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	275 startupinfo=None, creationflags=0)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
79659 f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	277 Execute a child program in a new process. On Unix, the class uses
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	278 :meth:`os.execvp`-like behavior to execute the child program. On Windows,
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	279 the class uses the Windows ``CreateProcess()`` function. The arguments to
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	280 :class:`Popen` are as follows.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
79605 11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	282 args should be a sequence of program arguments or else a single string.
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	283 By default, the program to execute is the first item in args if args is
79659 f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	284 a sequence. If args is a string, the interpretation is
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	285 platform-dependent and described below. See the shell and executable
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	286 arguments for additional differences from the default behavior. Unless
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	287 otherwise stated, it is recommended to pass args as a sequence.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
79659 f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	289 On Unix, if args is a string, the string is interpreted as the name or
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	290 path of the program to execute. However, this can only be done if not
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	291 passing arguments to the program.
58687 c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	292
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	293 .. note::
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	294
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	295 :meth:`shlex.split` can be useful when determining the correct
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	296 tokenization for args, especially in complex cases::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297
58687 c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	298 >>> import shlex, subprocess
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	299 >>> command_line = raw_input()
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	300 /bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	301 >>> args = shlex.split(command_line)
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	302 >>> print args
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	303 ['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	304 >>> p = subprocess.Popen(args) # Success!
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	305
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	306 Note in particular that options (such as -input) and arguments (such
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	307 as eggs.txt) that are separated by whitespace in the shell go in separate
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	308 list elements, while arguments that need quoting or backslash escaping when
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	309 used in the shell (such as filenames containing spaces or the echo command
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	310 shown above) are single list elements.
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	311
79659 f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	312 On Windows, if args is a sequence, it will be converted to a string in a
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	313 manner described in :ref:`converting-argument-sequence`. This is because
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	314 the underlying ``CreateProcess()`` operates on strings.
79605 11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	315
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	316 The shell argument (which defaults to False) specifies whether to use
79659 f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	317 the shell as the program to execute. If shell is True, it is
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	318 recommended to pass args as a string rather than as a sequence.
79605 11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	319
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	320 On Unix with ``shell=True``, the shell defaults to :file:`/bin/sh`. If
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	321 args is a string, the string specifies the command
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	322 to execute through the shell. This means that the string must be
58687 c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	323 formatted exactly as it would be when typed at the shell prompt. This
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	324 includes, for example, quoting or backslash escaping filenames with spaces in
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	325 them. If args is a sequence, the first item specifies the command string, and
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	326 any additional items will be treated as additional arguments to the shell
79605 11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	327 itself. That is to say, :class:`Popen` does the equivalent of::
58687 c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	328
c7254e8bc1db Merged revisions 77943,77959-77960 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56816 diff changeset	329 Popen(['/bin/sh', '-c', args[0], args[1], ...])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
79605 11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	331 On Windows with ``shell=True``, the :envvar:`COMSPEC` environment variable
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	332 specifies the default shell. The only time you need to specify
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	333 ``shell=True`` on Windows is when the command you wish to execute is built
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	334 into the shell (e.g. :command:`dir` or :command:`copy`). You do not need
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	335 ``shell=True`` to run a batch file or console-based executable.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
79663 bbdb90bf2692 Backport from 3.2: Fix placement of shell=True warning in subprocess.Popen() docs. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79659 diff changeset	337 .. warning::
bbdb90bf2692 Backport from 3.2: Fix placement of shell=True warning in subprocess.Popen() docs. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79659 diff changeset	338
bbdb90bf2692 Backport from 3.2: Fix placement of shell=True warning in subprocess.Popen() docs. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79659 diff changeset	339 Passing ``shell=True`` can be a security hazard if combined with
bbdb90bf2692 Backport from 3.2: Fix placement of shell=True warning in subprocess.Popen() docs. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79659 diff changeset	340 untrusted input. See the warning under :ref:`frequently-used-arguments`
bbdb90bf2692 Backport from 3.2: Fix placement of shell=True warning in subprocess.Popen() docs. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79659 diff changeset	341 for details.
bbdb90bf2692 Backport from 3.2: Fix placement of shell=True warning in subprocess.Popen() docs. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79659 diff changeset	342
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 bufsize, if given, has the same meaning as the corresponding argument to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 built-in open() function: :const:`0` means unbuffered, :const:`1` means line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 buffered, any other positive value means use a buffer of (approximately) that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 size. A negative bufsize means to use the system default, which usually means
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 fully buffered. The default value for bufsize is :const:`0` (unbuffered).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
62030 b47c4cf25f02 Merged revisions 81652 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61733 diff changeset	349 .. note::
b47c4cf25f02 Merged revisions 81652 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61733 diff changeset	350
b47c4cf25f02 Merged revisions 81652 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61733 diff changeset	351 If you experience performance issues, it is recommended that you try to
b47c4cf25f02 Merged revisions 81652 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61733 diff changeset	352 enable buffering by setting bufsize to either -1 or a large enough
b47c4cf25f02 Merged revisions 81652 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61733 diff changeset	353 positive value (such as 4096).
b47c4cf25f02 Merged revisions 81652 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 61733 diff changeset	354
79605 11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	355 The executable argument specifies a replacement program to execute. It
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	356 is very seldom needed. When ``shell=False``, executable replaces the
79659 f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	357 program to execute specified by args. However, the original args is
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	358 still passed to the program. Most programs treat the program specified
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	359 by args as the command name, which can then be different from the program
f051e37ac11d Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79605 diff changeset	360 actually executed. On Unix, the args name
79605 11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	361 becomes the display name for the executable in utilities such as
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	362 :program:`ps`. If ``shell=True``, on Unix the executable argument
11171bf6a6bd Issue #16115: Backport subprocess.Popen() documentation improvements from 3.2. Chris Jerdonek <chris.jerdonek@gmail.com> parents: 79032 diff changeset	363 specifies a replacement shell for the default :file:`/bin/sh`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	365 stdin, stdout and stderr specify the executed program's standard input,
50065 ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	366 standard output and standard error file handles, respectively. Valid values
ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	367 are :data:`PIPE`, an existing file descriptor (a positive integer), an
ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	368 existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	369 to the child should be created. With the default settings of ``None``, no
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	370 redirection will occur; the child's file handles will be inherited from the
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	371 parent. Additionally, stderr can be :data:`STDOUT`, which indicates that
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	372 the stderr data from the child process should be captured into the same file
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	373 handle as for stdout.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 If preexec_fn is set to a callable object, this object will be called in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 child process just before the child is executed. (Unix only)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 If close_fds is true, all file descriptors except :const:`0`, :const:`1` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 :const:`2` will be closed before the child process is executed. (Unix only).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 Or, on Windows, if close_fds is true then no handles will be inherited by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 child process. Note that on Windows, you cannot set close_fds to true and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 also redirect the standard handles by setting stdin, stdout or stderr.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 If cwd is not ``None``, the child's current directory will be changed to cwd
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 before it is executed. Note that this directory is not considered when
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 searching the executable, so you can't specify the program's path relative to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 cwd.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388
46483 374833de570c #2633: clarify meaning of env parameter. Georg Brandl <georg@python.org> parents: 46480 diff changeset	389 If env is not ``None``, it must be a mapping that defines the environment
374833de570c #2633: clarify meaning of env parameter. Georg Brandl <georg@python.org> parents: 46480 diff changeset	390 variables for the new process; these are used instead of inheriting the current
374833de570c #2633: clarify meaning of env parameter. Georg Brandl <georg@python.org> parents: 46480 diff changeset	391 process' environment, which is the default behavior.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392
53177 f0a16e1deea1 Merged revisions 71651 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53164 diff changeset	393 .. note::
53164 7a69ffc4f4ae Merged revisions 71631 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 50522 diff changeset	394
53177 f0a16e1deea1 Merged revisions 71651 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53164 diff changeset	395 If specified, env must provide any variables required
f0a16e1deea1 Merged revisions 71651 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53164 diff changeset	396 for the program to execute. On Windows, in order to run a
f0a16e1deea1 Merged revisions 71651 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53164 diff changeset	397 `side-by-side assembly`_ the specified env must include a valid
53164 7a69ffc4f4ae Merged revisions 71631 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 50522 diff changeset	398 :envvar:`SystemRoot`.
7a69ffc4f4ae Merged revisions 71631 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 50522 diff changeset	399
53177 f0a16e1deea1 Merged revisions 71651 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53164 diff changeset	400 .. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly
f0a16e1deea1 Merged revisions 71651 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53164 diff changeset	401
78597 35d8a638b0e2 #15543: reflow paragraphs. R David Murray <rdmurray@bitdance.com> parents: 78596 diff changeset	402 If universal_newlines is ``True``, the file objects stdout and stderr
35d8a638b0e2 #15543: reflow paragraphs. R David Murray <rdmurray@bitdance.com> parents: 78596 diff changeset	403 are opened as text files in :term:`universal newlines` mode. Lines may be
35d8a638b0e2 #15543: reflow paragraphs. R David Murray <rdmurray@bitdance.com> parents: 78596 diff changeset	404 terminated by any of ``'\n'``, the Unix end-of-line convention, ``'\r'``,
35d8a638b0e2 #15543: reflow paragraphs. R David Murray <rdmurray@bitdance.com> parents: 78596 diff changeset	405 the old Macintosh convention or ``'\r\n'``, the Windows convention. All of
35d8a638b0e2 #15543: reflow paragraphs. R David Murray <rdmurray@bitdance.com> parents: 78596 diff changeset	406 these external representations are seen as ``'\n'`` by the Python program.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
59831 38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from Georg Brandl <georg@python.org> parents: 58687 diff changeset	410 This feature is only available if Python is built with universal newline
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from Georg Brandl <georg@python.org> parents: 58687 diff changeset	411 support (the default). Also, the newlines attribute of the file objects
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from Georg Brandl <georg@python.org> parents: 58687 diff changeset	412 :attr:`stdout`, :attr:`stdin` and :attr:`stderr` are not updated by the
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from Georg Brandl <georg@python.org> parents: 58687 diff changeset	413 communicate() method.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	415 If given, startupinfo will be a :class:`STARTUPINFO` object, which is
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	416 passed to the underlying ``CreateProcess`` function.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	417 creationflags, if given, can be :data:`CREATE_NEW_CONSOLE` or
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	418 :data:`CREATE_NEW_PROCESS_GROUP`. (Windows only)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 Exceptions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 ^^^^^^^^^^
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424 Exceptions raised in the child process, before the new program has started to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 execute, will be re-raised in the parent. Additionally, the exception object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 will have one extra attribute called :attr:`child_traceback`, which is a string
65127 ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 63015 diff changeset	427 containing traceback information from the child's point of view.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 The most common exception raised is :exc:`OSError`. This occurs, for example,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 when trying to execute a non-existent file. Applications should prepare for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 :exc:`OSError` exceptions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 A :exc:`ValueError` will be raised if :class:`Popen` is called with invalid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 arguments.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	436 :func:`check_call` and :func:`check_output` will raise
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	437 :exc:`CalledProcessError` if the called process returns a non-zero return
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	438 code.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 Security
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 ^^^^^^^^
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	444 Unlike some other popen functions, this implementation will never call a
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	445 system shell implicitly. This means that all characters, including shell
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	446 metacharacters, can safely be passed to child processes. Obviously, if the
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	447 shell is invoked explicitly, then it is the application's responsibility to
73133 5dfe6d7f7c61 Issue #13237: fix typo Nick Coghlan <ncoghlan@gmail.com> parents: 73132 diff changeset	448 ensure that all whitespace and metacharacters are quoted appropriately.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 Popen Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 -------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 Instances of the :class:`Popen` class have the following methods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 .. method:: Popen.poll()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	459 Check if child process has terminated. Set and return :attr:`returncode`
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	460 attribute.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463 .. method:: Popen.wait()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	465 Wait for child process to terminate. Set and return :attr:`returncode`
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	466 attribute.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467
48164 c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	468 .. warning::
c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	469
57542 d7cc9017ac4c #7177: clarify the potential PIPE deadlock warnings Philip Jenvey <pjenvey@underboss.org> parents: 56294 diff changeset	470 This will deadlock when using ``stdout=PIPE`` and/or
d7cc9017ac4c #7177: clarify the potential PIPE deadlock warnings Philip Jenvey <pjenvey@underboss.org> parents: 56294 diff changeset	471 ``stderr=PIPE`` and the child process generates enough output to
d7cc9017ac4c #7177: clarify the potential PIPE deadlock warnings Philip Jenvey <pjenvey@underboss.org> parents: 56294 diff changeset	472 a pipe such that it blocks waiting for the OS pipe buffer to
d7cc9017ac4c #7177: clarify the potential PIPE deadlock warnings Philip Jenvey <pjenvey@underboss.org> parents: 56294 diff changeset	473 accept more data. Use :meth:`communicate` to avoid that.
48161 8bd5650193c6 issue1606: Add warnings to the subprocess documentation about common pitfalls Gregory P. Smith <greg@mad-scientist.com> parents: 48089 diff changeset	474
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476 .. method:: Popen.communicate(input=None)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 Interact with process: Send data to stdin. Read data from stdout and stderr,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 until end-of-file is reached. Wait for process to terminate. The optional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 input argument should be a string to be sent to the child process, or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 ``None``, if no data should be sent to the child.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482
50008 11bf59fe10b9 Merged revisions 67326,67498,67531-67532,67538,67553-67554,67556-67557 via svnmerge from Georg Brandl <georg@python.org> parents: 49677 diff changeset	483 :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484
44005 d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	485 Note that if you want to send data to the process's stdin, you need to create
d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	486 the Popen object with ``stdin=PIPE``. Similarly, to get anything other than
d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	487 ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	488 ``stderr=PIPE`` too.
d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	489
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	490 .. note::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	492 The data read is buffered in memory, so do not use this method if the data
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	493 size is large or unlimited.
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	494
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	496 .. method:: Popen.send_signal(signal)
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	497
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	498 Sends the signal signal to the child.
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	499
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	500 .. note::
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	501
60197 0ab89e8bdedc Implement #1220212. Add os.kill support for Windows. Brian Curtin <brian.curtin@gmail.com> parents: 59796 diff changeset	502 On Windows, SIGTERM is an alias for :meth:`terminate`. CTRL_C_EVENT and
60348 e94d446c6d0e Fix markup errors. Ezio Melotti <ezio.melotti@gmail.com> parents: 60197 diff changeset	503 CTRL_BREAK_EVENT can be sent to processes started with a creationflags
60197 0ab89e8bdedc Implement #1220212. Add os.kill support for Windows. Brian Curtin <brian.curtin@gmail.com> parents: 59796 diff changeset	504 parameter which includes `CREATE_NEW_PROCESS_GROUP`.
46480 e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	505
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	506 .. versionadded:: 2.6
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	507
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	508
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	509 .. method:: Popen.terminate()
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	510
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	511 Stop the child. On Posix OSs the method sends SIGTERM to the
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74173 diff changeset	512 child. On Windows the Win32 API function :c:func:`TerminateProcess` is called
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	513 to stop the child.
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	514
46480 e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	515 .. versionadded:: 2.6
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	516
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	517
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	518 .. method:: Popen.kill()
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	519
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	520 Kills the child. On Posix OSs the function sends SIGKILL to the child.
46480 e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	521 On Windows :meth:`kill` is an alias for :meth:`terminate`.
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	522
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	523 .. versionadded:: 2.6
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	524
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	525
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 The following attributes are also available:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527
48164 c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	528 .. warning::
c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	529
78774 92aa438a5c4b #15788: fix broken links in subprocess doc. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78597 diff changeset	530 Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
92aa438a5c4b #15788: fix broken links in subprocess doc. Patch by Chris Rebert. Ezio Melotti <ezio.melotti@gmail.com> parents: 78597 diff changeset	531 :attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
53573 503f0f41f35f Merged revisions 72007-72010,72036-72037 via svnmerge from Georg Brandl <georg@python.org> parents: 53177 diff changeset	532 deadlocks due to any of the other OS pipe buffers filling up and blocking the
503f0f41f35f Merged revisions 72007-72010,72036-72037 via svnmerge from Georg Brandl <georg@python.org> parents: 53177 diff changeset	533 child process.
48164 c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	534
c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	535
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 .. attribute:: Popen.stdin
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
50065 ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	538 If the stdin argument was :data:`PIPE`, this attribute is a file object
ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	539 that provides input to the child process. Otherwise, it is ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 .. attribute:: Popen.stdout
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543
50065 ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	544 If the stdout argument was :data:`PIPE`, this attribute is a file object
ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	545 that provides output from the child process. Otherwise, it is ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 .. attribute:: Popen.stderr
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
50065 ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	550 If the stderr argument was :data:`PIPE`, this attribute is a file object
ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	551 that provides error output from the child process. Otherwise, it is
ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	552 ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 .. attribute:: Popen.pid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557 The process ID of the child process.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558
59845 f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	559 Note that if you set the shell argument to ``True``, this is the process ID
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	560 of the spawned shell.
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from Georg Brandl <georg@python.org> parents: 59831 diff changeset	561
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 .. attribute:: Popen.returncode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	565 The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	566 by :meth:`communicate`). A ``None`` value indicates that the process
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	567 hasn't terminated yet.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50065 diff changeset	568
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	569 A negative value ``-N`` indicates that the child was terminated by signal
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	570 ``N`` (Unix only).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	573 Windows Popen Helpers
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	574 ---------------------
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	575
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	576 The :class:`STARTUPINFO` class and following constants are only available
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	577 on Windows.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	578
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	579 .. class:: STARTUPINFO()
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	580
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	581 Partial support of the Windows
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	582 `STARTUPINFO <http://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx>`__
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	583 structure is used for :class:`Popen` creation.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	584
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	585 .. attribute:: dwFlags
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	586
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	587 A bit field that determines whether certain :class:`STARTUPINFO`
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	588 attributes are used when the process creates a window. ::
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	589
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	590 si = subprocess.STARTUPINFO()
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	591 si.dwFlags = subprocess.STARTF_USESTDHANDLES \| subprocess.STARTF_USESHOWWINDOW
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	592
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	593 .. attribute:: hStdInput
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	594
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	595 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	596 is the standard input handle for the process. If
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	597 :data:`STARTF_USESTDHANDLES` is not specified, the default for standard
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	598 input is the keyboard buffer.
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	599
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	600 .. attribute:: hStdOutput
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	601
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	602 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	603 is the standard output handle for the process. Otherwise, this attribute
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	604 is ignored and the default for standard output is the console window's
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	605 buffer.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	606
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	607 .. attribute:: hStdError
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	608
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	609 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	610 is the standard error handle for the process. Otherwise, this attribute is
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	611 ignored and the default for standard error is the console window's buffer.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	612
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	613 .. attribute:: wShowWindow
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	614
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	615 If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this attribute
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	616 can be any of the values that can be specified in the ``nCmdShow``
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	617 parameter for the
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	618 `ShowWindow <http://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx>`__
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	619 function, except for ``SW_SHOWDEFAULT``. Otherwise, this attribute is
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	620 ignored.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	621
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	622 :data:`SW_HIDE` is provided for this attribute. It is used when
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	623 :class:`Popen` is called with ``shell=True``.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	624
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	625
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	626 Constants
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	627 ^^^^^^^^^
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	628
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	629 The :mod:`subprocess` module exposes the following constants.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	630
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	631 .. data:: STD_INPUT_HANDLE
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	632
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	633 The standard input device. Initially, this is the console input buffer,
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	634 ``CONIN$``.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	635
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	636 .. data:: STD_OUTPUT_HANDLE
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	637
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	638 The standard output device. Initially, this is the active console screen
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	639 buffer, ``CONOUT$``.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	640
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	641 .. data:: STD_ERROR_HANDLE
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	642
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	643 The standard error device. Initially, this is the active console screen
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	644 buffer, ``CONOUT$``.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	645
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	646 .. data:: SW_HIDE
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	647
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	648 Hides the window. Another window will be activated.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	649
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	650 .. data:: STARTF_USESTDHANDLES
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	651
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	652 Specifies that the :attr:`STARTUPINFO.hStdInput`,
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	653 :attr:`STARTUPINFO.hStdOutput`, and :attr:`STARTUPINFO.hStdError` attributes
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	654 contain additional information.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	655
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	656 .. data:: STARTF_USESHOWWINDOW
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	657
71212 b8f5da066782 Fix closes issue10403 - Let's not use members anymore. Senthil Kumaran <senthil@uthcode.com> parents: 69702 diff changeset	658 Specifies that the :attr:`STARTUPINFO.wShowWindow` attribute contains
69702 9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	659 additional information.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	660
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	661 .. data:: CREATE_NEW_CONSOLE
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	662
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	663 The new process has a new console, instead of inheriting its parent's
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	664 console (the default).
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	665
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	666 This flag is always set when :class:`Popen` is created with ``shell=True``.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	667
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	668 .. data:: CREATE_NEW_PROCESS_GROUP
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	669
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	670 A :class:`Popen` ``creationflags`` parameter to specify that a new process
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	671 group will be created. This flag is necessary for using :func:`os.kill`
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	672 on the subprocess.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	673
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	674 This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified.
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	675
9a31422649f1 Fix #11961. Document STARTUPINFO and creation flag options. Brian Curtin <brian@python.org> parents: 69452 diff changeset	676
47800 70e1a38c9805 Turn section references into proper cross-references. Georg Brandl <georg@python.org> parents: 46510 diff changeset	677 .. _subprocess-replacements:
70e1a38c9805 Turn section references into proper cross-references. Georg Brandl <georg@python.org> parents: 46510 diff changeset	678
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 Replacing Older Functions with the subprocess Module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 ----------------------------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	682 In this section, "a becomes b" means that b can be used as a replacement for a.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	686 All "a" functions in this section fail (more or less) silently if the
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	687 executed program cannot be found; the "b" replacements raise :exc:`OSError`
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	688 instead.
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	689
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	690 In addition, the replacements using :func:`check_output` will fail with a
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	691 :exc:`CalledProcessError` if the requested operation produces a non-zero
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	692 return code. The output is still available as the ``output`` attribute of
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	693 the raised exception.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	695 In the following examples, we assume that the relevant functions have already
0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	696 been imported from the subprocess module.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 Replacing /bin/sh shell backquote
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 output=`mycmd myarg`
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	705 # becomes
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	706 output = check_output(["mycmd", "myarg"])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49357 diff changeset	709 Replacing shell pipeline
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49357 diff changeset	710 ^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714 output=`dmesg \| grep hda`
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	715 # becomes
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716 p1 = Popen(["dmesg"], stdout=PIPE)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
67879 405a44c6dced Merged revisions 88352 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 66159 diff changeset	718 p1.stdout.close() # Allow p1 to receive a SIGPIPE if p2 exits.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 output = p2.communicate()[0]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720
67879 405a44c6dced Merged revisions 88352 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 66159 diff changeset	721 The p1.stdout.close() call after starting the p2 is important in order for p1
405a44c6dced Merged revisions 88352 via svnmerge from Gregory P. Smith <greg@mad-scientist.com> parents: 66159 diff changeset	722 to receive a SIGPIPE if p2 exits before p1.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	724 Alternatively, for trusted input, the shell's own pipeline support may still
76093 2c1ce04ded55 #14481: fix formatting of example in subprocess docs. R David Murray <rdmurray@bitdance.com> parents: 74395 diff changeset	725 be used directly::
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	726
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	727 output=`dmesg \| grep hda`
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	728 # becomes
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	729 output=check_output("dmesg \| grep hda", shell=True)
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	730
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	731
54855 a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	732 Replacing :func:`os.system`
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	733 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 sts = os.system("mycmd" + " myarg")
73094 2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	738 # becomes
2184df0e0f89 Issue #13237: Rearrange subprocess module documentation to emphasise the convenience functions and commonly needed arguments Nick Coghlan <ncoghlan@gmail.com> parents: 71212 diff changeset	739 sts = call("mycmd" + " myarg", shell=True)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 * Calling the program through the shell is usually not required.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 A more realistic example would look like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 try:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 retcode = call("mycmd" + " myarg", shell=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 if retcode < 0:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 print >>sys.stderr, "Child was terminated by signal", -retcode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 else:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 print >>sys.stderr, "Child returned", retcode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 except OSError, e:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 print >>sys.stderr, "Execution failed:", e
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756
54855 a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	757 Replacing the :func:`os.spawn <os.spawnl>` family
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	758 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 P_NOWAIT example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 pid = Popen(["/bin/mycmd", "myarg"]).pid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 P_WAIT example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 retcode = call(["/bin/mycmd", "myarg"])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 Vector example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 os.spawnvp(os.P_NOWAIT, path, args)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 Popen([path] + args[1:])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 Environment example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784
54855 a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	785 Replacing :func:`os.popen`, :func:`os.popen2`, :func:`os.popen3`
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	786 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	790 pipe = os.popen("cmd", 'r', bufsize)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 ==>
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	792 pipe = Popen("cmd", shell=True, bufsize=bufsize, stdout=PIPE).stdout
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	796 pipe = os.popen("cmd", 'w', bufsize)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 ==>
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	798 pipe = Popen("cmd", shell=True, bufsize=bufsize, stdin=PIPE).stdin
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	802 (child_stdin, child_stdout) = os.popen2("cmd", mode, bufsize)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 ==>
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	804 p = Popen("cmd", shell=True, bufsize=bufsize,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 stdin=PIPE, stdout=PIPE, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 (child_stdin, child_stdout) = (p.stdin, p.stdout)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810 (child_stdin,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 child_stdout,
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	812 child_stderr) = os.popen3("cmd", mode, bufsize)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 ==>
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	814 p = Popen("cmd", shell=True, bufsize=bufsize,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815 stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 (child_stdin,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817 child_stdout,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818 child_stderr) = (p.stdin, p.stdout, p.stderr)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	822 (child_stdin, child_stdout_and_stderr) = os.popen4("cmd", mode,
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	823 bufsize)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824 ==>
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	825 p = Popen("cmd", shell=True, bufsize=bufsize,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	829 On Unix, os.popen2, os.popen3 and os.popen4 also accept a sequence as
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	830 the command to execute, in which case arguments will be passed
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	831 directly to the program without shell intervention. This usage can be
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	832 replaced as follows::
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	833
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	834 (child_stdin, child_stdout) = os.popen2(["/bin/ls", "-l"], mode,
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	835 bufsize)
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	836 ==>
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	837 p = Popen(["/bin/ls", "-l"], bufsize=bufsize, stdin=PIPE, stdout=PIPE)
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	838 (child_stdin, child_stdout) = (p.stdin, p.stdout)
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	839
54855 a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	840 Return code handling translates as follows::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	842 pipe = os.popen("cmd", 'w')
54855 a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	843 ...
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	844 rc = pipe.close()
63016 77dfe2a775d1 Merged revisions 82877 via svnmerge from Stefan Krah <stefan@bytereef.org> parents: 62030 diff changeset	845 if rc is not None and rc >> 8:
54855 a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	846 print "There were some errors"
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	847 ==>
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	848 process = Popen("cmd", 'w', shell=True, stdin=PIPE)
54855 a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	849 ...
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	850 process.stdin.close()
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	851 if process.wait() != 0:
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	852 print "There were some errors"
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	853
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	854
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	855 Replacing functions from the :mod:`popen2` module
a57992a63caa Merged revisions 73026,73313,73511,73554 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 53573 diff changeset	856 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862 p = Popen(["somestring"], shell=True, bufsize=bufsize,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863 stdin=PIPE, stdout=PIPE, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864 (child_stdout, child_stdin) = (p.stdout, p.stdin)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	866 On Unix, popen2 also accepts a sequence as the command to execute, in
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	867 which case arguments will be passed directly to the program without
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	868 shell intervention. This usage can be replaced as follows::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869
56295 7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	870 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize,
7e1856167c4a Merged revisions 75143 via svnmerge from Philip Jenvey <pjenvey@underboss.org> parents: 54855 diff changeset	871 mode)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874 stdin=PIPE, stdout=PIPE, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875 (child_stdout, child_stdin) = (p.stdout, p.stdin)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876
50065 ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	877 :class:`popen2.Popen3` and :class:`popen2.Popen4` basically work as
ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	878 :class:`subprocess.Popen`, except that:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879
50065 ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	880 * :class:`Popen` raises an exception if the execution fails.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882 * the capturestderr argument is replaced with the stderr argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	883
50065 ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	884 * ``stdin=PIPE`` and ``stdout=PIPE`` must be specified.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886 * popen2 closes all file descriptors by default, but you have to specify
50065 ae98681058b2 Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from Georg Brandl <georg@python.org> parents: 50008 diff changeset	887 ``close_fds=True`` with :class:`Popen`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888
73131 0b4df6701c4d Issue #13237: further updates to subprocess documentation Nick Coghlan <ncoghlan@gmail.com> parents: 73094 diff changeset	889
69354 f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	890 Notes
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	891 -----
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	892
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	893 .. _converting-argument-sequence:
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	894
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	895 Converting an argument sequence to a string on Windows
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	896 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	897
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	898 On Windows, an args sequence is converted to a string that can be parsed
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	899 using the following rules (which correspond to the rules used by the MS C
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	900 runtime):
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	901
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	902 1. Arguments are delimited by white space, which is either a
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	903 space or a tab.
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	904
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	905 2. A string surrounded by double quotation marks is
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	906 interpreted as a single argument, regardless of white space
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	907 contained within. A quoted string can be embedded in an
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	908 argument.
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	909
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	910 3. A double quotation mark preceded by a backslash is
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	911 interpreted as a literal double quotation mark.
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	912
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	913 4. Backslashes are interpreted literally, unless they
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	914 immediately precede a double quotation mark.
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	915
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	916 5. If backslashes immediately precede a double quotation mark,
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	917 every pair of backslashes is interpreted as a literal
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	918 backslash. If the number of backslashes is odd, the last
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	919 backslash escapes the next double quotation mark as
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	920 described in rule 3.
f38489a3394f Issue #11827: remove mention of list2cmdline in the doc of subprocess Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	921

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/subprocess.rst @ 79675:c0a2294de787 2.7