##############################################################################
#
# Copyright (c) 2003 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Extension to use doctest tests as unit tests

This module provides a DocTestSuite contructor for converting doctest
tests to unit tests.

$Id$
"""

from StringIO import StringIO
import doctest
import os
import pdb
import sys
import tempfile
import unittest


class DocTestTestCase(unittest.TestCase):
    """A test case that wraps a test function.

    This is useful for slipping pre-existing test functions into the
    PyUnit framework. Optionally, set-up and tidy-up functions can be
    supplied. As with TestCase, the tidy-up ('tearDown') function will
    always be called if the set-up ('setUp') function ran successfully.
    """

    def __init__(self, tester, name, doc, filename, lineno,
                 setUp=None, tearDown=None):
        unittest.TestCase.__init__(self)
        (self.__tester, self.__name, self.__doc,
         self.__filename, self.__lineno,
         self.__setUp, self.__tearDown
         ) = tester, name, doc, filename, lineno, setUp, tearDown

    def setUp(self):
        if self.__setUp is not None:
            self.__setUp()

    def tearDown(self):
        if self.__tearDown is not None:
            self.__tearDown()

    def setDebugModeOn(self):
        self.__tester.optionflags |= (
            doctest.RUN_DEBUGGER_ON_UNEXPECTED_EXCEPTION)

    def runTest(self):
        old = sys.stdout
        new = StringIO()
        try:
            sys.stdout = new
            failures, tries = self.__tester.runstring(self.__doc, self.__name)
        finally:
            sys.stdout = old

        if failures:
            lname = '.'.join(self.__name.split('.')[-1:])
            lineno = self.__lineno or "0 (don't know line no)"
            raise self.failureException(
                'Failed doctest test for %s\n'
                '  File "%s", line %s, in %s\n\n%s'
                % (self.__name, self.__filename, lineno, lname, new.getvalue())
                )

    def id(self):
        return self.__name

    def __repr__(self):
        name = self.__name.split('.')
        return "%s (%s)" % (name[-1], '.'.join(name[:-1]))

    __str__ = __repr__

    def shortDescription(self):
        return "Doctest: " + self.__name

def DocFileSuite(package, *paths):
    """Creates a suite of doctest files.
    
    package is the source package containing the doctest files.
    
    Each subsequent argument is a string specifying the file name of the
    doctest relative to the package.
    
    The suite contains one function test case (unittest.FunctionTestCase) for 
    each doctest source file. The function name is derrived from the doctest
    file name by replacing '.' characters with '_'. E.g. if the doctest file is
    'utility.txt' and the package is foo.bar, the test function name will be 
    'foo.bar.utility_txt'.
    """
    
    # It's not entirely obvious how to connection this single string
    # with unittest.  For now, re-use the _utest() function that comes
    # standard with doctest in Python 2.3.  One problem is that the
    # error indicator doesn't point to the line of the doctest file
    # that failed.
    import os, doctest, new
    t = doctest.Tester(globs={})
    suite = unittest.TestSuite()
    dir = os.path.split(package.__file__)[0]
    for path in paths:
        from re import sub
        funcName = path.replace('.', '_')
        funcName = package.__name__ + '.' + sub('\\\|/', '.', funcName)
        path = os.path.join(dir, path)
        source = open(path).read()
        def runit(path=path, source=source):
            doctest._utest(t, path, source, path, 0)
        runit = new.function(runit.func_code, runit.func_globals, funcName,
                             runit.func_defaults, runit.func_closure)
        f = unittest.FunctionTestCase(runit,
                                      description="doctest from %s" % path)
        suite.addTest(f)
    return suite

def DocTestSuite(module=None,
                 setUp=lambda: None,
                 tearDown=lambda: None,
                 ):
    """Convert doctest tests for a mudule to a unittest test suite

    This tests convers each documentation string in a module that
    contains doctest tests to a unittest test case. If any of the
    tests in a doc string fail, then the test case fails. An error is
    raised showing the name of the file containing the test and a
    (sometimes approximate) line number.

    A module argument provides the module to be tested. The argument
    can be either a module or a module name.

    If no argument is given, the calling module is used.

    """
    module = _normalizeModule(module)
    tests = _findTests(module)

    if not tests:
        raise ValueError(module, "has no tests")

    tests.sort()
    suite = unittest.TestSuite()
    tester = doctest.Tester(module)
    for name, doc, filename, lineno in tests:
        if not filename:
            filename = module.__file__
            if filename.endswith(".pyc"):
                filename = filename[:-1]
            elif filename.endswith(".pyo"):
                filename = filename[:-1]

        suite.addTest(DocTestTestCase(
            tester, name, doc, filename, lineno,
            setUp, tearDown))


    return suite

def _normalizeModule(module):
    # Normalize a module
    if module is None:
        # Test the calling module
        module = sys._getframe(2).f_globals['__name__']
        module = sys.modules[module]

    elif isinstance(module, (str, unicode)):
        module = __import__(module, globals(), locals(), ["*"])

    return module

def _doc(name, object, tests, prefix, filename='', lineno=''):
    doc = getattr(object, '__doc__', '')
    if doc and doc.find('>>>') >= 0:
        tests.append((prefix+name, doc, filename, lineno))


def _findTests(module, prefix=None):
    if prefix is None:
        prefix = module.__name__
    dict = module.__dict__
    tests = []
    _doc(prefix, module, tests, '',
         lineno="1 (or below)")
    prefix = prefix and (prefix + ".")
    _find(dict.items(), module, dict, tests, prefix)
    return tests

def _find(items, module, dict, tests, prefix, minlineno=0):
    for name, object in items:

        # Only interested in named objects
        if not hasattr(object, '__name__'):
            continue

        if hasattr(object, 'func_globals'):
            # Looks like a func
            if object.func_globals is not dict:
                # Non-local func
                continue
            code = getattr(object, 'func_code', None)
            filename = getattr(code, 'co_filename', '')
            lineno = getattr(code, 'co_firstlineno', -1) + 1
            if minlineno:
                minlineno = min(lineno, minlineno)
            else:
                minlineno = lineno
            _doc(name, object, tests, prefix, filename, lineno)

        elif hasattr(object, "__module__"):
            # Maybe a class-like things. In which case, we care
            if object.__module__ != module.__name__:
                continue # not the same module
            if not (hasattr(object, '__dict__')
                    and hasattr(object, '__bases__')):
                continue # not a class

            lineno = _find(object.__dict__.items(), module, dict, tests,
                           prefix+name+".")

            _doc(name, object, tests, prefix,
                 lineno="%s (or above)" % (lineno-3))

    return minlineno




####################################################################
# doctest debugger

def _expect(expect):
    # Return the expected output, if any
    if expect:
        expect = "\n# ".join(expect.split("\n"))
        expect = "\n# Expect:\n# %s" % expect
    return expect

def testsource(module, name):
    """Extract the test sources from a doctest test docstring as a script

    Provide the module (or dotted name of the module) containing the
    test to be debugged and the name (within the module) of the object
    with the doc string with tests to be debugged.

    """
    module = _normalizeModule(module)
    tests = _findTests(module, "")
    test = [doc for (tname, doc, f, l) in tests if tname == name]
    if not test:
        raise ValueError(name, "not found in tests")
    test = test[0]
    # XXX we rely on an internal doctest function:
    examples = doctest._extract_examples(test)
    testsrc = '\n'.join([
        "%s%s" % (source, _expect(expect))
        for (source, expect, lineno) in examples
        ])
    return testsrc

def debug_src(src, pm=False, globs=None):
    """Debug a single doctest test doc string

    The string is provided directly
    """
    # XXX we rely on an internal doctest function:
    examples = doctest._extract_examples(src)
    src = '\n'.join([
        "%s%s" % (source, _expect(expect))
        for (source, expect, lineno) in examples
        ])
    debug_script(src, pm, globs)

def debug_script(src, pm=False, globs=None):
    "Debug a test script"
    srcfilename = tempfile.mktemp("doctestdebug.py")
    open(srcfilename, 'w').write(src)
    if globs:
        globs = globs.copy()
    else:
        globs = {}

    try:
        if pm:
            try:
                execfile(srcfilename, globs, globs)
            except:
                print sys.exc_info()[1]
                pdb.post_mortem(sys.exc_info()[2])
        else:
            # Note that %r is vital here.  '%s' instead can, e.g., cause
            # backslashes to get treated as metacharacters on Windows.
            pdb.run("execfile(%r)" % srcfilename, globs, globs)
    finally:
        os.remove(srcfilename)

def debug(module, name, pm=False):
    """Debug a single doctest test doc string

    Provide the module (or dotted name of the module) containing the
    test to be debugged and the name (within the module) of the object
    with the doc string with tests to be debugged.

    """
    module = _normalizeModule(module)
    testsrc = testsource(module, name)
    debug_script(testsrc, pm, module.__dict__)
