Georg Brandl | b533e26 | 2008-05-25 18:19:30 +0000 | [diff] [blame] | 1 | import sys |
| 2 | import os |
| 3 | import difflib |
| 4 | import subprocess |
| 5 | import re |
| 6 | import pydoc |
| 7 | import inspect |
| 8 | import unittest |
| 9 | import test.support |
| 10 | |
| 11 | from test import pydoc_mod |
| 12 | |
| 13 | expected_text_pattern = \ |
| 14 | """ |
| 15 | NAME |
| 16 | test.pydoc_mod - This is a test module for test_pydoc |
| 17 | |
| 18 | FILE |
| 19 | %s |
| 20 | %s |
| 21 | CLASSES |
| 22 | builtins.object |
| 23 | A |
| 24 | B |
| 25 | \x20\x20\x20\x20 |
| 26 | class A(builtins.object) |
| 27 | | Hello and goodbye |
| 28 | |\x20\x20 |
| 29 | | Methods defined here: |
| 30 | |\x20\x20 |
| 31 | | __init__() |
| 32 | | Wow, I have no function! |
| 33 | |\x20\x20 |
| 34 | | ---------------------------------------------------------------------- |
| 35 | | Data descriptors defined here: |
| 36 | |\x20\x20 |
| 37 | | __dict__ |
| 38 | | dictionary for instance variables (if defined) |
| 39 | |\x20\x20 |
| 40 | | __weakref__ |
| 41 | | list of weak references to the object (if defined) |
| 42 | \x20\x20\x20\x20 |
| 43 | class B(builtins.object) |
| 44 | | Data descriptors defined here: |
| 45 | |\x20\x20 |
| 46 | | __dict__ |
| 47 | | dictionary for instance variables (if defined) |
| 48 | |\x20\x20 |
| 49 | | __weakref__ |
| 50 | | list of weak references to the object (if defined) |
| 51 | |\x20\x20 |
| 52 | | ---------------------------------------------------------------------- |
| 53 | | Data and other attributes defined here: |
| 54 | |\x20\x20 |
| 55 | | NO_MEANING = 'eggs' |
| 56 | |
| 57 | FUNCTIONS |
| 58 | doc_func() |
| 59 | This function solves all of the world's problems: |
| 60 | hunger |
| 61 | lack of Python |
| 62 | war |
| 63 | \x20\x20\x20\x20 |
| 64 | nodoc_func() |
| 65 | |
| 66 | DATA |
| 67 | __author__ = 'Benjamin Peterson' |
| 68 | __credits__ = 'Nobody' |
| 69 | __package__ = None |
| 70 | __version__ = '1.2.3.4' |
| 71 | |
| 72 | VERSION |
| 73 | 1.2.3.4 |
| 74 | |
| 75 | AUTHOR |
| 76 | Benjamin Peterson |
| 77 | |
| 78 | CREDITS |
| 79 | Nobody |
| 80 | """.strip() |
| 81 | |
| 82 | expected_html_pattern = \ |
| 83 | """ |
| 84 | <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading"> |
| 85 | <tr bgcolor="#7799ee"> |
| 86 | <td valign=bottom> <br> |
| 87 | <font color="#ffffff" face="helvetica, arial"> <br><big><big><strong><a href="test.html"><font color="#ffffff">test</font></a>.pydoc_mod</strong></big></big> (version 1.2.3.4)</font></td |
| 88 | ><td align=right valign=bottom |
| 89 | ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:%s">%s</a>%s</font></td></tr></table> |
| 90 | <p><tt>This is a test module for test_pydoc</tt></p> |
| 91 | <p> |
| 92 | <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| 93 | <tr bgcolor="#ee77aa"> |
| 94 | <td colspan=3 valign=bottom> <br> |
| 95 | <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr> |
| 96 | \x20\x20\x20\x20 |
| 97 | <tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td> |
| 98 | <td width="100%%"><dl> |
| 99 | <dt><font face="helvetica, arial"><a href="builtins.html#object">builtins.object</a> |
| 100 | </font></dt><dd> |
| 101 | <dl> |
| 102 | <dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#A">A</a> |
| 103 | </font></dt><dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#B">B</a> |
| 104 | </font></dt></dl> |
| 105 | </dd> |
| 106 | </dl> |
| 107 | <p> |
| 108 | <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| 109 | <tr bgcolor="#ffc8d8"> |
| 110 | <td colspan=3 valign=bottom> <br> |
| 111 | <font color="#000000" face="helvetica, arial"><a name="A">class <strong>A</strong></a>(<a href="builtins.html#object">builtins.object</a>)</font></td></tr> |
| 112 | \x20\x20\x20\x20 |
| 113 | <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td> |
| 114 | <td colspan=2><tt>Hello and goodbye<br> </tt></td></tr> |
| 115 | <tr><td> </td> |
| 116 | <td width="100%%">Methods defined here:<br> |
| 117 | <dl><dt><a name="A-__init__"><strong>__init__</strong></a>()</dt><dd><tt>Wow, I have no function!</tt></dd></dl> |
| 118 | |
| 119 | <hr> |
| 120 | Data descriptors defined here:<br> |
| 121 | <dl><dt><strong>__dict__</strong></dt> |
| 122 | <dd><tt>dictionary for instance variables (if defined)</tt></dd> |
| 123 | </dl> |
| 124 | <dl><dt><strong>__weakref__</strong></dt> |
| 125 | <dd><tt>list of weak references to the object (if defined)</tt></dd> |
| 126 | </dl> |
| 127 | </td></tr></table> <p> |
| 128 | <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| 129 | <tr bgcolor="#ffc8d8"> |
| 130 | <td colspan=3 valign=bottom> <br> |
| 131 | <font color="#000000" face="helvetica, arial"><a name="B">class <strong>B</strong></a>(<a href="builtins.html#object">builtins.object</a>)</font></td></tr> |
| 132 | \x20\x20\x20\x20 |
| 133 | <tr><td bgcolor="#ffc8d8"><tt> </tt></td><td> </td> |
| 134 | <td width="100%%">Data descriptors defined here:<br> |
| 135 | <dl><dt><strong>__dict__</strong></dt> |
| 136 | <dd><tt>dictionary for instance variables (if defined)</tt></dd> |
| 137 | </dl> |
| 138 | <dl><dt><strong>__weakref__</strong></dt> |
| 139 | <dd><tt>list of weak references to the object (if defined)</tt></dd> |
| 140 | </dl> |
| 141 | <hr> |
| 142 | Data and other attributes defined here:<br> |
| 143 | <dl><dt><strong>NO_MEANING</strong> = 'eggs'</dl> |
| 144 | |
| 145 | </td></tr></table></td></tr></table><p> |
| 146 | <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| 147 | <tr bgcolor="#eeaa77"> |
| 148 | <td colspan=3 valign=bottom> <br> |
| 149 | <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr> |
| 150 | \x20\x20\x20\x20 |
| 151 | <tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td> |
| 152 | <td width="100%%"><dl><dt><a name="-doc_func"><strong>doc_func</strong></a>()</dt><dd><tt>This function solves all of the world's problems:<br> |
| 153 | hunger<br> |
| 154 | lack of Python<br> |
| 155 | war</tt></dd></dl> |
| 156 | <dl><dt><a name="-nodoc_func"><strong>nodoc_func</strong></a>()</dt></dl> |
| 157 | </td></tr></table><p> |
| 158 | <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| 159 | <tr bgcolor="#55aa55"> |
| 160 | <td colspan=3 valign=bottom> <br> |
| 161 | <font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr> |
| 162 | \x20\x20\x20\x20 |
| 163 | <tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td> |
| 164 | <td width="100%%"><strong>__author__</strong> = 'Benjamin Peterson'<br> |
| 165 | <strong>__credits__</strong> = 'Nobody'<br> |
| 166 | <strong>__package__</strong> = None<br> |
| 167 | <strong>__version__</strong> = '1.2.3.4'</td></tr></table><p> |
| 168 | <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| 169 | <tr bgcolor="#7799ee"> |
| 170 | <td colspan=3 valign=bottom> <br> |
| 171 | <font color="#ffffff" face="helvetica, arial"><big><strong>Author</strong></big></font></td></tr> |
| 172 | \x20\x20\x20\x20 |
| 173 | <tr><td bgcolor="#7799ee"><tt> </tt></td><td> </td> |
| 174 | <td width="100%%">Benjamin Peterson</td></tr></table><p> |
| 175 | <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| 176 | <tr bgcolor="#7799ee"> |
| 177 | <td colspan=3 valign=bottom> <br> |
| 178 | <font color="#ffffff" face="helvetica, arial"><big><strong>Credits</strong></big></font></td></tr> |
| 179 | \x20\x20\x20\x20 |
| 180 | <tr><td bgcolor="#7799ee"><tt> </tt></td><td> </td> |
| 181 | <td width="100%%">Nobody</td></tr></table> |
| 182 | """.strip() |
| 183 | |
| 184 | |
| 185 | # output pattern for missing module |
| 186 | missing_pattern = "no Python documentation found for '%s'" |
| 187 | |
| 188 | def run_pydoc(module_name, *args): |
| 189 | """ |
| 190 | Runs pydoc on the specified module. Returns the stripped |
| 191 | output of pydoc. |
| 192 | """ |
| 193 | cmd = [sys.executable, pydoc.__file__, " ".join(args), module_name] |
| 194 | output = subprocess.Popen(cmd, stdout=subprocess.PIPE).stdout.read() |
| 195 | return output.strip() |
| 196 | |
| 197 | def get_pydoc_html(module): |
| 198 | "Returns pydoc generated output as html" |
| 199 | doc = pydoc.HTMLDoc() |
| 200 | output = doc.docmodule(module) |
| 201 | loc = doc.getdocloc(pydoc_mod) or "" |
| 202 | if loc: |
| 203 | loc = "<br><a href=\"" + loc + "\">Module Docs</a>" |
| 204 | return output.strip(), loc |
| 205 | |
| 206 | def get_pydoc_text(module): |
| 207 | "Returns pydoc generated output as text" |
| 208 | doc = pydoc.TextDoc() |
| 209 | loc = doc.getdocloc(pydoc_mod) or "" |
| 210 | if loc: |
| 211 | loc = "\nMODULE DOCS\n " + loc + "\n" |
| 212 | |
| 213 | output = doc.docmodule(module) |
| 214 | |
| 215 | # cleanup the extra text formatting that pydoc preforms |
| 216 | patt = re.compile('\b.') |
| 217 | output = patt.sub('', output) |
| 218 | return output.strip(), loc |
| 219 | |
| 220 | def print_diffs(text1, text2): |
| 221 | "Prints unified diffs for two texts" |
| 222 | lines1 = text1.splitlines(True) |
| 223 | lines2 = text2.splitlines(True) |
| 224 | diffs = difflib.unified_diff(lines1, lines2, n=0, fromfile='expected', |
| 225 | tofile='got') |
| 226 | print('\n' + ''.join(diffs)) |
| 227 | |
| 228 | |
| 229 | class PyDocDocTest(unittest.TestCase): |
| 230 | |
| 231 | def test_html_doc(self): |
| 232 | result, doc_loc = get_pydoc_html(pydoc_mod) |
| 233 | mod_file = inspect.getabsfile(pydoc_mod) |
| 234 | expected_html = expected_html_pattern % (mod_file, mod_file, doc_loc) |
| 235 | if result != expected_html: |
| 236 | print_diffs(expected_html, result) |
| 237 | self.fail("outputs are not equal, see diff above") |
| 238 | |
| 239 | def test_text_doc(self): |
| 240 | result, doc_loc = get_pydoc_text(pydoc_mod) |
| 241 | expected_text = expected_text_pattern % \ |
| 242 | (inspect.getabsfile(pydoc_mod), doc_loc) |
| 243 | if result != expected_text: |
| 244 | print_diffs(expected_text, result) |
| 245 | self.fail("outputs are not equal, see diff above") |
| 246 | |
| 247 | def test_not_here(self): |
| 248 | missing_module = "test.i_am_not_here" |
| 249 | result = str(run_pydoc(missing_module), 'ascii') |
| 250 | expected = missing_pattern % missing_module |
| 251 | self.assertEqual(expected, result, |
| 252 | "documentation for missing module found") |
| 253 | |
| 254 | |
| 255 | class TestDescriptions(unittest.TestCase): |
| 256 | |
| 257 | def test_module(self): |
| 258 | # Check that pydocfodder module can be described |
| 259 | from test import pydocfodder |
| 260 | doc = pydoc.render_doc(pydocfodder) |
| 261 | self.assert_("pydocfodder" in doc) |
| 262 | |
| 263 | def test_classic_class(self): |
| 264 | class C: "Classic class" |
| 265 | c = C() |
| 266 | self.assertEqual(pydoc.describe(C), 'class C') |
| 267 | self.assertEqual(pydoc.describe(c), 'C') |
| 268 | expected = 'C in module %s' % __name__ |
| 269 | self.assert_(expected in pydoc.render_doc(c)) |
| 270 | |
| 271 | def test_class(self): |
| 272 | class C(object): "New-style class" |
| 273 | c = C() |
| 274 | |
| 275 | self.assertEqual(pydoc.describe(C), 'class C') |
| 276 | self.assertEqual(pydoc.describe(c), 'C') |
| 277 | expected = 'C in module %s object' % __name__ |
| 278 | self.assert_(expected in pydoc.render_doc(c)) |
| 279 | |
| 280 | |
| 281 | def test_main(): |
| 282 | test.support.run_unittest(PyDocDocTest, TestDescriptions) |
| 283 | |
| 284 | if __name__ == "__main__": |
| 285 | test_main() |