[docs] [issue26240] Docstring of the subprocess module should be cleaned up

[Martin Panter]

Martin Panter added the comment:

Thanks for tackling this one Tim. I agree with Berker that the :const:`True` changes are out of scope (some introduce errors and inaccuracies).

 class CalledProcessError(SubprocessError):
-    """Raised when a check_call() or check_output() process returns non-zero.
+    """Raised when a process run by check_call() or check_output() process
+    returns a non-zero exit status.

New text has stray “process” noun. The old text was good enough IMO.

+      output:      Output of the child process if it was captured by run() or
+                   check_output(). Otherwise, None.
     check_output() will also store the output in the output attribute.

I think that last paragraph is redundant and strange now that you already described the “output” attribute.

 class TimeoutExpired(SubprocessError):
+    Attributes:

The “cmd” attribute is missing from the list.

 class Popen(object):

Your patch seems to be based on 3.6 or 3.7, but you have omitted the new “encoding” etc parameters from the signature (and list of constructor parameters). What about just relying on the automatic signature for __init__()?

+    """ [. . .]
+      universal_newlines:
+        If universal_newlines is True, the file objects stdout and stderr are
+        opened as a text file, but lines may be terminated by any of '\n',

“opened as text files” would read better I think.

The escape codes will be translated to literal newlines etc in the doc string. The best solution is probably to make it a raw string: r""". . .""".

This universal_newlines entry has lots of details about newline translation of stdout and stderr, but fails to mention the translation of stdin. And I think the details about the child decoding its input should be added to the RST documentation before we consider adding it to the doc string.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue26240>
_______________________________________