Lines Matching +full:module +full:- +full:path +full:- +full:tests
1 # Module doctest.
2 # Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
7 # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
9 r"""Module doctest -- a framework for running examples in docstrings.
11 In simplest use, end each module M to be tested with:
20 Then running the module as a script will cause the examples in the
30 Run it with the -v switch instead:
32 python M.py -v
42 with the unittest framework, and support for running non-Python text
111 # - Example: a <source, want> pair, plus an intra-docstring line number.
112 # - DocTest: a collection of examples, parsed from a docstring, plus
114 # - DocTestFinder: extracts DocTests from a given object's docstring and
116 # - DocTestRunner: runs DocTest cases, and accumulates statistics.
121 # +------+ +---------+ +-------+
122 # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
123 # +------+ +---------+ +-------+
127 # +---------+
170 # 2. Example & DocTest -- store test cases
171 # 3. DocTest Parser -- extracts examples from strings
172 # 4. DocTest Finder -- extracts test cases from objects
173 # 5. DocTest Runner -- runs test cases
174 # 6. Test Functions -- convenient wrappers for testing
185 Return the compiler-flags associated with the future features that
195 def _normalize_module(module, depth=2): argument
197 Return the module specified by `module`. In particular:
198 - If `module` is a module, then return module.
199 - If `module` is a string, then import and return the
200 module with that name.
201 - If `module` is None, then return the calling module.
202 The calling module is assumed to be the module of
205 if inspect.ismodule(module):
206 return module
207 elif isinstance(module, str):
208 return __import__(module, globals(), locals(), ["*"])
209 elif module is None:
212 raise TypeError("Expected a module, string, or None")
215 # The IO module provides a handy decoder for universal newline conversion
239 every non-blank line in `s`, and return the result.
241 # This regexp matches the start of non-blank lines:
270 # Worst-case linear-time ellipsis matching.
293 w = ws[-1]
296 endpos -= len(w)
297 del ws[-1]
306 # For the rest, we only need to find the leftmost non-overlapping
331 # the possibly dotted module path (if any) and the exception message (if
390 # [XX] Normalize with respect to os.path.pardir?
391 def _module_relative_path(module, test_path): argument
392 if not inspect.ismodule(module):
393 raise TypeError('Expected a module: %r' % module)
395 raise ValueError('Module-relative files may not have absolute paths')
397 # Normalize the path. On Windows, replace "/" with "\".
398 test_path = os.path.join(*(test_path.split('/')))
400 # Find the base directory for the path.
401 if hasattr(module, '__file__'):
402 # A normal module/package
403 basedir = os.path.split(module.__file__)[0]
404 elif module.__name__ == '__main__':
407 basedir = os.path.split(sys.argv[0])[0]
411 if hasattr(module, '__path__'):
412 for directory in module.__path__:
413 fullpath = os.path.join(directory, test_path)
414 if os.path.exists(fullpath):
417 # A module w/o __file__ (this includes builtins)
418 raise ValueError("Can't resolve paths relative to the module "
420 % module.__name__)
422 # Combine the base directory and the test path.
423 return os.path.join(basedir, test_path)
428 ## - An "example" is a <source, want> pair, where "source" is a
433 ## - A "doctest" is a collection of examples, typically extracted from
442 - source: A single Python statement, always ending with a newline.
445 - want: The expected output from running the source code (either
450 - exc_msg: The exception message generated by the example, if
458 - lineno: The line number within the DocTest string containing
460 zero-based, with respect to the beginning of the DocTest.
462 - indent: The example's indentation in the DocTest string.
466 - options: A dictionary mapping from option flags to True or
510 - examples: the list of examples.
512 - globs: The namespace (aka globals) that the examples should
515 - name: A name identifying the DocTest (typically, the name of
518 - filename: The name of the file that this DocTest was extracted
521 - lineno: The line number within filename where this DocTest
523 line number is zero-based, with respect to the beginning of
526 - docstring: The string that the examples were extracted from,
568 # This lets us sort tests by name:
595 # Want consists of any non-blank lines that do not start with PS1.
604 # - the traceback header line (`hdr`)
605 # - the traceback stack (`stack`)
606 # - the exception message (`msg`), as generated by
609 # exception message is the first non-indented line starting with a word
632 Line numbers for the Examples are 0-based. The optional
646 # Add the pre-example text to `output`.
663 # Add any remaining post-example text to `output`.
683 0-based, because it's most common in doctests that nothing
684 interesting appears on the same line as opening triple-quote,
719 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
720 del want_lines[-1] # forget final newline & spaces after it
740 # positives for string-literals that contain the string
760 if (option[0] not in '+-' or
773 # This regular expression finds the indentation of every non-blank
778 "Return the minimum indentation of any non-blank line in `s`"
839 will include tests for objects with empty docstrings.
846 def find(self, obj, name=None, module=None, globs=None, extraglobs=None): argument
852 The optional parameter `module` is the module that contains
853 the given object. If the module is not specified or is None, then
855 correct module. The object's module is used:
857 - As a default namespace, if `globs` is not specified.
858 - To prevent the DocTestFinder from extracting DocTests
860 - To find the name of the file containing the object.
861 - To help find the line number of the object within its
864 Contained objects whose module does not match `module` are ignored.
866 If `module` is False, no attempt to find the module will be made.
867 This is obscure, of use mostly in tests: if `module` is False, or
869 considered to belong to the (non-existent) module, so all contained
876 defaults to the module's `__dict__`, if specified, or {}
889 # Find the module that contains the given object (if obj is
890 # a module, then module=obj.). Note: this may fail, in which
891 # case module will be None.
892 if module is False:
893 module = None
894 elif module is None:
895 module = inspect.getmodule(obj)
897 # Read the module's source code. This is used by
909 if not file[0]+file[-2:] == '<]>': file = None
913 if module is not None:
914 # Supply the module globals in case the module was
916 # file is not a valid filesystem path
917 source_lines = linecache.getlines(file, module.__dict__)
920 # filesystem path
927 if module is None:
930 globs = module.__dict__.copy()
936 globs['__name__'] = '__main__' # provide a default module name
939 tests = []
940 self._find(tests, obj, name, module, source_lines, globs, {})
941 # Sort the tests by alpha order of names, for consistency in
942 # verbose-mode output. This was a feature of doctest in Pythons
945 tests.sort()
946 return tests
948 def _from_module(self, module, object): argument
951 module.
953 if module is None:
956 return module is inspect.getmodule(object)
958 return module.__dict__ is object.__globals__
967 return module.__name__ == obj_mod
969 return module.__name__ == object.__module__
971 return module.__name__ == object.__module__
988 def _find(self, tests, obj, name, module, source_lines, globs, seen): argument
990 Find tests for the given object and any contained objects, and
991 add them to `tests`.
994 print('Finding tests in %s' % name)
1001 # Find a test for this object, and add it to the list of tests.
1002 test = self._get_test(obj, name, module, globs, source_lines)
1004 tests.append(test)
1006 # Look for tests in a module's contained objects.
1013 self._from_module(module, val)):
1014 self._find(tests, val, valname, module, source_lines,
1017 # Look for tests in a module's __test__ dictionary.
1031 self._find(tests, val, valname, module, source_lines,
1034 # Look for tests in a class's contained objects.
1044 self._from_module(module, val)):
1046 self._find(tests, val, valname, module, source_lines,
1049 def _get_test(self, obj, name, module, globs, source_lines): argument
1077 if module is None:
1081 filename = getattr(module, '__file__', None) or module.__name__
1082 if filename[-4:] == ".pyc":
1083 filename = filename[:-1]
1107 getattr(obj, '__name__', '-'))
1121 lineno = obj.co_firstlineno - 1
1150 >>> tests = DocTestFinder().find(_TestClass)
1152 >>> tests.sort(key = lambda test: test.name)
1153 >>> for test in tests:
1154 ... print(test.name, '->', runner.run(test))
1155 _TestClass -> TestResults(failed=0, attempted=2)
1156 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1157 _TestClass.get -> TestResults(failed=0, attempted=2)
1158 _TestClass.square -> TestResults(failed=0, attempted=1)
1165 4 items passed all tests:
1166 2 tests in _TestClass
1167 2 tests in _TestClass.__init__
1168 2 tests in _TestClass.get
1169 1 tests in _TestClass.square
1170 7 tests in 4 items.
1212 only failures if false; by default, it's true iff '-v' is in
1222 verbose = '-v' in sys.argv
1373 exc_msg = traceback.format_exception_only(*exception[:2])[-1]
1453 specified, then it will default to the set of future-import
1468 if encoding is None or encoding.lower() == 'utf-8':
1543 print(len(notests), "items had no tests:")
1548 print(len(passed), "items passed all tests:")
1551 print(" %3d tests in %s" % (count, thing))
1559 print(totalt, "tests in", len(self._name2ft), "items.")
1560 print(totalt - totalf, "passed and", totalf, "failed.")
1593 Convert string to hex-escaped ASCII string.
1603 several non-exact match types are also possible. See the
1608 # If `want` contains hex-escaped character such as "\u1234",
1612 # be folded to hex-escaped ASCII string to compare.
1617 # if they're string-identical, always return true.
1668 # too hard ... or maybe not. In two real-life failures Tim saw,
1671 # and could be the basis for a kick-ass diff in this case.
1676 # for 1-line differences.
1705 kind = 'unified diff with -expected +actual'
1713 kind = 'ndiff with -expected +actual'
1734 - test: the DocTest object being run
1736 - example: the Example object that failed
1738 - got: the actual output
1753 - test: the DocTest object being run
1755 - example: the Example object that failed
1757 - exc_info: the exception info
1768 r"""Run doc tests but raise an exception as soon as there is a failure.
1887 from module m (or the current module if m is not supplied), starting
1895 Return (#failures, #tests).
1899 Optional keyword arg "name" gives the name of the module; by default
1912 only failures if false; by default, it's true iff "-v" is in sys.argv.
1916 detailed, else very brief (in fact, empty if all tests passed).
1918 Optional keyword arg "optionflags" or's together module constants,
1935 post-mortem debugged.
1947 # If no module was given, then use __main__.
1949 # DWA - m will still be None if this wasn't invoked from the command
1954 # Check that we were actually given a module.
1956 raise TypeError("testmod: module required; %r" % (m,))
1958 # If no name was given, then use the module's name.
1962 # Find, parse, and run all tests in the given module.
1988 Test examples in the given file. Return (#failures, #tests).
1993 - If "module_relative" is True (the default), then "filename"
1994 specifies a module-relative path. By default, this path is
1995 relative to the calling module's directory; but if the
1997 package. To ensure os-independence, "filename" should use
1998 "/" characters to separate path segments, and should not
1999 be an absolute path (i.e., it may not begin with "/").
2001 - If "module_relative" is False, then "filename" specifies an
2002 os-specific path. The path may be absolute or relative (to
2010 base directory for a module relative filename. If no package is
2011 specified, then the calling module's directory is used as the base
2012 directory for module relative filenames. It is an error to
2025 only failures if false; by default, it's true iff "-v" is in sys.argv.
2029 detailed, else very brief (in fact, empty if all tests passed).
2031 Optional keyword arg "optionflags" or's together module constants,
2047 post-mortem debugged.
2050 subclass) that should be used to extract tests from the files.
2066 raise ValueError("Package may only be specified for module-"
2069 # Relativize the path
2071 encoding or "utf-8")
2075 name = os.path.basename(filename)
2116 it will default to the set of future-import flags that apply to
2123 # Find, parse, and run all tests in the given module.
2215 runner.DIVIDER = "-"*70
2230 lname = '.'.join(test.name.split('.')[-1:])
2240 and test suites to support post-mortem debugging. The test code
2242 caller can catch the errors and initiate post-mortem debugging.
2327 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2335 def __init__(self, module): argument
2336 self.module = module
2340 self.skipTest("DocTestSuite will not work with -O2 and above")
2346 return "Skipping tests from %s" % self.module.__name__
2357 def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, argument
2360 Convert doctest tests for a module to a unittest test suite.
2362 This converts each documentation string in a module that
2363 contains doctest tests to a unittest test case. If any of the
2364 tests in a doc string fail, then the test case fails. An exception
2368 The `module` argument provides the module to be tested. The argument
2369 can be either a module or a module name.
2371 If no argument is given, the calling module is used.
2376 A set-up function. This is called before running the
2377 tests in each file. The setUp function will be passed a DocTest
2382 A tear-down function. This is called after running the
2383 tests in each file. The tearDown function will be passed a DocTest
2388 A dictionary containing initial global variables for the tests.
2397 module = _normalize_module(module)
2398 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2400 if not tests and sys.flags.optimize >=2:
2401 # Skip doctests when running with -O2
2403 suite.addTest(SkipDocTestCase(module))
2406 tests.sort()
2409 for test in tests:
2413 filename = module.__file__
2414 if filename[-4:] == ".pyc":
2415 filename = filename[:-1]
2434 def DocFileTest(path, module_relative=True, package=None, argument
2443 raise ValueError("Package may only be specified for module-"
2446 # Relativize the path.
2447 doc, path = _load_testfile(path, package, module_relative,
2448 encoding or "utf-8")
2451 globs["__file__"] = path
2454 name = os.path.basename(path)
2457 test = parser.get_doctest(doc, globs, name, path, 0)
2463 The path to each doctest file is given as a string; the
2471 interpreted as os-independent module-relative paths. By
2472 default, these paths are relative to the calling module's
2474 they are relative to that package. To ensure os-independence,
2475 "filename" should use "/" characters to separate path
2476 segments, and may not be an absolute path (i.e., it may not
2480 interpreted as os-specific paths. These paths may be absolute
2485 should be used as the base directory for module relative paths.
2486 If "package" is not specified, then the calling module's
2487 directory is used as the base directory for module relative
2492 A set-up function. This is called before running the
2493 tests in each file. The setUp function will be passed a DocTest
2498 A tear-down function. This is called after running the
2499 tests in each file. The tearDown function will be passed a DocTest
2504 A dictionary containing initial global variables for the tests.
2511 tests from the files.
2524 for path in paths:
2525 suite.addTest(DocFileTest(path, **kw))
2595 output.append(piece.source[:-1])
2600 output += ['## '+l for l in want.split('\n')[:-1]]
2602 # Add non-example text.
2604 for l in piece.split('\n')[:-1]]
2607 while output and output[-1] == '#':
2615 def testsource(module, name): argument
2618 Provide the module (or dotted name of the module) containing the
2619 test to be debugged and the name (within the module) of the object
2620 with the doc string with tests to be debugged.
2622 module = _normalize_module(module)
2623 tests = DocTestFinder().find(module)
2624 test = [t for t in tests if t.name == name]
2626 raise ValueError(name, "not found in tests")
2656 def debug(module, name, pm=False): argument
2659 Provide the module (or dotted name of the module) containing the
2660 test to be debugged and the name (within the module) of the object
2661 with the docstring with tests to be debugged.
2663 module = _normalize_module(module)
2664 testsrc = testsource(module, name)
2665 debug_script(testsrc, pm, module.__dict__)
2672 A pointless class, for sanity-checking of docstring testing.
2678 >>> _TestClass(13).get() + _TestClass(-12).get()
2685 """val -> _TestClass object with associated value val.
2695 """square() -> square TestClass's associated value
2705 """get() -> return TestClass's associated value.
2707 >>> x = _TestClass(-42)
2709 -42
2716 Example of a string object, searched as-is.
2722 "bool-int equivalence": r"""
2769 parser.add_argument('-v', '--verbose', action='store_true', default=False,
2770 help='print very verbose output for all tests')
2771 parser.add_argument('-o', '--option', action='append',
2776 parser.add_argument('-f', '--fail-fast', action='store_true',
2777 help=('stop running tests after first failure (this'
2778 ' is a shorthand for -o FAIL_FAST, and is'
2779 ' in addition to any other -o options)'))
2781 help='file containing the tests to run')
2794 # It is a module -- insert its dir into sys.path and try to
2797 dirname, filename = os.path.split(filename)
2798 sys.path.insert(0, dirname)
2799 m = __import__(filename[:-3])
2800 del sys.path[0]