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
107 # - Example: a <source, want> pair, plus an intra-docstring line number.
108 # - DocTest: a collection of examples, parsed from a docstring, plus
110 # - DocTestFinder: extracts DocTests from a given object's docstring and
112 # - DocTestRunner: runs DocTest cases, and accumulates statistics.
117 # +------+ +---------+ +-------+
118 # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
119 # +------+ +---------+ +-------+
123 # +---------+
164 # 2. Example & DocTest -- store test cases
165 # 3. DocTest Parser -- extracts examples from strings
166 # 4. DocTest Finder -- extracts test cases from objects
167 # 5. DocTest Runner -- runs test cases
168 # 6. Test Functions -- convenient wrappers for testing
169 # 7. Tester Class -- for backwards compatibility
180 Return the compiler-flags associated with the future features that
190 def _normalize_module(module, depth=2): argument
192 Return the module specified by `module`. In particular:
193 - If `module` is a module, then return module.
194 - If `module` is a string, then import and return the
195 module with that name.
196 - If `module` is None, then return the calling module.
197 The calling module is assumed to be the module of
200 if inspect.ismodule(module):
201 return module
202 elif isinstance(module, (str, unicode)):
203 return __import__(module, globals(), locals(), ["*"])
204 elif module is None:
207 raise TypeError("Expected a module, string, or None")
223 _encoding = getattr(sys.__stdout__, 'encoding', None) or 'utf-8'
228 every non-blank line in `s`, and return the result.
234 # This regexp matches the start of non-blank lines:
271 # Worst-case linear-time ellipsis matching.
294 w = ws[-1]
297 endpos -= len(w)
298 del ws[-1]
307 # For the rest, we only need to find the leftmost non-overlapping
332 # 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, path): argument
392 if not inspect.ismodule(module):
393 raise TypeError, 'Expected a module: %r' % module
394 if path.startswith('/'):
395 raise ValueError, 'Module-relative files may not have absolute paths'
397 # Find the base directory for the path.
398 if hasattr(module, '__file__'):
399 # A normal module/package
400 basedir = os.path.split(module.__file__)[0]
401 elif module.__name__ == '__main__':
404 basedir = os.path.split(sys.argv[0])[0]
408 # A module w/o __file__ (this includes builtins)
409 raise ValueError("Can't resolve paths relative to the module " +
410 module + " (it has no __file__)")
412 # Combine the base directory and the path.
413 return os.path.join(basedir, *(path.split('/')))
418 ## - An "example" is a <source, want> pair, where "source" is a
423 ## - A "doctest" is a collection of examples, typically extracted from
432 - source: A single Python statement, always ending with a newline.
435 - want: The expected output from running the source code (either
440 - exc_msg: The exception message generated by the example, if
448 - lineno: The line number within the DocTest string containing
450 zero-based, with respect to the beginning of the DocTest.
452 - indent: The example's indentation in the DocTest string.
456 - options: A dictionary mapping from option flags to True or
504 - examples: the list of examples.
506 - globs: The namespace (aka globals) that the examples should
509 - name: A name identifying the DocTest (typically, the name of
512 - filename: The name of the file that this DocTest was extracted
515 - lineno: The line number within filename where this DocTest
517 line number is zero-based, with respect to the beginning of
520 - docstring: The string that the examples were extracted from,
564 # This lets us sort tests by name:
567 return -1
590 # Want consists of any non-blank lines that do not start with PS1.
599 # - the traceback header line (`hdr`)
600 # - the traceback stack (`stack`)
601 # - the exception message (`msg`), as generated by
604 # exception message is the first non-indented line starting with a word
627 Line numbers for the Examples are 0-based. The optional
641 # Add the pre-example text to `output`.
658 # Add any remaining post-example text to `output`.
678 0-based, because it's most common in doctests that nothing
679 interesting appears on the same line as opening triple-quote,
714 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
715 del want_lines[-1] # forget final newline & spaces after it
735 # positives for string-literals that contain the string
755 if (option[0] not in '+-' or
768 # This regular expression finds the indentation of every non-blank
773 "Return the minimum indentation of any non-blank line in `s`"
834 will include tests for objects with empty docstrings.
841 def find(self, obj, name=None, module=None, globs=None, extraglobs=None): argument
847 The optional parameter `module` is the module that contains
848 the given object. If the module is not specified or is None, then
850 correct module. The object's module is used:
852 - As a default namespace, if `globs` is not specified.
853 - To prevent the DocTestFinder from extracting DocTests
855 - To find the name of the file containing the object.
856 - To help find the line number of the object within its
859 Contained objects whose module does not match `module` are ignored.
861 If `module` is False, no attempt to find the module will be made.
862 This is obscure, of use mostly in tests: if `module` is False, or
864 considered to belong to the (non-existent) module, so all contained
871 defaults to the module's `__dict__`, if specified, or {}
884 # Find the module that contains the given object (if obj is
885 # a module, then module=obj.). Note: this may fail, in which
886 # case module will be None.
887 if module is False:
888 module = None
889 elif module is None:
890 module = inspect.getmodule(obj)
892 # Read the module's source code. This is used by
897 if module is not None:
898 # Supply the module globals in case the module was
900 # file is not a valid filesystem path
901 source_lines = linecache.getlines(file, module.__dict__)
904 # filesystem path
913 if module is None:
916 globs = module.__dict__.copy()
922 globs['__name__'] = '__main__' # provide a default module name
925 tests = []
926 self._find(tests, obj, name, module, source_lines, globs, {})
927 # Sort the tests by alpha order of names, for consistency in
928 # verbose-mode output. This was a feature of doctest in Pythons
931 tests.sort()
932 return tests
934 def _from_module(self, module, object): argument
937 module.
939 if module is None:
942 return module is inspect.getmodule(object)
944 return module.__dict__ is object.func_globals
946 return module.__name__ == object.__module__
948 return module.__name__ == object.__module__
954 def _find(self, tests, obj, name, module, source_lines, globs, seen): argument
956 Find tests for the given object and any contained objects, and
957 add them to `tests`.
960 print 'Finding tests in %s' % name
967 # Find a test for this object, and add it to the list of tests.
968 test = self._get_test(obj, name, module, globs, source_lines)
970 tests.append(test)
972 # Look for tests in a module's contained objects.
978 self._from_module(module, val)):
979 self._find(tests, val, valname, module, source_lines,
982 # Look for tests in a module's __test__ dictionary.
997 self._find(tests, val, valname, module, source_lines,
1000 # Look for tests in a class's contained objects.
1012 self._from_module(module, val)):
1014 self._find(tests, val, valname, module, source_lines,
1017 def _get_test(self, obj, name, module, globs, source_lines): argument
1045 if module is None:
1048 filename = getattr(module, '__file__', module.__name__)
1049 if filename[-4:] in (".pyc", ".pyo"):
1050 filename = filename[:-1]
1072 getattr(obj, '__name__', '-'))
1084 lineno = getattr(obj, 'co_firstlineno', None)-1
1113 >>> tests = DocTestFinder().find(_TestClass)
1115 >>> tests.sort(key = lambda test: test.name)
1116 >>> for test in tests:
1117 ... print test.name, '->', runner.run(test)
1118 _TestClass -> TestResults(failed=0, attempted=2)
1119 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1120 _TestClass.get -> TestResults(failed=0, attempted=2)
1121 _TestClass.square -> TestResults(failed=0, attempted=1)
1128 4 items passed all tests:
1129 2 tests in _TestClass
1130 2 tests in _TestClass.__init__
1131 2 tests in _TestClass.get
1132 1 tests in _TestClass.square
1133 7 tests in 4 items.
1175 only failures if false; by default, it's true iff '-v' is in
1185 verbose = '-v' in sys.argv
1337 exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
1417 specified, then it will default to the set of future-import
1496 print len(notests), "items had no tests:"
1501 print len(passed), "items passed all tests:"
1504 print " %3d tests in %s" % (count, thing)
1512 print totalt, "tests in", len(self._name2ft), "items."
1513 print totalt - totalf, "passed and", totalf, "failed."
1550 several non-exact match types are also possible. See the
1555 # if they're string-identical, always return true.
1606 # too hard ... or maybe not. In two real-life failures Tim saw,
1609 # and could be the basis for a kick-ass diff in this case.
1614 # for 1-line differences.
1643 kind = 'unified diff with -expected +actual'
1651 kind = 'ndiff with -expected +actual'
1674 - test: the DocTest object being run
1676 - example: the Example object that failed
1678 - got: the actual output
1693 - test: the DocTest object being run
1695 - example: the Example object that failed
1697 - exc_info: the exception info
1708 r"""Run doc tests but raise an exception as soon as there is a failure.
1827 from module m (or the current module if m is not supplied), starting
1835 Return (#failures, #tests).
1839 Optional keyword arg "name" gives the name of the module; by default
1852 only failures if false; by default, it's true iff "-v" is in sys.argv.
1856 detailed, else very brief (in fact, empty if all tests passed).
1858 Optional keyword arg "optionflags" or's together module constants,
1875 post-mortem debugged.
1887 # If no module was given, then use __main__.
1889 # DWA - m will still be None if this wasn't invoked from the command
1894 # Check that we were actually given a module.
1896 raise TypeError("testmod: module required; %r" % (m,))
1898 # If no name was given, then use the module's name.
1902 # Find, parse, and run all tests in the given module.
1928 Test examples in the given file. Return (#failures, #tests).
1933 - If "module_relative" is True (the default), then "filename"
1934 specifies a module-relative path. By default, this path is
1935 relative to the calling module's directory; but if the
1937 package. To ensure os-independence, "filename" should use
1938 "/" characters to separate path segments, and should not
1939 be an absolute path (i.e., it may not begin with "/").
1941 - If "module_relative" is False, then "filename" specifies an
1942 os-specific path. The path may be absolute or relative (to
1950 base directory for a module relative filename. If no package is
1951 specified, then the calling module's directory is used as the base
1952 directory for module relative filenames. It is an error to
1965 only failures if false; by default, it's true iff "-v" is in sys.argv.
1969 detailed, else very brief (in fact, empty if all tests passed).
1971 Optional keyword arg "optionflags" or's together module constants,
1987 post-mortem debugged.
1990 subclass) that should be used to extract tests from the files.
2006 raise ValueError("Package may only be specified for module-"
2009 # Relativize the path
2014 name = os.path.basename(filename)
2058 it will default to the set of future-import flags that apply to
2065 # Find, parse, and run all tests in the given module.
2086 raise TypeError("Tester.__init__: mod must be a module; %r" %
2107 def rundoc(self, object, name=None, module=None): argument
2109 tests = self.testfinder.find(object, name, module=module,
2111 for test in tests:
2116 def rundict(self, d, name, module=None): argument
2120 if module is None:
2121 module = False
2122 return self.rundoc(m, name, module)
2219 runner.DIVIDER = "-"*70
2234 lname = '.'.join(test.name.split('.')[-1:])
2244 and test suites to support post-mortem debugging. The test code
2246 caller can catch the errors and initiate post-mortem debugging.
2334 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2342 def __init__(self, module): argument
2343 self.module = module
2347 self.skipTest("DocTestSuite will not work with -O2 and above")
2353 return "Skipping tests from %s" % self.module.__name__
2358 def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, argument
2361 Convert doctest tests for a module to a unittest test suite.
2363 This converts each documentation string in a module that
2364 contains doctest tests to a unittest test case. If any of the
2365 tests in a doc string fail, then the test case fails. An exception
2369 The `module` argument provides the module to be tested. The argument
2370 can be either a module or a module name.
2372 If no argument is given, the calling module is used.
2377 A set-up function. This is called before running the
2378 tests in each file. The setUp function will be passed a DocTest
2383 A tear-down function. This is called after running the
2384 tests in each file. The tearDown function will be passed a DocTest
2389 A dictionary containing initial global variables for the tests.
2398 module = _normalize_module(module)
2399 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2401 if not tests and sys.flags.optimize >=2:
2402 # Skip doctests when running with -O2
2404 suite.addTest(SkipDocTestCase(module))
2406 elif not tests:
2410 # number of doctest examples in tests is zero (i.e. if no doctest
2414 raise ValueError(module, "has no docstrings")
2416 tests.sort()
2419 for test in tests:
2423 filename = module.__file__
2424 if filename[-4:] in (".pyc", ".pyo"):
2425 filename = filename[:-1]
2445 def DocFileTest(path, module_relative=True, package=None, argument
2454 raise ValueError("Package may only be specified for module-"
2457 # Relativize the path.
2458 doc, path = _load_testfile(path, package, module_relative)
2461 globs["__file__"] = path
2464 name = os.path.basename(path)
2471 test = parser.get_doctest(doc, globs, name, path, 0)
2477 The path to each doctest file is given as a string; the
2485 interpreted as os-independent module-relative paths. By
2486 default, these paths are relative to the calling module's
2488 they are relative to that package. To ensure os-independence,
2489 "filename" should use "/" characters to separate path
2490 segments, and may not be an absolute path (i.e., it may not
2494 interpreted as os-specific paths. These paths may be absolute
2499 should be used as the base directory for module relative paths.
2500 If "package" is not specified, then the calling module's
2501 directory is used as the base directory for module relative
2506 A set-up function. This is called before running the
2507 tests in each file. The setUp function will be passed a DocTest
2512 A tear-down function. This is called after running the
2513 tests in each file. The tearDown function will be passed a DocTest
2518 A dictionary containing initial global variables for the tests.
2525 tests from the files.
2538 for path in paths:
2539 suite.addTest(DocFileTest(path, **kw))
2609 output.append(piece.source[:-1])
2614 output += ['## '+l for l in want.split('\n')[:-1]]
2616 # Add non-example text.
2618 for l in piece.split('\n')[:-1]]
2621 while output and output[-1] == '#':
2629 def testsource(module, name): argument
2632 Provide the module (or dotted name of the module) containing the
2633 test to be debugged and the name (within the module) of the object
2634 with the doc string with tests to be debugged.
2636 module = _normalize_module(module)
2637 tests = DocTestFinder().find(module)
2638 test = [t for t in tests if t.name == name]
2640 raise ValueError(name, "not found in tests")
2682 def debug(module, name, pm=False): argument
2685 Provide the module (or dotted name of the module) containing the
2686 test to be debugged and the name (within the module) of the object
2687 with the docstring with tests to be debugged.
2689 module = _normalize_module(module)
2690 testsrc = testsource(module, name)
2691 debug_script(testsrc, pm, module.__dict__)
2698 A pointless class, for sanity-checking of docstring testing.
2704 >>> _TestClass(13).get() + _TestClass(-12).get()
2711 """val -> _TestClass object with associated value val.
2721 """square() -> square TestClass's associated value
2731 """get() -> return TestClass's associated value.
2733 >>> x = _TestClass(-42)
2735 -42
2742 Example of a string object, searched as-is.
2748 "bool-int equivalence": r"""
2792 testfiles = [arg for arg in sys.argv[1:] if arg and arg[0] != '-']
2794 name = os.path.basename(sys.argv[0])
2795 if '__loader__' in globals(): # python -m
2796 name, _ = os.path.splitext(name)
2797 print("usage: {0} [-v] file ...".format(name))
2801 # It is a module -- insert its dir into sys.path and try to
2804 dirname, filename = os.path.split(filename)
2805 sys.path.insert(0, dirname)
2806 m = __import__(filename[:-3])
2807 del sys.path[0]