Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(158891)

Side by Side Diff: Doc/library/subprocess.rst

Issue 24420: Documentation regressions from adding subprocess.run()
Patch Set: Created 4 years, 6 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`subprocess` --- Subprocess management 1 :mod:`subprocess` --- Subprocess management
2 =========================================== 2 ===========================================
3 3
4 .. module:: subprocess 4 .. module:: subprocess
5 :synopsis: Subprocess management. 5 :synopsis: Subprocess management.
6 .. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se> 6 .. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se>
7 .. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se> 7 .. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
8 8
9 9
10 The :mod:`subprocess` module allows you to spawn new processes, connect to their 10 The :mod:`subprocess` module allows you to spawn new processes, connect to their
(...skipping 807 matching lines...) Expand 10 before | Expand all | Expand 10 after
818 Older high-level API 818 Older high-level API
819 -------------------- 819 --------------------
820 820
821 Prior to Python 3.5, these three functions comprised the high level API to 821 Prior to Python 3.5, these three functions comprised the high level API to
822 subprocess. You can now use :func:`run` in many cases, but lots of existing code 822 subprocess. You can now use :func:`run` in many cases, but lots of existing code
823 calls these functions. 823 calls these functions.
824 824
825 .. function:: call(args, *, stdin=None, stdout=None, stderr=None, shell=False, t imeout=None) 825 .. function:: call(args, *, stdin=None, stdout=None, stderr=None, shell=False, t imeout=None)
826 826
827 Run the command described by *args*. Wait for command to complete, then 827 Run the command described by *args*. Wait for command to complete, then
828 return the :attr:`returncode` attribute. 828 return the :attr:`~Popen.returncode` attribute.
829 829
830 This is equivalent to:: 830 This is equivalent to::
831 831
832 run(...).returncode 832 run(...).returncode
833 833
834 (except that the *input* and *check* parameters are not supported) 834 (except that the *input* and *check* parameters are not supported)
835
836 The arguments shown above are merely the most
837 common ones. The full function signature is largely the
838 same as that of the :class:`Popen` constructor - this function passes all
839 supplied arguments other than *timeout* directly through to that interface.
835 840
836 .. note:: 841 .. note::
837 842
838 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this 843 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
839 function. The child process will block if it generates enough 844 function. The child process will block if it generates enough
840 output to a pipe to fill up the OS pipe buffer as the pipes are 845 output to a pipe to fill up the OS pipe buffer as the pipes are
841 not being read from. 846 not being read from.
842 847
843 .. versionchanged:: 3.3 848 .. versionchanged:: 3.3
844 *timeout* was added. 849 *timeout* was added.
845 850
846 .. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=Fa lse, timeout=None) 851 .. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=Fa lse, timeout=None)
847 852
848 Run command with arguments. Wait for command to complete. If the return 853 Run command with arguments. Wait for command to complete. If the return
849 code was zero then return, otherwise raise :exc:`CalledProcessError`. The 854 code was zero then return, otherwise raise :exc:`CalledProcessError`. The
850 :exc:`CalledProcessError` object will have the return code in the 855 :exc:`CalledProcessError` object will have the return code in the
851 :attr:`~CalledProcessError.returncode` attribute. 856 :attr:`~CalledProcessError.returncode` attribute.
852 857
853 This is equivalent to:: 858 This is equivalent to::
854 859
855 run(..., check=True) 860 run(..., check=True)
856 861
857 (except that the *input* parameter is not supported) 862 (except that the *input* parameter is not supported)
863
864 The arguments shown above are merely the most
865 common ones. The full function signature is largely the
866 same as that of the :class:`Popen` constructor - this function passes all
867 supplied arguments other than *timeout* directly through to that interface.
858 868
859 .. note:: 869 .. note::
860 870
861 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this 871 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
862 function. The child process will block if it generates enough 872 function. The child process will block if it generates enough
863 output to a pipe to fill up the OS pipe buffer as the pipes are 873 output to a pipe to fill up the OS pipe buffer as the pipes are
864 not being read from. 874 not being read from.
865 875
866 .. versionchanged:: 3.3 876 .. versionchanged:: 3.3
867 *timeout* was added. 877 *timeout* was added.
868 878
869 879
870 .. function:: check_output(args, *, input=None, stdin=None, stderr=None, shell=F alse, universal_newlines=False, timeout=None) 880 .. function:: check_output(args, *[, input], stdin=None, stderr=None, shell=Fals e, universal_newlines=False, timeout=None)
berkerpeksag 2015/06/25 23:31:14 I think we can now remove *input* from the signatu
Martin Panter 2015/06/26 02:32:56 Yes I agree. I might tweak the new paragraph and t
berkerpeksag 2015/06/26 13:16:58 Yes, that would be better.
871 881
872 Run command with arguments and return its output. 882 Run command with arguments and return its output.
873 883
874 If the return code was non-zero it raises a :exc:`CalledProcessError`. The 884 If the return code was non-zero it raises a :exc:`CalledProcessError`. The
875 :exc:`CalledProcessError` object will have the return code in the 885 :exc:`CalledProcessError` object will have the return code in the
876 :attr:`~CalledProcessError.returncode` attribute and any output in the 886 :attr:`~CalledProcessError.returncode` attribute and any output in the
877 :attr:`~CalledProcessError.output` attribute. 887 :attr:`~CalledProcessError.output` attribute.
878 888
879 This is equivalent to:: 889 This is equivalent to::
880 890
881 run(..., check=True, stdout=PIPE).stdout 891 run(..., check=True, stdout=PIPE).stdout
892
893 The arguments shown above are merely the most common ones.
894 The full function signature is largely the same as that of :func:`run` -
895 most arguments are passed directly through to that interface.
896 The differences are that explicitly passing ``input=None`` is not
897 supported, and that *stdout* is not permitted as an argument, as
898 it is used internally to collect the output from the subprocess.
882 899
883 By default, this function will return the data as encoded bytes. The actual 900 By default, this function will return the data as encoded bytes. The actual
884 encoding of the output data may depend on the command being invoked, so the 901 encoding of the output data may depend on the command being invoked, so the
885 decoding to text will often need to be handled at the application level. 902 decoding to text will often need to be handled at the application level.
886 903
887 This behaviour may be overridden by setting *universal_newlines* to 904 This behaviour may be overridden by setting *universal_newlines* to
888 ``True`` as described above in :ref:`frequently-used-arguments`. 905 ``True`` as described above in :ref:`frequently-used-arguments`.
889 906
890 To also capture standard error in the result, use 907 To also capture standard error in the result, use
891 ``stderr=subprocess.STDOUT``:: 908 ``stderr=subprocess.STDOUT``::
(...skipping 284 matching lines...) Expand 10 before | Expand all | Expand 10 after
1176 every pair of backslashes is interpreted as a literal 1193 every pair of backslashes is interpreted as a literal
1177 backslash. If the number of backslashes is odd, the last 1194 backslash. If the number of backslashes is odd, the last
1178 backslash escapes the next double quotation mark as 1195 backslash escapes the next double quotation mark as
1179 described in rule 3. 1196 described in rule 3.
1180 1197
1181 1198
1182 .. seealso:: 1199 .. seealso::
1183 1200
1184 :mod:`shlex` 1201 :mod:`shlex`
1185 Module which provides function to parse and escape command lines. 1202 Module which provides function to parse and escape command lines.
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+