Lib/test/test_pydoc.py

   1 import sys
   2 import os
   3 import os.path
   4 import difflib
   5 import subprocess
   6 import re
   7 import pydoc
   8 import inspect
   9 import unittest
  10 import xml.etree
  11 import test.test_support
  12 from contextlib import contextmanager
  13 from test.test_support import (
  14     TESTFN, forget, rmtree, EnvironmentVarGuard, reap_children)
  15
  16 from test import pydoc_mod
  17
  18 expected_text_pattern = \
  19 """
  20 NAME
  21     test.pydoc_mod - This is a test module for test_pydoc
  22
  23 FILE
  24     %s
  25 %s
  26 CLASSES
  27     __builtin__.object
  28         B
  29     A
  30 \x20\x20\x20\x20
  31     class A
  32      |  Hello and goodbye
  33      |\x20\x20
  34      |  Methods defined here:
  35      |\x20\x20
  36      |  __init__()
  37      |      Wow, I have no function!
  38 \x20\x20\x20\x20
  39     class B(__builtin__.object)
  40      |  Data descriptors defined here:
  41      |\x20\x20
  42      |  __dict__
  43      |      dictionary for instance variables (if defined)
  44      |\x20\x20
  45      |  __weakref__
  46      |      list of weak references to the object (if defined)
  47      |\x20\x20
  48      |  ----------------------------------------------------------------------
  49      |  Data and other attributes defined here:
  50      |\x20\x20
  51      |  NO_MEANING = 'eggs'
  52
  53 FUNCTIONS
  54     doc_func()
  55         This function solves all of the world's problems:
  56         hunger
  57         lack of Python
  58         war
  59 \x20\x20\x20\x20
  60     nodoc_func()
  61
  62 DATA
  63     __author__ = 'Benjamin Peterson'
  64     __credits__ = 'Nobody'
  65     __version__ = '1.2.3.4'
  66
  67 VERSION
  68     1.2.3.4
  69
  70 AUTHOR
  71     Benjamin Peterson
  72
  73 CREDITS
  74     Nobody
  75 """.strip()
  76
  77 expected_html_pattern = \
  78 """
  79 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
  80 <tr bgcolor="#7799ee">
  81 <td valign=bottom>&nbsp;<br>
  82 <font color="#ffffff" face="helvetica, arial">&nbsp;<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
  83 ><td align=right valign=bottom
  84 ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:%s">%s</a>%s</font></td></tr></table>
  85     <p><tt>This&nbsp;is&nbsp;a&nbsp;test&nbsp;module&nbsp;for&nbsp;test_pydoc</tt></p>
  86 <p>
  87 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
  88 <tr bgcolor="#ee77aa">
  89 <td colspan=3 valign=bottom>&nbsp;<br>
  90 <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr>
  91 \x20\x20\x20\x20
  92 <tr><td bgcolor="#ee77aa"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
  93 <td width="100%%"><dl>
  94 <dt><font face="helvetica, arial"><a href="__builtin__.html#object">__builtin__.object</a>
  95 </font></dt><dd>
  96 <dl>
  97 <dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#B">B</a>
  98 </font></dt></dl>
  99 </dd>
 100 <dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#A">A</a>
 101 </font></dt></dl>
 102  <p>
 103 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
 104 <tr bgcolor="#ffc8d8">
 105 <td colspan=3 valign=bottom>&nbsp;<br>
 106 <font color="#000000" face="helvetica, arial"><a name="A">class <strong>A</strong></a></font></td></tr>
 107 \x20\x20\x20\x20
 108 <tr bgcolor="#ffc8d8"><td rowspan=2><tt>&nbsp;&nbsp;&nbsp;</tt></td>
 109 <td colspan=2><tt>Hello&nbsp;and&nbsp;goodbye<br>&nbsp;</tt></td></tr>
 110 <tr><td>&nbsp;</td>
 111 <td width="100%%">Methods defined here:<br>
 112 <dl><dt><a name="A-__init__"><strong>__init__</strong></a>()</dt><dd><tt>Wow,&nbsp;I&nbsp;have&nbsp;no&nbsp;function!</tt></dd></dl>
 113
 114 </td></tr></table> <p>
 115 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
 116 <tr bgcolor="#ffc8d8">
 117 <td colspan=3 valign=bottom>&nbsp;<br>
 118 <font color="#000000" face="helvetica, arial"><a name="B">class <strong>B</strong></a>(<a href="__builtin__.html#object">__builtin__.object</a>)</font></td></tr>
 119 \x20\x20\x20\x20
 120 <tr><td bgcolor="#ffc8d8"><tt>&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
 121 <td width="100%%">Data descriptors defined here:<br>
 122 <dl><dt><strong>__dict__</strong></dt>
 123 <dd><tt>dictionary&nbsp;for&nbsp;instance&nbsp;variables&nbsp;(if&nbsp;defined)</tt></dd>
 124 </dl>
 125 <dl><dt><strong>__weakref__</strong></dt>
 126 <dd><tt>list&nbsp;of&nbsp;weak&nbsp;references&nbsp;to&nbsp;the&nbsp;object&nbsp;(if&nbsp;defined)</tt></dd>
 127 </dl>
 128 <hr>
 129 Data and other attributes defined here:<br>
 130 <dl><dt><strong>NO_MEANING</strong> = 'eggs'</dl>
 131
 132 </td></tr></table></td></tr></table><p>
 133 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
 134 <tr bgcolor="#eeaa77">
 135 <td colspan=3 valign=bottom>&nbsp;<br>
 136 <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
 137 \x20\x20\x20\x20
 138 <tr><td bgcolor="#eeaa77"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
 139 <td width="100%%"><dl><dt><a name="-doc_func"><strong>doc_func</strong></a>()</dt><dd><tt>This&nbsp;function&nbsp;solves&nbsp;all&nbsp;of&nbsp;the&nbsp;world's&nbsp;problems:<br>
 140 hunger<br>
 141 lack&nbsp;of&nbsp;Python<br>
 142 war</tt></dd></dl>
 143  <dl><dt><a name="-nodoc_func"><strong>nodoc_func</strong></a>()</dt></dl>
 144 </td></tr></table><p>
 145 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
 146 <tr bgcolor="#55aa55">
 147 <td colspan=3 valign=bottom>&nbsp;<br>
 148 <font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
 149 \x20\x20\x20\x20
 150 <tr><td bgcolor="#55aa55"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
 151 <td width="100%%"><strong>__author__</strong> = 'Benjamin Peterson'<br>
 152 <strong>__credits__</strong> = 'Nobody'<br>
 153 <strong>__version__</strong> = '1.2.3.4'</td></tr></table><p>
 154 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
 155 <tr bgcolor="#7799ee">
 156 <td colspan=3 valign=bottom>&nbsp;<br>
 157 <font color="#ffffff" face="helvetica, arial"><big><strong>Author</strong></big></font></td></tr>
 158 \x20\x20\x20\x20
 159 <tr><td bgcolor="#7799ee"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
 160 <td width="100%%">Benjamin&nbsp;Peterson</td></tr></table><p>
 161 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
 162 <tr bgcolor="#7799ee">
 163 <td colspan=3 valign=bottom>&nbsp;<br>
 164 <font color="#ffffff" face="helvetica, arial"><big><strong>Credits</strong></big></font></td></tr>
 165 \x20\x20\x20\x20
 166 <tr><td bgcolor="#7799ee"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
 167 <td width="100%%">Nobody</td></tr></table>
 168 """.strip()
 169
 170
 171 # output pattern for missing module
 172 missing_pattern = "no Python documentation found for '%s'"
 173
 174 # output pattern for module with bad imports
 175 badimport_pattern = "problem in %s - <type 'exceptions.ImportError'>: No module named %s"
 176
 177 def run_pydoc(module_name, *args):
 178     """
 179     Runs pydoc on the specified module. Returns the stripped
 180     output of pydoc.
 181     """
 182     cmd = [sys.executable, pydoc.__file__, " ".join(args), module_name]
 183     try:
 184         output = subprocess.Popen(cmd, stdout=subprocess.PIPE).communicate()[0]
 185         return output.strip()
 186     finally:
 187         reap_children()
 188
 189 def get_pydoc_html(module):
 190     "Returns pydoc generated output as html"
 191     doc = pydoc.HTMLDoc()
 192     output = doc.docmodule(module)
 193     loc = doc.getdocloc(pydoc_mod) or ""
 194     if loc:
 195         loc = "<br><a href=\"" + loc + "\">Module Docs</a>"
 196     return output.strip(), loc
 197
 198 def get_pydoc_text(module):
 199     "Returns pydoc generated output as text"
 200     doc = pydoc.TextDoc()
 201     loc = doc.getdocloc(pydoc_mod) or ""
 202     if loc:
 203         loc = "\nMODULE DOCS\n    " + loc + "\n"
 204
 205     output = doc.docmodule(module)
 206
 207     # cleanup the extra text formatting that pydoc preforms
 208     patt = re.compile('\b.')
 209     output = patt.sub('', output)
 210     return output.strip(), loc
 211
 212 def print_diffs(text1, text2):
 213     "Prints unified diffs for two texts"
 214     lines1 = text1.splitlines(True)
 215     lines2 = text2.splitlines(True)
 216     diffs = difflib.unified_diff(lines1, lines2, n=0, fromfile='expected',
 217                                  tofile='got')
 218     print '\n' + ''.join(diffs)
 219
 220
 221 class PyDocDocTest(unittest.TestCase):
 222
 223     @unittest.skipIf(sys.flags.optimize >= 2,
 224                      "Docstrings are omitted with -O2 and above")
 225     def test_html_doc(self):
 226         result, doc_loc = get_pydoc_html(pydoc_mod)
 227         mod_file = inspect.getabsfile(pydoc_mod)
 228         if sys.platform == 'win32':
 229             import nturl2path
 230             mod_url = nturl2path.pathname2url(mod_file)
 231         else:
 232             mod_url = mod_file
 233         expected_html = expected_html_pattern % (mod_url, mod_file, doc_loc)
 234         if result != expected_html:
 235             print_diffs(expected_html, result)
 236             self.fail("outputs are not equal, see diff above")
 237
 238     @unittest.skipIf(sys.flags.optimize >= 2,
 239                      "Docstrings are omitted with -O2 and above")
 240     def test_text_doc(self):
 241         result, doc_loc = get_pydoc_text(pydoc_mod)
 242         expected_text = expected_text_pattern % \
 243                         (inspect.getabsfile(pydoc_mod), doc_loc)
 244         if result != expected_text:
 245             print_diffs(expected_text, result)
 246             self.fail("outputs are not equal, see diff above")
 247
 248     def test_issue8225(self):
 249         # Test issue8225 to ensure no doc link appears for xml.etree
 250         result, doc_loc = get_pydoc_text(xml.etree)
 251         self.assertEqual(doc_loc, "", "MODULE DOCS incorrectly includes a link")
 252
 253     def test_not_here(self):
 254         missing_module = "test.i_am_not_here"
 255         result = run_pydoc(missing_module)
 256         expected = missing_pattern % missing_module
 257         self.assertEqual(expected, result,
 258             "documentation for missing module found")
 259
 260     def test_badimport(self):
 261         # This tests the fix for issue 5230, where if pydoc found the module
 262         # but the module had an internal import error pydoc would report no doc
 263         # found.
 264         modname = 'testmod_xyzzy'
 265         testpairs = (
 266             ('i_am_not_here', 'i_am_not_here'),
 267             ('test.i_am_not_here_either', 'i_am_not_here_either'),
 268             ('test.i_am_not_here.neither_am_i', 'i_am_not_here.neither_am_i'),
 269             ('i_am_not_here.{}'.format(modname), 'i_am_not_here.{}'.format(modname)),
 270             ('test.{}'.format(modname), modname),
 271             )
 272
 273         @contextmanager
 274         def newdirinpath(dir):
 275             os.mkdir(dir)
 276             sys.path.insert(0, dir)
 277             yield
 278             sys.path.pop(0)
 279             rmtree(dir)
 280
 281         with newdirinpath(TESTFN), EnvironmentVarGuard() as env:
 282             env['PYTHONPATH'] = TESTFN
 283             fullmodname = os.path.join(TESTFN, modname)
 284             sourcefn = fullmodname + os.extsep + "py"
 285             for importstring, expectedinmsg in testpairs:
 286                 f = open(sourcefn, 'w')
 287                 f.write("import {}\n".format(importstring))
 288                 f.close()
 289                 try:
 290                     result = run_pydoc(modname)
 291                 finally:
 292                     forget(modname)
 293                 expected = badimport_pattern % (modname, expectedinmsg)
 294                 self.assertEqual(expected, result)
 295
 296     def test_input_strip(self):
 297         missing_module = " test.i_am_not_here "
 298         result = run_pydoc(missing_module)
 299         expected = missing_pattern % missing_module.strip()
 300         self.assertEqual(expected, result,
 301             "white space was not stripped from module name "
 302             "or other error output mismatch")
 303
 304     def test_stripid(self):
 305         # test with strings, other implementations might have different repr()
 306         stripid = pydoc.stripid
 307         # strip the id
 308         self.assertEqual(stripid('<function stripid at 0x88dcee4>'),
 309                          '<function stripid>')
 310         self.assertEqual(stripid('<function stripid at 0x01F65390>'),
 311                          '<function stripid>')
 312         # nothing to strip, return the same text
 313         self.assertEqual(stripid('42'), '42')
 314         self.assertEqual(stripid("<type 'exceptions.Exception'>"),
 315                          "<type 'exceptions.Exception'>")
 316
 317
 318 class TestDescriptions(unittest.TestCase):
 319
 320     def test_module(self):
 321         # Check that pydocfodder module can be described
 322         from test import pydocfodder
 323         doc = pydoc.render_doc(pydocfodder)
 324         self.assertIn("pydocfodder", doc)
 325
 326     def test_classic_class(self):
 327         class C: "Classic class"
 328         c = C()
 329         self.assertEqual(pydoc.describe(C), 'class C')
 330         self.assertEqual(pydoc.describe(c), 'instance of C')
 331         expected = 'instance of C in module %s' % __name__
 332         self.assertIn(expected, pydoc.render_doc(c))
 333
 334     def test_class(self):
 335         class C(object): "New-style class"
 336         c = C()
 337
 338         self.assertEqual(pydoc.describe(C), 'class C')
 339         self.assertEqual(pydoc.describe(c), 'C')
 340         expected = 'C in module %s object' % __name__
 341         self.assertIn(expected, pydoc.render_doc(c))
 342
 343
 344 def test_main():
 345     test.test_support.run_unittest(PyDocDocTest,
 346                                    TestDescriptions)
 347
 348 if __name__ == "__main__":
 349     test_main()