doctest docstring examples

docstr_check.py

"""
refguide_check.py [OPTIONS] [-- ARGS]

Check for a Scipy submodule whether the objects in its __all__ dict
correspond to the objects included in the reference guide.

Example of usage::

    $ python refguide_check.py optimize

Note that this is a helper script to be able to check if things are missing;
the output of this script does need to be checked manually.  In some cases
objects are left out of the refguide for a good reason (it's an alias of
another function, or deprecated, or ...)

"""
from __future__ import print_function

import sys
import re
import copy
import inspect
import doctest
import warnings

from argparse import ArgumentParser, REMAINDER

import numpy as np
import mock

import scipy
from scipy import (cluster, constants, fftpack, integrate, interpolate, io,
                   linalg, misc, ndimage, odr, optimize, signal, sparse,
                   spatial, special, stats)

def get_all_dict(module):
    """Return a copy of the __all__ dict with irrelevant items removed."""
    all = copy.deepcopy(module.__all__)
    for name in ['absolute_import', 'division', 'print_function']:
        try:
            all.remove(name)
        except ValueError:
            pass

    # somehow some modules survive the first iteration (?)
    for _ in range(2):
        for name in all:
            if inspect.ismodule(getattr(module, name)):
                all.remove(name)

    return all


class DTRunner(doctest.DocTestRunner):
    def report_failure(self, out, test, example, got):
        # do not complain if output does not match
        pass


def main(argv):
    parser = ArgumentParser(usage=__doc__.lstrip())
    parser.add_argument("module_name", metavar="ARGS", default=[],
                        nargs=REMAINDER, help="Valid Scipy submodule name")
    args = parser.parse_args(argv)

    module_name = args.module_name[0]
    module = getattr(scipy, module_name)

    for name in get_all_dict(module):
        obj = getattr(module, name)

        finder = doctest.DocTestFinder()       
        tests = finder.find(obj, name)

        print("\n>>>", name)

        runner = DTRunner()
        for t in tests:
            # suppress popping up MPL figures
            for j, ex in enumerate(t.examples):
                if 'show()' in ex.source:
                    t.examples[j].source = ex.source.replace('show()', 'show')
            res = runner.run(t)


if __name__ == '__main__':
    main(argv=sys.argv[1:])

(based on scipy/tools/reguide_check.py)