doctest, sys.stderr, SystemExit and unused return values

[Steven Bethard]

I have an optparse-like module and though I have a full unittest-style
suite of tests for it, I'd also like to be able to run doctest on the
documentation to make sure my examples all work. However, I see that
doctest (1) doesn't capture anything from sys.stderr, and (2) unlike the
normal interpreter, generates a traceback for SystemExit.

Here's what some of my tests look like and the doctest output I get::

========== in my documentation ==========

>>parser.print_help()

usage: PROG [-h] [-w W] [-x X [X ...]] [y] [z [z ...]]

optional arguments:
-h, --help show this help message and exit
-w W w help
-x X [X ...] x help

positional arguments:
y y help
z z help

========== the doctest output ==========
Failed example:
parser.print_help()
Expected:
usage: PROG [-h] [-w W] [-x X [X ...]] [y] [z [z ...]]
========== in my documentation ==========

>>parser.parse_args('xyz --b 42'.split())

usage: PROG xyz [-h] [--x XXX] [-y] z
PROG xyz: error: no such option: --b

========== the doctest output ==========
Failed example:
parser.parse_args('xyz --b 42'.split())
Exception raised:
Traceback (most recent call last):
...
SystemExit: 2

Just like with optparse, calling ``print_help()`` and ``parse_args()``
prints to sys.stderr, and ``parse_args()`` raises SystemExit when it
encounters an error.

Is there a way to get these tests to pass?
On a related note, my examples currently use a lot of ``_ =`` because,
like optparse, I quite frequently don't care about the return value of
calls to add arguments, e.g.::

>>parser = argparse.ArgumentParser(prog='PROG')
_ = parser.add_optional('--foo', help='foo help')
_ = parser.add_positional('bar', help='bar help')
values = parser.parse_args('--foo spam badger'.split())
values.foo

'spam'

>>values.bar

'badger'

Is there any way to avoid having to write the ``_ =`` without getting an
error like::

Failed example:
parser.add_optional('--foo', help='foo help')
Expected nothing
Got:
Optional('--foo', dest='foo', action=None, ...

I don't want to include the whole Optional repr() string because it's
long and it distracts from the point of the example.

STeVe