classification
Title: popen2.Popen3 class (Unix) documentation misleading / confusing
Type: behavior Stage:
Components: Documentation Versions: Python 2.6, Python 2.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, mtomczak
Priority: low Keywords:

Created on 2007-12-11 17:12 by mtomczak, last changed 2008-01-06 14:34 by georg.brandl. This issue is now closed.

Messages (2)
msg58440 - (view) Author: Mark Tomczak (mtomczak) Date: 2007-12-11 17:12
The help documentation for the popen2.Popen3 class includes the
following information:

    class Popen3
     |  Class representing a child process.  Normally instances are created
     |  by the factory functions popen2() and popen3().

This information is misleading because the function popen2.popen3
actually returns a tuple of file objects (child_stdout, child_stdin,
child_stderr), not an instance of class Popen3. Additionally, some of
the properties of class Popen3 are monkey-patched into the instance when
it is created and so do not appear in a dir(popen2.Popen3) call on the
class itself. This means that some automatic documentation generators
seem to fail to list these properties of the runtime Popen3 instance, as
they are not apparent in the class definition.

I suggest adding a note in the documentation of popen2.Popen3 to refer
users to the manual page http://docs.python.org/lib/popen3-objects.html.
An example of usage that takes into account the monkey-patched
properties would also be helpful.
msg59376 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-01-06 14:34
I clarified the docstring in r59771. I won't extend it, however, since
most types don't announce their attributes in the docstring. For that
you should always consult the code or the official docs.
History
Date User Action Args
2008-01-06 14:34:54georg.brandlsetstatus: open -> closed
resolution: fixed
messages: + msg59376
2008-01-06 10:13:33georg.brandlsetassignee: georg.brandl
nosy: + georg.brandl
2008-01-03 23:13:16christian.heimessetpriority: low
versions: + Python 2.6, - Python 2.4, Python 2.3, Python 2.2.3, Python 2.2.2, Python 2.2.1, Python 2.2, Python 2.1.2, Python 2.1.1
2007-12-11 17:12:04mtomczakcreate