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