"""

Test script for doctest.

"""

from test import support

from test.support import import_helper

import doctest

import functools

import os

import sys

import importlib

import importlib.abc

import importlib.util

import unittest

import tempfile

import types

import contextlib

def doctest_skip_if(condition):

def decorator(func):

if condition and support.HAVE_DOCSTRINGS:

func.__doc__ = ">>> pass # doctest: +SKIP"

return func

return decorator

# NOTE: There are some additional tests relating to interaction with

# zipimport in the test_zipimport_support test module.

# There are also related tests in `test_doctest2` module.

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

## 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(), sep='', end='')

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 setter(self, val):

"""

>>> s = SampleClass(-5)

>>> s.setter(1)

>>> print(s.val)

1

"""

self.val = 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, setter, doc="""

>>> print(SampleClass(22).a_property)

22

""")

a_class_attribute = 42

@functools.cached_property

def a_cached_property(self):

"""

>>> print(SampleClass(29).get())

29

"""

return "hello"

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

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

## 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'

Compare `Example`:

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

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

>>> other_example = doctest.Example('print 42', '42\n')

>>> example == same_example

True

>>> example != same_example

False

>>> hash(example) == hash(same_example)

True

>>> example == other_example

False

>>> example != other_example

True

"""

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 inconsistent 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)'

Compare `DocTest`:

>>> docstring = '''

... >>> print 12

... 12

... '''

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

... 'some_test', 20)

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

... 'some_test', 20)

>>> test == same_test

True

>>> test != same_test

False

>>> hash(test) == hash(same_test)

True

>>> docstring = '''

... >>> print 42

... 42

... '''

>>> other_test = parser.get_doctest(docstring, globs, 'other_test',

... 'other_file', 10)

>>> test == other_test

False

>>> test != other_test

True

>>> test < other_test

False

>>> other_test < test

True

Test comparison with lineno None on one side

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

... 'some_test', None)

>>> test.lineno is None

False

>>> no_lineno.lineno is None

True

>>> test < no_lineno

False

>>> no_lineno < test

True

Compare `DocTestCase`:

>>> DocTestCase = doctest.DocTestCase

>>> test_case = DocTestCase(test)

>>> same_test_case = DocTestCase(same_test)

>>> other_test_case = DocTestCase(other_test)

>>> test_case == same_test_case

True

>>> test_case != same_test_case

False

>>> hash(test_case) == hash(same_test_case)

True

>>> test == other_test_case

False

>>> test != other_test_case

True

"""

class test_DocTestFinder:

def basics(): 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:

>>> from test.test_doctest import test_doctest

>>> old = test_doctest.__file__

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

>>> tests = finder.find(sample_func)

>>> print(tests) # doctest: +ELLIPSIS

[<DocTest sample_func from test_doctest.py:36 (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_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__

1 SampleClass.a_cached_property

2 SampleClass.a_classmethod

1 SampleClass.a_property

1 SampleClass.a_staticmethod

1 SampleClass.double

1 SampleClass.get

3 SampleClass.setter

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 types

>>> m = types.ModuleType('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_doctest, to prevent doctest from

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

>>> from test.test_doctest import test_doctest

>>> tests = finder.find(m, module=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__

1 some_module.SampleClass.a_cached_property

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

3 some_module.SampleClass.setter

1 some_module.__test__.c

2 some_module.__test__.d

1 some_module.sample_func

However, doctest will ignore imported objects from other modules

(without proper `module=`):

>>> import types

>>> m = types.ModuleType('poluted_namespace')

>>> m.__dict__.update({

... 'sample_func': sample_func,

... 'SampleClass': SampleClass,

... })

>>> finder = doctest.DocTestFinder()

>>> finder.find(m)

[]

Duplicate Removal

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

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

will only be generated for it once:

>>> from test.test_doctest import doctest_aliases

>>> assert doctest_aliases.TwoNames.f

>>> assert doctest_aliases.TwoNames.g

>>> tests = excl_empty_finder.find(doctest_aliases)

>>> print(len(tests))

2

>>> print(tests[0].name)

test.test_doctest.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__

1 SampleClass.a_cached_property

2 SampleClass.a_classmethod

1 SampleClass.a_property

1 SampleClass.a_staticmethod

1 SampleClass.double

1 SampleClass.get

3 SampleClass.setter

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

tells it to include (empty) tests for objects with no doctests. This feature

is really to support backward compatibility in what doctest.master.summarize()

displays.

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

>>> for t in tests:

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

3 SampleClass

3 SampleClass.NestedClass

1 SampleClass.NestedClass.__init__

0 SampleClass.NestedClass.get

0 SampleClass.NestedClass.square

1 SampleClass.__init__

1 SampleClass.a_cached_property

2 SampleClass.a_classmethod

1 SampleClass.a_property

1 SampleClass.a_staticmethod

1 SampleClass.double

1 SampleClass.get

3 SampleClass.setter

When used with `exclude_empty=False` we are also interested in line numbers

of doctests that are empty.

It used to be broken for quite some time until `bpo-28249`.

>>> from test.test_doctest import doctest_lineno

>>> tests = doctest.DocTestFinder(exclude_empty=False).find(doctest_lineno)

>>> for t in tests:

... print('%5s %s' % (t.lineno, t.name))

None test.test_doctest.doctest_lineno

None test.test_doctest.doctest_lineno.ClassWithACachedProperty

102 test.test_doctest.doctest_lineno.ClassWithACachedProperty.cached

22 test.test_doctest.doctest_lineno.ClassWithDocstring

30 test.test_doctest.doctest_lineno.ClassWithDoctest

None test.test_doctest.doctest_lineno.ClassWithoutDocstring

None test.test_doctest.doctest_lineno.MethodWrapper

53 test.test_doctest.doctest_lineno.MethodWrapper.classmethod_with_doctest

39 test.test_doctest.doctest_lineno.MethodWrapper.method_with_docstring

45 test.test_doctest.doctest_lineno.MethodWrapper.method_with_doctest

None test.test_doctest.doctest_lineno.MethodWrapper.method_without_docstring

61 test.test_doctest.doctest_lineno.MethodWrapper.property_with_doctest

86 test.test_doctest.doctest_lineno.cached_func_with_doctest

None test.test_doctest.doctest_lineno.cached_func_without_docstring

4 test.test_doctest.doctest_lineno.func_with_docstring

77 test.test_doctest.doctest_lineno.func_with_docstring_wrapped

12 test.test_doctest.doctest_lineno.func_with_doctest

None test.test_doctest.doctest_lineno.func_without_docstring

Turning off Recursion

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

DocTestFinder can be told not to look for tests in contained objects

using the `recurse` flag:

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

>>> for t in tests:

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

3 SampleClass

Line numbers

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

DocTestFinder finds the line number of each example:

>>> def f(x):

... '''

... >>> x = 12

...

... some text

...

... >>> # examples are not created for comments & bare prompts.

... >>>

... ...

...

... >>> for x in range(10):

... ... print(x, end=' ')

... 0 1 2 3 4 5 6 7 8 9

... >>> x//2

... 6

... '''

>>> test = doctest.DocTestFinder().find(f)[0]

>>> [e.lineno for e in test.examples]

[1, 9, 12]

"""

if int.__doc__: # simple check for --without-doc-strings, skip if lacking

def non_Python_modules(): r"""

Finding Doctests in Modules Not Written in Python

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

DocTestFinder can also find doctests in most modules not written in Python.

We'll use builtins as an example, since it almost certainly isn't written in

plain ol' Python and is guaranteed to be available.

>>> import builtins

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

>>> 750 < len(tests) < 800 # approximate number of objects with docstrings # TODO: RUSTPYTHON # doctest: +EXPECTED_FAILURE

True

>>> real_tests = [t for t in tests if len(t.examples) > 0]

>>> len(real_tests) # objects that actually have doctests # TODO: RUSTPYTHON # doctest: +EXPECTED_FAILURE

14

>>> for t in real_tests: # TODO: RUSTPYTHON # doctest: +EXPECTED_FAILURE

... print('{} {}'.format(len(t.examples), t.name))

...

1 builtins.bin

5 builtins.bytearray.hex

5 builtins.bytes.hex

3 builtins.float.as_integer_ratio

2 builtins.float.fromhex

2 builtins.float.hex

1 builtins.hex

1 builtins.int

3 builtins.int.as_integer_ratio

2 builtins.int.bit_count

2 builtins.int.bit_length

5 builtins.memoryview.hex

1 builtins.oct

1 builtins.zip

Note here that 'bin', 'oct', and 'hex' are functions; 'float.as_integer_ratio',

'float.hex', and 'int.bit_length' are methods; 'float.fromhex' is a classmethod,

and 'int' is a type.

"""

class TestDocTest(unittest.TestCase):

def test_run(self):

test = '''

>>> 1 + 1

11

>>> 2 + 3 # doctest: +SKIP

"23"

>>> 5 + 7

57

'''

def myfunc():

pass

myfunc.__doc__ = test

# test DocTestFinder.run()

test = doctest.DocTestFinder().find(myfunc)[0]

with support.captured_stdout():

with support.captured_stderr():

results = doctest.DocTestRunner(verbose=False).run(test)

# test TestResults

self.assertIsInstance(results, doctest.TestResults)

self.assertEqual(results.failed, 2)

self.assertEqual(results.attempted, 3)

self.assertEqual(results.skipped, 1)

self.assertEqual(tuple(results), (2, 3))

x, y = results

self.assertEqual((x, y), (2, 3))

class TestDocTestFinder(unittest.TestCase):

def test_issue35753(self):

# This import of `call` should trigger issue35753 when

# DocTestFinder.find() is called due to inspect.unwrap() failing,

# however with a patched doctest this should succeed.

from unittest.mock import call

dummy_module = types.ModuleType("dummy")

dummy_module.__dict__['inject_call'] = call

finder = doctest.DocTestFinder()

self.assertEqual(finder.find(dummy_module), [])

def test_empty_namespace_package(self):

pkg_name = 'doctest_empty_pkg'

with tempfile.TemporaryDirectory() as parent_dir:

pkg_dir = os.path.join(parent_dir, pkg_name)

os.mkdir(pkg_dir)

sys.path.append(parent_dir)

try:

mod = importlib.import_module(pkg_name)

finally:

import_helper.forget(pkg_name)

sys.path.pop()

include_empty_finder = doctest.DocTestFinder(exclude_empty=False)

exclude_empty_finder = doctest.DocTestFinder(exclude_empty=True)

self.assertEqual(len(include_empty_finder.find(mod)), 1)

self.assertEqual(len(exclude_empty_finder.find(mod)), 0)

def test_DocTestParser(): r"""

Unit tests for the `DocTestParser` class.

DocTestParser is used to parse docstrings containing doctest examples.

The `parse` method divides a docstring into examples and intervening

text:

>>> s = '''

... >>> x, y = 2, 3 # no output expected

... >>> if 1:

... ... print(x)

... ... print(y)

... 2

... 3

...

... Some text.

... >>> x+y

... 5

... '''

>>> parser = doctest.DocTestParser()

>>> for piece in parser.parse(s):

... if isinstance(piece, doctest.Example):

... print('Example:', (piece.source, piece.want, piece.lineno))

... else:

... print(' Text:', repr(piece))

Text: '\n'

Example: ('x, y = 2, 3 # no output expected\n', '', 1)

Text: ''

Example: ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)

Text: '\nSome text.\n'

Example: ('x+y\n', '5\n', 9)

Text: ''

The `get_examples` method returns just the examples:

>>> for piece in parser.get_examples(s):

... print((piece.source, piece.want, piece.lineno))

('x, y = 2, 3 # no output expected\n', '', 1)

('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)

('x+y\n', '5\n', 9)

The `get_doctest` method creates a Test from the examples, along with the

given arguments:

>>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)

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

('name', 'filename', 5)

>>> for piece in test.examples:

... print((piece.source, piece.want, piece.lineno))

('x, y = 2, 3 # no output expected\n', '', 1)

('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)

('x+y\n', '5\n', 9)

"""

class test_DocTestRunner:

def basics(): r"""

Unit tests for the `DocTestRunner` class.

DocTestRunner is used to run DocTest test cases, and to accumulate

statistics. Here's a simple DocTest case we can use:

>>> import _colorize

>>> save_colorize = _colorize.COLORIZE

>>> _colorize.COLORIZE = False

>>> def f(x):

... '''

... >>> x = 12

... >>> print(x)

... 12

... >>> x//2

... 6

... '''

>>> test = doctest.DocTestFinder().find(f)[0]

The main DocTestRunner interface is the `run` method, which runs a

given DocTest case in a given namespace (globs). It returns a tuple

`(f,t)`, where `f` is the number of failed tests and `t` is the number

of tried tests.

>>> doctest.DocTestRunner(verbose=False).run(test)

TestResults(failed=0, attempted=3)

If any example produces incorrect output, then the test runner reports

the failure and proceeds to the next example:

>>> def f(x):

... '''

... >>> x = 12

... >>> print(x)

... 14

... >>> x//2

... 6

... '''

>>> test = doctest.DocTestFinder().find(f)[0]

>>> doctest.DocTestRunner(verbose=True).run(test)

... # doctest: +ELLIPSIS

Trying:

x = 12

Expecting nothing

ok

Trying:

print(x)

Expecting:

14

**********************************************************************

File ..., line 4, in f

Failed example:

print(x)

Expected:

14

Got:

12

Trying:

x//2

Expecting:

6

ok

TestResults(failed=1, attempted=3)

>>> _colorize.COLORIZE = save_colorize

"""

def verbose_flag(): r"""

The `verbose` flag makes the test runner generate more detailed

output:

>>> def f(x):

... '''

... >>> x = 12

... >>> print(x)

... 12

... >>> x//2

... 6

... '''

>>> test = doctest.DocTestFinder().find(f)[0]

>>> doctest.DocTestRunner(verbose=True).run(test)

Trying:

x = 12

Expecting nothing

ok

Trying:

print(x)

Expecting:

12

ok

Trying:

x//2

Expecting:

6

ok

TestResults(failed=0, attempted=3)

If the `verbose` flag is unspecified, then the output will be verbose

iff `-v` appears in sys.argv:

>>> # Save the real sys.argv list.

>>> old_argv = sys.argv

>>> # If -v does not appear in sys.argv, then output isn't verbose.

>>> sys.argv = ['test']

>>> doctest.DocTestRunner().run(test)

TestResults(failed=0, attempted=3)