# 0, Option Flags

'register_optionflag',

'DONT_ACCEPT_TRUE_FOR_1',

'DONT_ACCEPT_BLANKLINE',

'NORMALIZE_WHITESPACE',

'ELLIPSIS',

'SKIP',

'IGNORE_EXCEPTION_DETAIL',

'COMPARISON_FLAGS',

'REPORT_UDIFF',

'REPORT_CDIFF',

'REPORT_NDIFF',

'REPORT_ONLY_FIRST_FAILURE',

'REPORTING_FLAGS',

'FAIL_FAST',

# 1. Utility Functions

# 2. Example & DocTest

'Example',

'DocTest',

# 3. Doctest Parser

'DocTestParser',

# 4. Doctest Finder

'DocTestFinder',

# 5. Doctest Runner

'DocTestRunner',

'OutputChecker',

'DocTestFailure',

'UnexpectedException',

'DebugRunner',

# 6. Test Functions

'testmod',

'testfile',

'run_docstring_examples',

# 7. Unittest Support

'DocTestSuite',

'DocFileSuite',

'set_unittest_reportflags',

# 8. Debugging Support

'script_from_examples',

'testsource',

'debug_src',

'debug',

def __new__(cls, failed, attempted, *, skipped=0):

results = super().__new__(cls, failed, attempted)

results.skipped = skipped

return results

def __repr__(self):

if self.skipped:

return (f'TestResults(failed={self.failed}, '

f'attempted={self.attempted}, '

f'skipped={self.skipped})')

else:

# Leave the repr() unchanged for backward compatibility

# if skipped is zero

DONT_ACCEPT_BLANKLINE |

NORMALIZE_WHITESPACE |

ELLIPSIS |

SKIP |

REPORT_CDIFF |

REPORT_NDIFF |

REPORT_ONLY_FIRST_FAILURE |

"""

flags = 0

for fname in __future__.all_feature_names:

feature = globs.get(fname, None)

if feature is getattr(__future__, fname):

flags |= feature.compiler_flag

"""

if inspect.ismodule(module):

return module

elif isinstance(module, str):

return __import__(module, globals(), locals(), ["*"])

elif module is None:

try:

try:

return sys.modules[sys._getframemodulename(depth)]

except AttributeError:

return sys.modules[sys._getframe(depth).f_globals['__name__']]

except KeyError:

pass

else:

if module_relative:

package = _normalize_module(package, 3)

filename = _module_relative_path(package, filename)

if (loader := getattr(package, '__loader__', None)) is None:

try:

loader = package.__spec__.loader

except AttributeError:

pass

if hasattr(loader, 'get_data'):

file_contents = loader.get_data(filename)

# get_data() opens files as 'rb', so one must do the equivalent

# conversion as universal newlines would do.

return TextIOWrapper(BytesIO(file_contents), encoding=encoding, newline=None).read(), filename

with open(filename, encoding=encoding) as f:

"""

# This regexp matches the start of non-blank lines:

"""

# Get a traceback message.

excout = StringIO()

exc_type, exc_val, exc_tb = exc_info

traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)

def getvalue(self):

result = StringIO.getvalue(self)

# If anything at all was written, make sure there's a trailing

# newline. There's no way for the expected output to indicate

# that a trailing newline is missing.

if result and not result.endswith("\n"):

result += "\n"

return result

def truncate(self, size=None):

if size is not None:

self.seek(size)

"""

if ELLIPSIS_MARKER not in want:

return want == got

# Find "the real" strings.

ws = want.split(ELLIPSIS_MARKER)

assert len(ws) >= 2

# Deal with exact matches possibly needed at one or both ends.

startpos, endpos = 0, len(got)

w = ws[0]

if w: # starts with exact match

if got.startswith(w):

startpos = len(w)

del ws[0]

else:

return False

w = ws[-1]

if w: # ends with exact match

if got.endswith(w):

endpos -= len(w)

del ws[-1]

else:

return False

if startpos > endpos:

# Exact end matches required more characters than we have, as in

# _ellipsis_match('aa...aa', 'aaa')

return False

# For the rest, we only need to find the leftmost non-overlapping

# match for each piece. If there's no overall match that way alone,

# there's no overall match period.

for w in ws:

# w may be '' at times, if there are consecutive ellipses, or

# due to an ellipsis at the start or end of `want`. That's OK.

# Search for an empty string succeeds, and doesn't change startpos.

startpos = got.find(w, startpos, endpos)

if startpos < 0:

return False

startpos += len(w)

"Return a commented form of the given line"

line = line.rstrip()

if line:

return '# '+line

else:

# Support for IGNORE_EXCEPTION_DETAIL.

# Get rid of everything except the exception name; in particular, drop

# the possibly dotted module path (if any) and the exception message (if

# any). We assume that a colon is never part of a dotted name, or of an

# exception name.

# E.g., given

# "foo.bar.MyError: la di da"

# return "MyError"

# Or for "abc.def" or "abc.def:\n" return "def".

start, end = 0, len(msg)

# The exception name must appear on the first line.

i = msg.find("\n")

if i >= 0:

end = i

# retain up to the first colon (if any)

i = msg.find(':', 0, end)

if i >= 0:

end = i

# retain just the exception name

i = msg.rfind('.', 0, end)

if i >= 0:

start = i+1

"""

def __init__(self, out):

self.__out = out

self.__debugger_used = False

# do not play signal games in the pdb

super().__init__(stdout=out, nosigint=True)

# still use input() to get user input

self.use_rawinput = 1

def set_trace(self, frame=None, *, commands=None):

self.__debugger_used = True

if frame is None:

frame = sys._getframe().f_back

pdb.Pdb.set_trace(self, frame, commands=commands)

def set_continue(self):

# Calling set_continue unconditionally would break unit test

# coverage reporting, as Bdb.set_continue calls sys.settrace(None).

if self.__debugger_used:

pdb.Pdb.set_continue(self)

def trace_dispatch(self, *args):

# Redirect stdout to the given stream.

save_stdout = sys.stdout

sys.stdout = self.__out

# Call Pdb's trace dispatch method.

try:

return pdb.Pdb.trace_dispatch(self, *args)

finally:

if not inspect.ismodule(module):

raise TypeError('Expected a module: %r' % module)

if test_path.startswith('/'):

raise ValueError('Module-relative files may not have absolute paths')

# Normalize the path. On Windows, replace "/" with "\".

test_path = os.path.join(*(test_path.split('/')))

# Find the base directory for the path.

if hasattr(module, '__file__'):

# A normal module/package

basedir = os.path.split(module.__file__)[0]

elif module.__name__ == '__main__':

# An interactive session.

if len(sys.argv)>0 and sys.argv[0] != '':

basedir = os.path.split(sys.argv[0])[0]

else:

basedir = os.curdir

else:

if hasattr(module, '__path__'):

for directory in module.__path__:

fullpath = os.path.join(directory, test_path)

if os.path.exists(fullpath):

return fullpath

# A module w/o __file__ (this includes builtins)

raise ValueError("Can't resolve paths relative to the module "

"%r (it has no __file__)"

% module.__name__)

# Combine the base directory and the test path.

"""

def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,

options=None):

# Normalize inputs.

if not source.endswith('\n'):

source += '\n'

if want and not want.endswith('\n'):

want += '\n'

if exc_msg is not None and not exc_msg.endswith('\n'):

exc_msg += '\n'

# Store properties.

self.source = source

self.want = want

self.lineno = lineno

self.indent = indent

if options is None: options = {}

self.options = options

self.exc_msg = exc_msg

def __eq__(self, other):

if type(self) is not type(other):

return NotImplemented

return self.source == other.source and \

self.want == other.want and \

self.lineno == other.lineno and \

self.indent == other.indent and \

self.options == other.options and \

self.exc_msg == other.exc_msg

def __hash__(self):

return hash((self.source, self.want, self.lineno, self.indent,

"""

def __init__(self, examples, globs, name, filename, lineno, docstring):

"""

assert not isinstance(examples, str), \

"DocTest no longer accepts str; use DocTestParser instead"

self.examples = examples

self.docstring = docstring

self.globs = globs.copy()

self.name = name

self.filename = filename

self.lineno = lineno

def __repr__(self):

if len(self.examples) == 0:

examples = 'no examples'

elif len(self.examples) == 1:

examples = '1 example'

else:

examples = '%d examples' % len(self.examples)

return ('<%s %s from %s:%s (%s)>' %

(self.__class__.__name__,

self.name, self.filename, self.lineno, examples))

def __eq__(self, other):

if type(self) is not type(other):

return NotImplemented

return self.examples == other.examples and \

self.docstring == other.docstring and \

self.globs == other.globs and \

self.name == other.name and \

self.filename == other.filename and \

self.lineno == other.lineno

def __hash__(self):

return hash((self.docstring, self.name, self.filename, self.lineno))

# This lets us sort tests by name:

def __lt__(self, other):

if not isinstance(other, DocTest):

return NotImplemented

self_lno = self.lineno if self.lineno is not None else -1

other_lno = other.lineno if other.lineno is not None else -1

return ((self.name, self.filename, self_lno, id(self))

<

"""

# This regular expression is used to find doctest examples in a

# string. It defines three groups: `source` is the source code

# (including leading indentation and prompts); `indent` is the

# indentation of the first (PS1) line of the source code; and

# `want` is the expected output (including leading indentation).

_EXAMPLE_RE = re.compile(r'''

''', re.MULTILINE | re.VERBOSE)

# A regular expression for handling `want` strings that contain

# expected exceptions. It divides `want` into three pieces:

# - the traceback header line (`hdr`)

# - the traceback stack (`stack`)

# - the exception message (`msg`), as generated by

# traceback.format_exception_only()

# `msg` may have multiple lines. We assume/require that the

# exception message is the first non-indented line starting with a word

# character following the traceback header line.

_EXCEPTION_RE = re.compile(r"""

""", re.VERBOSE | re.MULTILINE | re.DOTALL)

# A callable returning a true value iff its argument is a blank line

# or contains a single comment.

_IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match

def parse(self, string, name='<string>'):

"""

string = string.expandtabs()

# If all lines begin with the same indentation, then strip it.

min_indent = self._min_indent(string)

if min_indent > 0:

string = '\n'.join([l[min_indent:] for l in string.split('\n')])

output = []

charno, lineno = 0, 0

# Find all doctest examples in the string:

for m in self._EXAMPLE_RE.finditer(string):

# Add the pre-example text to `output`.

output.append(string[charno:m.start()])

# Update lineno (lines before this example)

lineno += string.count('\n', charno, m.start())

# Extract info from the regexp match.

(source, options, want, exc_msg) = \

self._parse_example(m, name, lineno)

# Create an Example, and add it to the list.

if not self._IS_BLANK_OR_COMMENT(source):

output.append( Example(source, want, exc_msg,

lineno=lineno,

indent=min_indent+len(m.group('indent')),

options=options) )

# Update lineno (lines inside this example)

lineno += string.count('\n', m.start(), m.end())

# Update charno.

charno = m.end()

# Add any remaining post-example text to `output`.

output.append(string[charno:])

return output

def get_doctest(self, string, globs, name, filename, lineno):

"""

return DocTest(self.get_examples(string, name), globs,

name, filename, lineno, string)

def get_examples(self, string, name='<string>'):

"""

return [x for x in self.parse(string, name)

if isinstance(x, Example)]

def _parse_example(self, m, name, lineno):

"""

# Get the example's indentation level.

indent = len(m.group('indent'))

# Divide source into lines; check that they're properly

# indented; and then strip their indentation & prompts.

source_lines = m.group('source').split('\n')

self._check_prompt_blank(source_lines, indent, name, lineno)

self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)

source = '\n'.join([sl[indent+4:] for sl in source_lines])

# Divide want into lines; check that it's properly indented; and

# then strip the indentation. Spaces before the last newline should

# be preserved, so plain rstrip() isn't good enough.

want = m.group('want')

want_lines = want.split('\n')

if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):

del want_lines[-1] # forget final newline & spaces after it

self._check_prefix(want_lines, ' '*indent, name,

lineno + len(source_lines))

want = '\n'.join([wl[indent:] for wl in want_lines])

# If `want` contains a traceback message, then extract it.

m = self._EXCEPTION_RE.match(want)

if m:

exc_msg = m.group('msg')

else:

exc_msg = None

# Extract options from the source.

options = self._find_options(source, name, lineno)

return source, options, want, exc_msg

# This regular expression looks for option directives in the

# source code of an example. Option directives are comments

# starting with "doctest:". Warning: this may give false

# positives for string-literals that contain the string

# "#doctest:". Eliminating these false positives would require

# actually parsing the string; but we limit them by ignoring any

# line containing "#doctest:" that is *followed* by a quote mark.

_OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',

re.MULTILINE)

def _find_options(self, source, name, lineno):

"""

options = {}

# (note: with the current regexp, this will match at most once:)

for m in self._OPTION_DIRECTIVE_RE.finditer(source):

option_strings = m.group(1).replace(',', ' ').split()

for option in option_strings:

if (option[0] not in '+-' or

option[1:] not in OPTIONFLAGS_BY_NAME):

raise ValueError('line %r of the doctest for %s '

'has an invalid option: %r' %

(lineno+1, name, option))

flag = OPTIONFLAGS_BY_NAME[option[1:]]

options[flag] = (option[0] == '+')

if options and self._IS_BLANK_OR_COMMENT(source):

raise ValueError('line %r of the doctest for %s has an option '

'directive on a line with no example: %r' %

(lineno, name, source))

return options

# This regular expression finds the indentation of every non-blank

# line in a string.

_INDENT_RE = re.compile(r'^([ ]*)(?=\S)', re.MULTILINE)

def _min_indent(self, s):

"Return the minimum indentation of any non-blank line in `s`"

indents = [len(indent) for indent in self._INDENT_RE.findall(s)]

if len(indents) > 0:

return min(indents)

else:

return 0

def _check_prompt_blank(self, lines, indent, name, lineno):

"""

for i, line in enumerate(lines):

if len(line) >= indent+4 and line[indent+3] != ' ':

raise ValueError('line %r of the docstring for %s '

'lacks blank after %s: %r' %

(lineno+i+1, name,

line[indent:indent+3], line))

def _check_prefix(self, lines, prefix, name, lineno):

"""

for i, line in enumerate(lines):

if line and not line.startswith(prefix):

raise ValueError('line %r of the docstring for %s has '

'inconsistent leading whitespace: %r' %

"""

def __init__(self, verbose=False, parser=DocTestParser(),

recurse=True, exclude_empty=True):

"""

self._parser = parser

self._verbose = verbose

self._recurse = recurse

self._exclude_empty = exclude_empty

def find(self, obj, name=None, module=None, globs=None, extraglobs=None):

"""

# If name was not specified, then extract it from the object.

if name is None:

name = getattr(obj, '__name__', None)

if name is None:

raise ValueError("DocTestFinder.find: name must be given "

"when obj.__name__ doesn't exist: %r" %

(type(obj),))

# Find the module that contains the given object (if obj is

# a module, then module=obj.). Note: this may fail, in which

# case module will be None.

if module is False:

module = None

elif module is None:

module = inspect.getmodule(obj)

# Read the module's source code. This is used by

# DocTestFinder._find_lineno to find the line number for a

# given object's docstring.

try:

file = inspect.getsourcefile(obj)

except (TypeError, OSError):

source_lines = None

else:

if not file:

# Check to see if it's one of our special internal "files"

# (see __patched_linecache_getlines).

file = inspect.getfile(obj)

if not file[0]+file[-2:] == '<]>': file = None

if file is None:

source_lines = None

else:

if module is not None:

# Supply the module globals in case the module was

# originally loaded via a PEP 302 loader and

# file is not a valid filesystem path

source_lines = linecache.getlines(file, module.__dict__)

else:

# No access to a loader, so assume it's a normal

# filesystem path

source_lines = linecache.getlines(file)

if not source_lines:

source_lines = None

# Initialize globals, and merge in extraglobs.

if globs is None:

if module is None:

globs = {}

else:

globs = module.__dict__.copy()

else:

globs = globs.copy()

if extraglobs is not None:

globs.update(extraglobs)

if '__name__' not in globs:

globs['__name__'] = '__main__' # provide a default module name

# Recursively explore `obj`, extracting DocTests.

tests = []

self._find(tests, obj, name, module, source_lines, globs, {})

# Sort the tests by alpha order of names, for consistency in

# verbose-mode output. This was a feature of doctest in Pythons

# <= 2.3 that got lost by accident in 2.4. It was repaired in

# 2.4.4 and 2.5.

tests.sort()

return tests

def _from_module(self, module, object):

"""

if module is None:

return True

elif inspect.getmodule(object) is not None:

return module is inspect.getmodule(object)

elif inspect.isfunction(object):

return module.__dict__ is object.__globals__

elif (inspect.ismethoddescriptor(object) or

inspect.ismethodwrapper(object)):

if hasattr(object, '__objclass__'):

obj_mod = object.__objclass__.__module__

elif hasattr(object, '__module__'):

obj_mod = object.__module__

else:

return True # [XX] no easy way to tell otherwise

return module.__name__ == obj_mod

elif inspect.isclass(object):

return module.__name__ == object.__module__

elif hasattr(object, '__module__'):

return module.__name__ == object.__module__

elif isinstance(object, property):

return True # [XX] no way not be sure.

else:

raise ValueError("object must be a class or function")