|
| 1 | +"""Experimental code for cleaner support of IPython syntax with unittest. |
| 2 | +
|
| 3 | +In IPython up until 0.10, we've used very hacked up nose machinery for running |
| 4 | +tests with IPython special syntax, and this has proved to be extremely slow. |
| 5 | +This module provides decorators to try a different approach, stemming from a |
| 6 | +conversation Brian and I (FP) had about this problem Sept/09. |
| 7 | +
|
| 8 | +The goal is to be able to easily write simple functions that can be seen by |
| 9 | +unittest as tests, and ultimately for these to support doctests with full |
| 10 | +IPython syntax. Nose already offers this based on naming conventions and our |
| 11 | +hackish plugins, but we are seeking to move away from nose dependencies if |
| 12 | +possible. |
| 13 | +
|
| 14 | +This module follows a different approach, based on decorators. |
| 15 | +
|
| 16 | +- A decorator called @ipdoctest can mark any function as having a docstring |
| 17 | + that should be viewed as a doctest, but after syntax conversion. |
| 18 | +
|
| 19 | +Authors |
| 20 | +------- |
| 21 | +
|
| 22 | +- Fernando Perez <[email protected]> |
| 23 | +""" |
| 24 | + |
| 25 | +#----------------------------------------------------------------------------- |
| 26 | +# Copyright (C) 2009 The IPython Development Team |
| 27 | +# |
| 28 | +# Distributed under the terms of the BSD License. The full license is in |
| 29 | +# the file COPYING, distributed as part of this software. |
| 30 | +#----------------------------------------------------------------------------- |
| 31 | + |
| 32 | + |
| 33 | +#----------------------------------------------------------------------------- |
| 34 | +# Imports |
| 35 | +#----------------------------------------------------------------------------- |
| 36 | + |
| 37 | +# Stdlib |
| 38 | +import re |
| 39 | +import sys |
| 40 | +import unittest |
| 41 | +from doctest import DocTestFinder, DocTestRunner, TestResults |
| 42 | + |
| 43 | +# Our own |
| 44 | +import nosepatch |
| 45 | + |
| 46 | +# We already have python3-compliant code for parametric tests |
| 47 | +if sys.version[0]=='2': |
| 48 | + from _paramtestpy2 import ParametricTestCase |
| 49 | +else: |
| 50 | + from _paramtestpy3 import ParametricTestCase |
| 51 | + |
| 52 | +#----------------------------------------------------------------------------- |
| 53 | +# Classes and functions |
| 54 | +#----------------------------------------------------------------------------- |
| 55 | + |
| 56 | +def count_failures(runner): |
| 57 | + """Count number of failures in a doctest runner. |
| 58 | +
|
| 59 | + Code modeled after the summarize() method in doctest. |
| 60 | + """ |
| 61 | + return [TestResults(f, t) for f, t in runner._name2ft.values() if f > 0 ] |
| 62 | + |
| 63 | + |
| 64 | +class IPython2PythonConverter(object): |
| 65 | + """Convert IPython 'syntax' to valid Python. |
| 66 | +
|
| 67 | + Eventually this code may grow to be the full IPython syntax conversion |
| 68 | + implementation, but for now it only does prompt convertion.""" |
| 69 | + |
| 70 | + def __init__(self): |
| 71 | + self.ps1 = re.compile(r'In\ \[\d+\]: ') |
| 72 | + self.ps2 = re.compile(r'\ \ \ \.\.\.+: ') |
| 73 | + self.out = re.compile(r'Out\[\d+\]: \s*?\n?') |
| 74 | + |
| 75 | + def __call__(self, ds): |
| 76 | + """Convert IPython prompts to python ones in a string.""" |
| 77 | + pyps1 = '>>> ' |
| 78 | + pyps2 = '... ' |
| 79 | + pyout = '' |
| 80 | + |
| 81 | + dnew = ds |
| 82 | + dnew = self.ps1.sub(pyps1, dnew) |
| 83 | + dnew = self.ps2.sub(pyps2, dnew) |
| 84 | + dnew = self.out.sub(pyout, dnew) |
| 85 | + return dnew |
| 86 | + |
| 87 | + |
| 88 | +class Doc2UnitTester(object): |
| 89 | + """Class whose instances act as a decorator for docstring testing. |
| 90 | +
|
| 91 | + In practice we're only likely to need one instance ever, made below (though |
| 92 | + no attempt is made at turning it into a singleton, there is no need for |
| 93 | + that). |
| 94 | + """ |
| 95 | + def __init__(self, verbose=False): |
| 96 | + """New decorator. |
| 97 | +
|
| 98 | + Parameters |
| 99 | + ---------- |
| 100 | +
|
| 101 | + verbose : boolean, optional (False) |
| 102 | + Passed to the doctest finder and runner to control verbosity. |
| 103 | + """ |
| 104 | + self.verbose = verbose |
| 105 | + # We can reuse the same finder for all instances |
| 106 | + self.finder = DocTestFinder(verbose=verbose, recurse=False) |
| 107 | + |
| 108 | + def __call__(self, func): |
| 109 | + """Use as a decorator: doctest a function's docstring as a unittest. |
| 110 | + |
| 111 | + This version runs normal doctests, but the idea is to make it later run |
| 112 | + ipython syntax instead.""" |
| 113 | + |
| 114 | + # Capture the enclosing instance with a different name, so the new |
| 115 | + # class below can see it without confusion regarding its own 'self' |
| 116 | + # that will point to the test instance at runtime |
| 117 | + d2u = self |
| 118 | + |
| 119 | + # Rewrite the function's docstring to have python syntax |
| 120 | + if func.__doc__ is not None: |
| 121 | + func.__doc__ = ip2py(func.__doc__) |
| 122 | + |
| 123 | + # Now, create a tester object that is a real unittest instance, so |
| 124 | + # normal unittest machinery (or Nose, or Trial) can find it. |
| 125 | + class Tester(unittest.TestCase): |
| 126 | + def test(self): |
| 127 | + # Make a new runner per function to be tested |
| 128 | + runner = DocTestRunner(verbose=d2u.verbose) |
| 129 | + map(runner.run, d2u.finder.find(func, func.__name__)) |
| 130 | + failed = count_failures(runner) |
| 131 | + if failed: |
| 132 | + # Since we only looked at a single function's docstring, |
| 133 | + # failed should contain at most one item. More than that |
| 134 | + # is a case we can't handle and should error out on |
| 135 | + if len(failed) > 1: |
| 136 | + err = "Invalid number of test results:" % failed |
| 137 | + raise ValueError(err) |
| 138 | + # Report a normal failure. |
| 139 | + self.fail('failed doctests: %s' % str(failed[0])) |
| 140 | + |
| 141 | + # Rename it so test reports have the original signature. |
| 142 | + Tester.__name__ = func.__name__ |
| 143 | + return Tester |
| 144 | + |
| 145 | + |
| 146 | +def ipdocstring(func): |
| 147 | + """Change the function docstring via ip2py. |
| 148 | + """ |
| 149 | + if func.__doc__ is not None: |
| 150 | + func.__doc__ = ip2py(func.__doc__) |
| 151 | + return func |
| 152 | + |
| 153 | + |
| 154 | +# Make an instance of the classes for public use |
| 155 | +ipdoctest = Doc2UnitTester() |
| 156 | +ip2py = IPython2PythonConverter() |
0 commit comments