doctest.py

来自「mallet是自然语言处理、机器学习领域的一个开源项目。」· Python 代码 · 共 1,174 行 · 第 1/3 页

        pass

# Display some tag-and-msg pairs nicely, keeping the tag and its msg
# on the same line when that makes sense.

def _tag_out(printer, *tag_msg_pairs):
    for tag, msg in tag_msg_pairs:
        printer(tag + ":")
        msg_has_nl = msg[-1:] == "\n"
        msg_has_two_nl = msg_has_nl and \
                        msg.find("\n") < len(msg) - 1
        if len(tag) + len(msg) < 76 and not msg_has_two_nl:
            printer(" ")
        else:
            printer("\n")
        printer(msg)
        if not msg_has_nl:
            printer("\n")

# Run list of examples, in context globs.  "out" can be used to display
# stuff to "the real" stdout, and fakeout is an instance of _SpoofOut
# that captures the examples' std output.  Return (#failures, #tries).

def _run_examples_inner(out, fakeout, examples, globs, verbose, name,
                        compileflags):
    import sys, traceback
    OK, BOOM, FAIL = range(3)
    NADA = "nothing"
    stderr = _SpoofOut()
    failures = 0
    for source, want, lineno in examples:
        if verbose:
            _tag_out(out, ("Trying", source),
                          ("Expecting", want or NADA))
        fakeout.clear()
        try:
            exec compile(source, "<string>", "single",
                         compileflags, 1) in globs
            got = fakeout.get()
            state = OK
        except:
            # See whether the exception was expected.
            if want.find("Traceback (innermost last):\n") == 0 or \
               want.find("Traceback (most recent call last):\n") == 0:
                # Only compare exception type and value - the rest of
                # the traceback isn't necessary.
                want = want.split('\n')[-2] + '\n'
                exc_type, exc_val = sys.exc_info()[:2]
                got = traceback.format_exception_only(exc_type, exc_val)[-1]
                state = OK
            else:
                # unexpected exception
                stderr.clear()
                traceback.print_exc(file=stderr)
                state = BOOM

        if state == OK:
            if got == want:
                if verbose:
                    out("ok\n")
                continue
            state = FAIL

        assert state in (FAIL, BOOM)
        failures = failures + 1
        out("*" * 65 + "\n")
        _tag_out(out, ("Failure in example", source))
        out("from line #" + `lineno` + " of " + name + "\n")
        if state == FAIL:
            _tag_out(out, ("Expected", want or NADA), ("Got", got))
        else:
            assert state == BOOM
            _tag_out(out, ("Exception raised", stderr.get()))

    return failures, len(examples)

# Get the future-flags associated with the future features that have been
# imported into globs.

def _extract_future_flags(globs):
    flags = 0
    for fname in __future__.all_feature_names:
        feature = globs.get(fname, None)
        if feature is getattr(__future__, fname):
            flags |= feature.compiler_flag
    return flags

# Run list of examples, in a shallow copy of context (dict) globs.
# Return (#failures, #tries).

def _run_examples(examples, globs, verbose, name, compileflags):
    import sys
    saveout = sys.stdout
    globs = globs.copy()
    try:
        sys.stdout = fakeout = _SpoofOut()
        x = _run_examples_inner(saveout.write, fakeout, examples,
                                globs, verbose, name, compileflags)
    finally:
        sys.stdout = saveout
        # While Python gc can clean up most cycles on its own, it doesn't
        # chase frame objects.  This is especially irksome when running
        # generator tests that raise exceptions, because a named generator-
        # iterator gets an entry in globs, and the generator-iterator
        # object's frame's traceback info points back to globs.  This is
        # easy to break just by clearing the namespace.  This can also
        # help to break other kinds of cycles, and even for cycles that
        # gc can break itself it's better to break them ASAP.
        globs.clear()
    return x

def run_docstring_examples(f, globs, verbose=0, name="NoName",
                           compileflags=None):
    """f, globs, verbose=0, name="NoName" -> run examples from f.__doc__.

    Use (a shallow copy of) dict globs as the globals for execution.
    Return (#failures, #tries).

    If optional arg verbose is true, print stuff even if there are no
    failures.
    Use string name in failure msgs.
    """

    try:
        doc = f.__doc__
        if not doc:
            # docstring empty or None
            return 0, 0
        # just in case CT invents a doc object that has to be forced
        # to look like a string <0.9 wink>
        doc = str(doc)
    except:
        return 0, 0

    e = _extract_examples(doc)
    if not e:
        return 0, 0
    if compileflags is None:
        compileflags = _extract_future_flags(globs)
    return _run_examples(e, globs, verbose, name, compileflags)

def is_private(prefix, base):
    """prefix, base -> true iff name prefix + "." + base is "private".

    Prefix may be an empty string, and base does not contain a period.
    Prefix is ignored (although functions you write conforming to this
    protocol may make use of it).
    Return true iff base begins with an (at least one) underscore, but
    does not both begin and end with (at least) two underscores.

    >>> is_private("a.b", "my_func")
    0
    >>> is_private("____", "_my_func")
    1
    >>> is_private("someclass", "__init__")
    0
    >>> is_private("sometypo", "__init_")
    1
    >>> is_private("x.y.z", "_")
    1
    >>> is_private("_x.y.z", "__")
    0
    >>> is_private("", "")  # senseless but consistent
    0
    """

    return base[:1] == "_" and not base[:2] == "__" == base[-2:]

# Determine if a class of function was defined in the given module.

def _from_module(module, object):
    if _isfunction(object):
        return module.__dict__ is object.func_globals
    if _isclass(object):
        return module.__name__ == object.__module__
    raise ValueError("object must be a class or function")

class Tester:
    """Class Tester -- runs docstring examples and accumulates stats.

In normal use, function doctest.testmod() hides all this from you,
so use that if you can.  Create your own instances of Tester to do
fancier things.

Methods:
    runstring(s, name)
        Search string s for examples to run; use name for logging.
        Return (#failures, #tries).

    rundoc(object, name=None)
        Search object.__doc__ for examples to run; use name (or
        object.__name__) for logging.  Return (#failures, #tries).

    rundict(d, name, module=None)
        Search for examples in docstrings in all of d.values(); use name
        for logging.  Exclude functions and classes not defined in module
        if specified.  Return (#failures, #tries).

    run__test__(d, name)
        Treat dict d like module.__test__.  Return (#failures, #tries).

    summarize(verbose=None)
        Display summary of testing results, to stdout.  Return
        (#failures, #tries).

    merge(other)
        Merge in the test results from Tester instance "other".

>>> from doctest import Tester
>>> t = Tester(globs={'x': 42}, verbose=0)
>>> t.runstring(r'''
...      >>> x = x * 2
...      >>> print x
...      42
... ''', 'XYZ')
*****************************************************************
Failure in example: print x
from line #2 of XYZ
Expected: 42
Got: 84
(1, 2)
>>> t.runstring(">>> x = x * 2\\n>>> print x\\n84\\n", 'example2')
(0, 2)
>>> t.summarize()
*****************************************************************
1 items had failures:
   1 of   2 in XYZ
***Test Failed*** 1 failures.
(1, 4)
>>> t.summarize(verbose=1)
1 items passed all tests:
   2 tests in example2
*****************************************************************
1 items had failures:
   1 of   2 in XYZ
4 tests in 2 items.
3 passed and 1 failed.
***Test Failed*** 1 failures.
(1, 4)
>>>
"""

    def __init__(self, mod=None, globs=None, verbose=None,
                 isprivate=None):
        """mod=None, globs=None, verbose=None, isprivate=None

See doctest.__doc__ for an overview.

Optional keyword arg "mod" is a module, whose globals are used for
executing examples.  If not specified, globs must be specified.

Optional keyword arg "globs" gives a dict to be used as the globals
when executing examples; if not specified, use the globals from
module mod.

In either case, a copy of the dict is used for each docstring
examined.

Optional keyword arg "verbose" prints lots of stuff if true, only
failures if false; by default, it's true iff "-v" is in sys.argv.

Optional keyword arg "isprivate" specifies a function used to determine
whether a name is private.  The default function is doctest.is_private;
see its docs for details.
"""

        if mod is None and globs is None:
            raise TypeError("Tester.__init__: must specify mod or globs")
        if mod is not None and not _ismodule(mod):
            raise TypeError("Tester.__init__: mod must be a module; " +
                            `mod`)
        if globs is None:
            globs = mod.__dict__
        self.globs = globs

        if verbose is None:
            import sys
            verbose = "-v" in sys.argv
        self.verbose = verbose

        if isprivate is None:
            isprivate = is_private
        self.isprivate = isprivate

        self.name2ft = {}   # map name to (#failures, #trials) pair

        self.compileflags = _extract_future_flags(globs)

    def runstring(self, s, name):
        """
        s, name -> search string s for examples to run, logging as name.

        Use string name as the key for logging the outcome.
        Return (#failures, #examples).

        >>> t = Tester(globs={}, verbose=1)
        >>> test = r'''
        ...    # just an example
        ...    >>> x = 1 + 2
        ...    >>> x
        ...    3
        ... '''
        >>> t.runstring(test, "Example")
        Running string Example
        Trying: x = 1 + 2
        Expecting: nothing
        ok
        Trying: x
        Expecting: 3
        ok
        0 of 2 examples failed in string Example
        (0, 2)
        """

        if self.verbose:
            print "Running string", name
        f = t = 0
        e = _extract_examples(s)
        if e:
            f, t = _run_examples(e, self.globs, self.verbose, name,
                                 self.compileflags)
        if self.verbose:
            print f, "of", t, "examples failed in string", name
        self.__record_outcome(name, f, t)
        return f, t

    def rundoc(self, object, name=None):
        """
        object, name=None -> search object.__doc__ for examples to run.

        Use optional string name as the key for logging the outcome;
        by default use object.__name__.
        Return (#failures, #examples).
        If object is a class object, search recursively for method
        docstrings too.
        object.__doc__ is examined regardless of name, but if object is
        a class, whether private names reached from object are searched
        depends on the constructor's "isprivate" argument.

        >>> t = Tester(globs={}, verbose=0)
        >>> def _f():
        ...     '''Trivial docstring example.
        ...     >>> assert 2 == 2
        ...     '''
        ...     return 32
        ...
        >>> t.rundoc(_f)  # expect 0 failures in 1 example
        (0, 1)
        """

        if name is None:
            try:
                name = object.__name__
            except AttributeError:
                raise ValueError("Tester.rundoc: name must be given "
                    "when object.__name__ doesn't exist; " + `object`)
        if self.verbose:
            print "Running", name + ".__doc__"
        f, t = run_docstring_examples(object, self.globs, self.verbose, name,
                                      self.compileflags)
        if self.verbose:
            print f, "of", t, "examples failed in", name + ".__doc__"
        self.__record_outcome(name, f, t)
        if _isclass(object):
            # In 2.2, class and static methods complicate life.  Build
            # a dict "that works", by hook or by crook.
            d = {}
            for tag, kind, homecls, value in _classify_class_attrs(object):

                if homecls is not object:
                    # Only look at names defined immediately by the class.
                    continue

                elif self.isprivate(name, tag):
                    continue

                elif kind == "method":
                    # value is already a function
                    d[tag] = value

                elif kind == "static method":
                    # value isn't a function, but getattr reveals one
                    d[tag] = getattr(object, tag)

                elif kind == "class method":
                    # Hmm.  A classmethod object doesn't seem to reveal
                    # enough.  But getattr turns it into a bound method,
                    # and from there .im_func retrieves the underlying
                    # function.
                    d[tag] = getattr(object, tag).im_func

                elif kind == "property":