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

2016-10-25 Thread Martin Panter

Changes by Martin Panter :


--
resolution:  -> fixed
stage: commit review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-25 Thread Roundup Robot

Roundup Robot added the comment:

New changeset 720865fa61a4 by Martin Panter in branch '3.5':
Issue #26240: Clean up the subprocess module doc string
https://hg.python.org/cpython/rev/720865fa61a4

New changeset 8358c68579e9 by Martin Panter in branch '3.6':
Issue #26240: Merge subprocess doc string from 3.5 into 3.6
https://hg.python.org/cpython/rev/8358c68579e9

New changeset 0dd8b3f133f9 by Martin Panter in branch 'default':
Issue #26240: Merge subprocess doc string from 3.6
https://hg.python.org/cpython/rev/0dd8b3f133f9

New changeset 5a1edf5701f1 by Martin Panter in branch '2.7':
Issue #26240: Clean up the subprocess module doc string
https://hg.python.org/cpython/rev/5a1edf5701f1

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-21 Thread Martin Panter

Changes by Martin Panter :


Added file: http://bugs.python.org/file45180/subprocess3-2.7.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-21 Thread Martin Panter

Martin Panter added the comment:

Here are corresponding patches for 3.5 and 2.7.

--
stage: patch review -> commit review
Added file: http://bugs.python.org/file45179/subprocess3-3.5.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-20 Thread Martin Panter

Martin Panter added the comment:

V3 looks good to me

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-20 Thread Tim Mitchell

Tim Mitchell added the comment:

Changes as per Martins review.

--
Added file: http://bugs.python.org/file45159/subprocess3.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-19 Thread Martin Panter

Martin Panter added the comment:

.
I left some comments on the code review.

Also, I’m not sure about the links to the online documentation. We don’t do 
this for other modules as far as I know. The pydoc module and help() commands 
already add their own links, which can be configured via PYTHONDOCS.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-18 Thread Tim Mitchell

Tim Mitchell added the comment:

Am now working from tip of default in mercurial (Python 3.6).

* Removed all changes to subprocess.rst.

subprocess.__doc__
* Trimmed down even further - removed function signatures.
* added note to see Python docs for complete description.

Exception docs
* just list attributes rather than describing them - they are pretty 
self-explanatory.

Popen.__doc__ 
* Trimmed down to just list arguments with 1 or 2 liner descriptions. 
* Added note to see Python docs for complete description.
* added encoding and errors arguments

--
Added file: http://bugs.python.org/file45140/subprocess2.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-18 Thread 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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-18 Thread Tim Mitchell

Tim Mitchell added the comment:

hg patch with changes forthcoming

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-17 Thread Antony Lee

Changes by Antony Lee :


--
nosy:  -Antony.Lee

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-17 Thread Berker Peksag

Berker Peksag added the comment:

Thanks for the patch, Tim.

> Changed true -> :const:`True` in subprocess.rst.

This is out of scope for this issue and I actually prefer the current form.

Having method and class signatures in subprocess.__doc__ would make it less 
maintainable. I'd prefer having a short docstring that describes what the 
modules does, and what its modern API look like.

I don't think we should duplicate documentation of CalledProcessError, 
TimeoutExpired and Popen in their docstrings. Perhaps it would be better to 
just document which parameters are POSIX only.

Also, did you use the GitHub mirror to create the patch? If so, please use the 
official Mercurial repository: 
https://docs.python.org/devguide/setup.html#checkout Rietveld doesn't like 
patches created from the git repository so it was a bit hard to review the 
patch without using Rietveld. Thanks!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-17 Thread Berker Peksag

Changes by Berker Peksag :


--
nosy: +berker.peksag
stage: needs patch -> patch review
versions: +Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-17 Thread Tim Mitchell

Tim Mitchell added the comment:

Have stripped down the module __doc__ to a list of contents.
I chose to indent the descriptions of each argument to Popen. I know this is 
non-standard but it is such a long ramble otherwise.

Changed true -> :const:`True` in subprocess.rst.

--
keywords: +patch
nosy: +tim.mitchell
Added file: http://bugs.python.org/file45126/subprocess-docs.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-10-03 Thread Mariatta Wijaya

Changes by Mariatta Wijaya :


--
nosy: +Mariatta

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-09-12 Thread Robert Collins

Changes by Robert Collins :


--
nosy: +rbcollins

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-03-19 Thread Ezio Melotti

Changes by Ezio Melotti :


--
keywords: +easy
nosy: +ezio.melotti
type:  -> enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-02-05 Thread Terry J. Reedy

Terry J. Reedy added the comment:

I agree. The module docstring should briefly describe the module and maybe list 
the contents, a line for each.  The itertools docstring does the latter; the 
math docstring does not, though I would not mind if it did.

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-01-29 Thread Martin Panter

Martin Panter added the comment:

IMO the doc strings should be reduced down so that it is a concise summary, and 
divided or merged into doc strings of each class, method, function. Less 
important details should be moved to the main RST documentation (if they aren’t 
already there).

Regarding list2cmdline(), see the comment next to __all__ in the source code, 
and Issue 11827. BTW modifying __all__ would not automatically affect what is 
written in the RST files, which is where the “official” HTML docs come from :)

--
nosy: +martin.panter
stage:  -> needs patch
versions: +Python 2.7, Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com



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

2016-01-29 Thread Antony Lee

New submission from Antony Lee:

subprocess.__doc__ currently contains copies for the docstrings of a bunch of 
functions in the module (... but not subprocess.run).  The docs for the Popen 
class should be moved into that class' docstring.  The module's docstring also 
mentions the list2cmdline "method" (actually a function, and the qualifier 
"method"/"function" is missing the second time this function is mentioned ("The 
list2cmdline is designed ...")), but that function doesn't appear in `__all__` 
and thus not in the official HTML docs (yes, I know pydoc 
subprocess.list2cmdline works).

--
assignee: docs@python
components: Documentation
messages: 259238
nosy: Antony.Lee, docs@python
priority: normal
severity: normal
status: open
title: Docstring of the subprocess module should be cleaned up
versions: Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com