[svn r37741] monster checking for

* unifying IO capturing methods
* py.io.StdCapture and py.io.StdCaptureFD
  (and both have a classmethod 'call' that is
  a shortcut for capturing output while
  executing a function)
* removing lots of duplicate code
* providing some examples in py/doc/io.txt

at least tests on win32 and linux seem
to pass all for me.

--HG--
branch : trunk

py/doc/TODO.txt

@@ -97,7 +97,7 @@ testing
   os.fork to work))
 
 * see why startcapture() used to not use FD-based 
-  "py.io.OutErrCapture" to isolate standard output. 
+  "py.io.StdCaptureFD" to isolate standard output. 
   use that check if all py and PyPy tests pass
   as good as they do without. 
 

py/doc/index.txt

@@ -11,7 +11,9 @@ py.test and the py lib - documentation
 
 `py.code`_: High-level access/manipulation of Python code and traceback objects. 
 
-`py.xml`_ a fast'n'easy way to generate xml/html documents (including CSS-styling) 
+`py.xml`_ for generating in-memory xml/html object trees 
+
+`py.io`_ Helper Classes for Capturing of Input/Output 
 
 `py.log`_ an alpha document about the ad-hoc logging facilities 
 

py/doc/io.txt

@@ -0,0 +1,45 @@
+=======
+py.io
+=======
+
+.. contents::
+.. sectnum::
+
+The 'py' lib provides helper classes for capturing IO during
+execution of a program. 
+
+IO Capturing examples
+===============================================
+
+:api:`py.io.StdCapture`
+---------------------------
+
+Basic Example: 
+
+  >>> import py
+  >>> capture = py.io.StdCapture()
+  >>> print "hello"
+  >>> out,err = capture.reset()
+  >>> out.strip() == "hello"
+  True
+
+For calling functions you may use a shortcut: 
+  >>> import py
+  >>> def f(): print "hello"
+  >>> res, out, err = py.io.StdCapture.call(f)
+  >>> out.strip() == "hello"
+  True
+
+:api:`py.io.StdCaptureFD`
+---------------------------
+
+If you also want to capture writes to the stdout/stdin
+filedescriptors you may invoke: 
+
+  >>> import py, sys
+  >>> capture = py.io.StdCaptureFD()
+  >>> sys.stdout.write("hello")
+  >>> sys.stderr.write("world")
+  >>> out,err = capture.reset()
+  >>> out.strip() + err.strip() == "helloworld"
+  True