"""

Test script for doctest.

"""

from test import test_support

import doctest

import warnings

######################################################################

## Sample Objects (used by test cases)

######################################################################

def sample_func(v):

    """

    Blah blah

    >>> print sample_func(22)

    44

    Yee ha!

    """

    return v+v

class SampleClass:

    """

    >>> print 1

    1

    >>> # comments get ignored.  so are empty PS1 and PS2 prompts:

    >>>

    ...

    Multiline example:

    >>> sc = SampleClass(3)

    >>> for i in range(10):

    ...     sc = sc.double()

    ...     print sc.get(),

    6 12 24 48 96 192 384 768 1536 3072

    """

    def __init__(self, val):

        """

        >>> print SampleClass(12).get()

        12

        """

        self.val = val

    def double(self):

        """

        >>> print SampleClass(12).double().get()

        24

        """

        return SampleClass(self.val + self.val)

    def get(self):

        """

        >>> print SampleClass(-5).get()

        -5

        """

        return self.val

    def a_staticmethod(v):

        """

        >>> print SampleClass.a_staticmethod(10)

        11

        """

        return v+1

    a_staticmethod = staticmethod(a_staticmethod)

    def a_classmethod(cls, v):

        """

        >>> print SampleClass.a_classmethod(10)

        12

        >>> print SampleClass(0).a_classmethod(10)

        12

        """

        return v+2

    a_classmethod = classmethod(a_classmethod)

    a_property = property(get, doc="""

        >>> print SampleClass(22).a_property

        22

        """)

    class NestedClass:

        """

        >>> x = SampleClass.NestedClass(5)

        >>> y = x.square()

        >>> print y.get()

        25

        """

        def __init__(self, val=0):

            """

            >>> print SampleClass.NestedClass().get()

            0

            """

            self.val = val

        def square(self):

            return SampleClass.NestedClass(self.val*self.val)

        def get(self):

            return self.val

class SampleNewStyleClass(object):

    r"""

    >>> print '1\n2\n3'

    1

    2

    3

    """

    def __init__(self, val):

        """

        >>> print SampleNewStyleClass(12).get()

        12

        """

        self.val = val

    def double(self):

        """

        >>> print SampleNewStyleClass(12).double().get()

        24

        """

        return SampleNewStyleClass(self.val + self.val)

    def get(self):

        """

        >>> print SampleNewStyleClass(-5).get()

        -5

        """

        return self.val

######################################################################

## Fake stdin (for testing interactive debugging)

######################################################################

class _FakeInput:

    """

    A fake input stream for pdb's interactive debugger.  Whenever a

    line is read, print it (to simulate the user typing it), and then

    return it.  The set of lines to return is specified in the

    constructor; they should not have trailing newlines.

    """

    def __init__(self, lines):

        self.lines = lines

    def readline(self):

        line = self.lines.pop(0)

        print line

        return line+'\n'

######################################################################

## Test Cases

######################################################################

def test_Example(): r"""

Unit tests for the `Example` class.

Example is a simple container class that holds:

  - `source`: A source string.

  - `want`: An expected output string.

  - `exc_msg`: An expected exception message string (or None if no

    exception is expected).

  - `lineno`: A line number (within the docstring).

  - `indent`: The example's indentation in the input string.

  - `options`: An option dictionary, mapping option flags to True or

    False.

These attributes are set by the constructor.  `source` and `want` are

required; the other attributes all have default values:

    >>> example = doctest.Example('print 1', '1\n')

    >>> (example.source, example.want, example.exc_msg,

    ...  example.lineno, example.indent, example.options)

    ('print 1\n', '1\n', None, 0, 0, {})

The first three attributes (`source`, `want`, and `exc_msg`) may be

specified positionally; the remaining arguments should be specified as

keyword arguments:

    >>> exc_msg = 'IndexError: pop from an empty list'

    >>> example = doctest.Example('[].pop()', '', exc_msg,

    ...                           lineno=5, indent=4,

    ...                           options={doctest.ELLIPSIS: True})

    >>> (example.source, example.want, example.exc_msg,

    ...  example.lineno, example.indent, example.options)

    ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})

The constructor normalizes the `source` string to end in a newline:

    Source spans a single line: no terminating newline.

    >>> e = doctest.Example('print 1', '1\n')

    >>> e.source, e.want

    ('print 1\n', '1\n')

    >>> e = doctest.Example('print 1\n', '1\n')

    >>> e.source, e.want

    ('print 1\n', '1\n')

    Source spans multiple lines: require terminating newline.

    >>> e = doctest.Example('print 1;\nprint 2\n', '1\n2\n')

    >>> e.source, e.want

    ('print 1;\nprint 2\n', '1\n2\n')

    >>> e = doctest.Example('print 1;\nprint 2', '1\n2\n')

    >>> e.source, e.want

    ('print 1;\nprint 2\n', '1\n2\n')

    Empty source string (which should never appear in real examples)

    >>> e = doctest.Example('', '')

    >>> e.source, e.want

    ('\n', '')

The constructor normalizes the `want` string to end in a newline,

unless it's the empty string:

    >>> e = doctest.Example('print 1', '1\n')

    >>> e.source, e.want

    ('print 1\n', '1\n')

    >>> e = doctest.Example('print 1', '1')

    >>> e.source, e.want

    ('print 1\n', '1\n')

    >>> e = doctest.Example('print', '')

    >>> e.source, e.want

    ('print\n', '')

The constructor normalizes the `exc_msg` string to end in a newline,

unless it's `None`:

    Message spans one line

    >>> exc_msg = 'IndexError: pop from an empty list'

    >>> e = doctest.Example('[].pop()', '', exc_msg)

    >>> e.exc_msg

    'IndexError: pop from an empty list\n'

    >>> exc_msg = 'IndexError: pop from an empty list\n'

    >>> e = doctest.Example('[].pop()', '', exc_msg)

    >>> e.exc_msg

    'IndexError: pop from an empty list\n'

    Message spans multiple lines

    >>> exc_msg = 'ValueError: 1\n  2'

    >>> e = doctest.Example('raise ValueError("1\n  2")', '', exc_msg)

    >>> e.exc_msg

    'ValueError: 1\n  2\n'

    >>> exc_msg = 'ValueError: 1\n  2\n'

    >>> e = doctest.Example('raise ValueError("1\n  2")', '', exc_msg)

    >>> e.exc_msg

    'ValueError: 1\n  2\n'

    Empty (but non-None) exception message (which should never appear

    in real examples)

    >>> exc_msg = ''

    >>> e = doctest.Example('raise X()', '', exc_msg)

    >>> e.exc_msg

    '\n'

"""

def test_DocTest(): r"""

Unit tests for the `DocTest` class.

DocTest is a collection of examples, extracted from a docstring, along

with information about where the docstring comes from (a name,

filename, and line number).  The docstring is parsed by the `DocTest`

constructor:

    >>> docstring = '''

    ...     >>> print 12

    ...     12

    ...

    ... Non-example text.

    ...

    ...     >>> print 'another\example'

    ...     another

    ...     example

    ... '''

    >>> globs = {} # globals to run the test in.

    >>> parser = doctest.DocTestParser()

    >>> test = parser.get_doctest(docstring, globs, 'some_test',

    ...                           'some_file', 20)

    >>> print test

    <DocTest some_test from some_file:20 (2 examples)>

    >>> len(test.examples)

    2

    >>> e1, e2 = test.examples

    >>> (e1.source, e1.want, e1.lineno)

    ('print 12\n', '12\n', 1)

    >>> (e2.source, e2.want, e2.lineno)

    ("print 'another\\example'\n", 'another\nexample\n', 6)

Source information (name, filename, and line number) is available as

attributes on the doctest object:

    >>> (test.name, test.filename, test.lineno)

    ('some_test', 'some_file', 20)

The line number of an example within its containing file is found by

adding the line number of the example and the line number of its

containing test:

    >>> test.lineno + e1.lineno

    21

    >>> test.lineno + e2.lineno

    26

If the docstring contains inconsistant leading whitespace in the

expected output of an example, then `DocTest` will raise a ValueError:

    >>> docstring = r'''

    ...       >>> print 'bad\nindentation'

    ...       bad

    ...     indentation

    ...     '''

    >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)

    Traceback (most recent call last):

    ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'

If the docstring contains inconsistent leading whitespace on

continuation lines, then `DocTest` will raise a ValueError:

    >>> docstring = r'''

    ...       >>> print ('bad indentation',

    ...     ...          2)

    ...       ('bad', 'indentation')

    ...     '''

    >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)

    Traceback (most recent call last):

    ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '...          2)'

If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`

will raise a ValueError:

    >>> docstring = '>>>print 1\n1'

    >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)

    Traceback (most recent call last):

    ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print 1'

If there's no blank space after a PS2 prompt ('...'), then `DocTest`

will raise a ValueError:

    >>> docstring = '>>> if 1:\n...print 1\n1'

    >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)

    Traceback (most recent call last):

    ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print 1'

"""

def test_DocTestFinder(): r"""

Unit tests for the `DocTestFinder` class.

DocTestFinder is used to extract DocTests from an object's docstring

and the docstrings of its contained objects.  It can be used with

modules, functions, classes, methods, staticmethods, classmethods, and

properties.

Finding Tests in Functions

~~~~~~~~~~~~~~~~~~~~~~~~~~

For a function whose docstring contains examples, DocTestFinder.find()

will return a single test (for that function's docstring):

    >>> finder = doctest.DocTestFinder()

We'll simulate a __file__ attr that ends in pyc:

    >>> import test.test_doctest

    >>> old = test.test_doctest.__file__

    >>> test.test_doctest.__file__ = 'test_doctest.pyc'

    >>> tests = finder.find(sample_func)

    >>> print tests  # doctest: +ELLIPSIS

    [<DocTest sample_func from ...:13 (1 example)>]

The exact name depends on how test_doctest was invoked, so allow for

leading path components.

    >>> tests[0].filename # doctest: +ELLIPSIS

    '...test_doctest.py'

    >>> test.test_doctest.__file__ = old

    >>> e = tests[0].examples[0]

    >>> (e.source, e.want, e.lineno)

    ('print sample_func(22)\n', '44\n', 3)

By default, tests are created for objects with no docstring:

    >>> def no_docstring(v):

    ...     pass

    >>> finder.find(no_docstring)

    []

However, the optional argument `exclude_empty` to the DocTestFinder

constructor can be used to exclude tests for objects with empty

docstrings:

    >>> def no_docstring(v):

    ...     pass

    >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)

    >>> excl_empty_finder.find(no_docstring)

    []

If the function has a docstring with no examples, then a test with no

examples is returned.  (This lets `DocTestRunner` collect statistics

about which functions have no tests -- but is that useful?  And should

an empty test also be created when there's no docstring?)

    >>> def no_examples(v):

    ...     ''' no doctest examples '''

    >>> finder.find(no_examples) # doctest: +ELLIPSIS

    [<DocTest no_examples from ...:1 (no examples)>]

Finding Tests in Classes

~~~~~~~~~~~~~~~~~~~~~~~~

For a class, DocTestFinder will create a test for the class's

docstring, and will recursively explore its contents, including

methods, classmethods, staticmethods, properties, and nested classes.

    >>> finder = doctest.DocTestFinder()

    >>> tests = finder.find(SampleClass)

    >>> for t in tests:

    ...     print '%2s  %s' % (len(t.examples), t.name)

     3  SampleClass

     3  SampleClass.NestedClass

     1  SampleClass.NestedClass.__init__

     1  SampleClass.__init__

     2  SampleClass.a_classmethod

     1  SampleClass.a_property

     1  SampleClass.a_staticmethod

     1  SampleClass.double

     1  SampleClass.get

New-style classes are also supported:

    >>> tests = finder.find(SampleNewStyleClass)

    >>> for t in tests:

    ...     print '%2s  %s' % (len(t.examples), t.name)

     1  SampleNewStyleClass

     1  SampleNewStyleClass.__init__

     1  SampleNewStyleClass.double

     1  SampleNewStyleClass.get

Finding Tests in Modules

~~~~~~~~~~~~~~~~~~~~~~~~

For a module, DocTestFinder will create a test for the class's

docstring, and will recursively explore its contents, including

functions, classes, and the `__test__` dictionary, if it exists:

    >>> # A module

    >>> import new

    >>> m = new.module('some_module')

    >>> def triple(val):

    ...     '''

    ...     >>> print triple(11)

    ...     33

    ...     '''

    ...     return val*3

    >>> m.__dict__.update({

    ...     'sample_func': sample_func,

    ...     'SampleClass': SampleClass,

    ...     '__doc__': '''

    ...         Module docstring.

    ...             >>> print 'module'

    ...             module

    ...         ''',

    ...     '__test__': {

    ...         'd': '>>> print 6\n6\n>>> print 7\n7\n',

    ...         'c': triple}})

    >>> finder = doctest.DocTestFinder()

    >>> # Use module=test.test_doctest, to prevent doctest from

    >>> # ignoring the objects since they weren't defined in m.

    >>> import test.test_doctest

    >>> tests = finder.find(m, module=test.test_doctest)

    >>> for t in tests:

    ...     print '%2s  %s' % (len(t.examples), t.name)

     1  some_module

     3  some_module.SampleClass

     3  some_module.SampleClass.NestedClass

     1  some_module.SampleClass.NestedClass.__init__

     1  some_module.SampleClass.__init__

     2  some_module.SampleClass.a_classmethod

     1  some_module.SampleClass.a_property

     1  some_module.SampleClass.a_staticmethod

     1  some_module.SampleClass.double

     1  some_module.SampleClass.get

     1  some_module.__test__.c

     2  some_module.__test__.d

     1  some_module.sample_func

Duplicate Removal

~~~~~~~~~~~~~~~~~

If a single object is listed twice (under different names), then tests

will only be generated for it once:

    >>> from test import doctest_aliases

    >>> tests = excl_empty_finder.find(doctest_aliases)

    >>> print len(tests)

    2

    >>> print tests[0].name

    test.doctest_aliases.TwoNames

    TwoNames.f and TwoNames.g are bound to the same object.

    We can't guess which will be found in doctest's traversal of

    TwoNames.__dict__ first, so we have to allow for either.

    >>> tests[1].name.split('.')[-1] in ['f', 'g']

    True

Empty Tests

~~~~~~~~~~~

By default, an object with no doctests doesn't create any tests:

    >>> tests = doctest.DocTestFinder().find(SampleClass)

    >>> for t in tests:

    ...     print '%2s  %s' % (len(t.examples), t.name)

     3  SampleClass

     3  SampleClass.NestedClass

     1  SampleClass.NestedClass.__init__

     1  SampleClass.__init__

     2  SampleClass.a_classmethod

     1  SampleClass.a_property

     1  SampleClass.a_staticmethod

     1  SampleClass.double

     1  SampleClass.get

By default, that excluded objects with no doctests.  exclude_empty=False